improve logo escaping (#3511)

* escape logo in make-badge

* 2.2.1 release notes

* tighten up validation of logo param

.buildpacks

@@ -1,2 +0,0 @@
-https://github.com/mojodna/heroku-buildpack-cairo.git
-https://github.com/heroku/heroku-buildpack-nodejs.git

.circleci/config.yml

@@ -1,5 +1,177 @@
 version: 2
 
+main_steps: &main_steps
+  steps:
+    - checkout
+
+    - restore_cache:
+        keys:
+          - v2-dependencies-{{ checksum "package-lock.json" }}
+          # https://github.com/badges/shields/issues/1937
+          - v2-dependencies-
+
+    - run:
+        name: Install dependencies
+        command: npm ci
+
+    - save_cache:
+        paths:
+          - node_modules
+        key: v2-dependencies-{{ checksum "package-lock.json" }}
+
+    - run:
+        name: Linter
+        when: always
+        command: npm run lint
+
+    - run:
+        name: Core tests
+        when: always
+        environment:
+          mocha_reporter: mocha-junit-reporter
+          MOCHA_FILE: junit/core/results.xml
+        command: npm run test:core
+
+    - run:
+        name: Entrypoint tests
+        when: always
+        environment:
+          mocha_reporter: mocha-junit-reporter
+          MOCHA_FILE: junit/entrypoint/results.xml
+        command: npm run test:entrypoint
+
+    - store_test_results:
+        path: junit
+
+    - run:
+        name: 'Prettier check (quick fix: `npm run prettier`)'
+        when: always
+        command: npm run prettier:check
+
+integration_steps: &integration_steps
+  steps:
+    - checkout
+
+    - restore_cache:
+        keys:
+          - v2-dependencies-{{ checksum "package-lock.json" }}
+          # https://github.com/badges/shields/issues/1937
+          - v2-dependencies-
+
+    - run:
+        name: Install dependencies
+        command: npm ci
+
+    - run:
+        name: Integration tests
+        when: always
+        environment:
+          mocha_reporter: mocha-junit-reporter
+          MOCHA_FILE: junit/integration/results.xml
+        command: npm run test:integration
+
+    - store_test_results:
+        path: junit
+
+services_steps: &services_steps
+  steps:
+    - checkout
+
+    - restore_cache:
+        keys:
+          - v2-dependencies-{{ checksum "package-lock.json" }}
+          # https://github.com/badges/shields/issues/1937
+          - v2-dependencies-
+
+    - run:
+        name: Install dependencies
+        command: npm ci
+
+    - run:
+        name: Identify services tagged in the PR title
+        command: npm run test:services:pr:prepare
+
+    - run:
+        name: Run tests for tagged services
+        environment:
+          mocha_reporter: mocha-junit-reporter
+          MOCHA_FILE: junit/services/results.xml
+        command: npm run test:services:pr:run
+
+    - store_test_results:
+        path: junit
+
+run_package_tests: &run_package_tests
+  when: always
+  command: |
+    # https://discuss.circleci.com/t/switch-nodejs-version-on-machine-executor-solved/26675/3
+    set +e
+    export NVM_DIR="/opt/circleci/.nvm"
+    [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
+    nvm install $NODE_VERSION
+    nvm use $NODE_VERSION
+    node --version
+    npm run test:package
+
+package_steps: &package_steps
+  steps:
+    - checkout
+
+    - restore_cache:
+        keys:
+          - v2-dependencies-{{ checksum "package-lock.json" }}
+          # https://github.com/badges/shields/issues/1937
+          - v2-dependencies-
+
+    - run:
+        name: Install dependencies
+        command: |
+          set +e
+          export NVM_DIR="/opt/circleci/.nvm"
+          [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
+          nvm install v12
+          nvm use v12
+          npm install -g npm
+          npm ci
+
+    # Run the package tests on each currently supported node version. See:
+    # https://github.com/badges/shields/blob/master/gh-badges/README.md#node-version-support
+
+    - run:
+        <<: *run_package_tests
+        environment:
+          mocha_reporter: mocha-junit-reporter
+          MOCHA_FILE: junit/gh-badges/v8/results.xml
+          NODE_VERSION: v8
+        name: Run package tests on Node 8
+
+    - run:
+        <<: *run_package_tests
+        environment:
+          mocha_reporter: mocha-junit-reporter
+          MOCHA_FILE: junit/gh-badges/v10/results.xml
+          NODE_VERSION: v10
+        name: Run package tests on Node 10
+
+    - run:
+        <<: *run_package_tests
+        environment:
+          mocha_reporter: mocha-junit-reporter
+          MOCHA_FILE: junit/gh-badges/v11/results.xml
+          NODE_VERSION: v11
+        name: Run package tests on Node 11
+
+    - run:
+        <<: *run_package_tests
+        environment:
+          mocha_reporter: mocha-junit-reporter
+          MOCHA_FILE: junit/gh-badges/v12/results.xml
+          NODE_VERSION: v12
+        name: Run package tests on Node 12
+
+    - store_test_results:
+        path: junit
+
 jobs:
   npm-install:
     docker:
@@ -9,100 +181,44 @@ jobs:
 
       - restore_cache:
           keys:
-          - v2-dependencies-{{ checksum "package.json" }}
-          # fallback to using the latest cache if no exact match is found
-          - v2-dependencies-
+            - v2-dependencies-{{ checksum "package-lock.json" }}
+            # fallback to using the latest cache if no exact match is found
+            - v2-dependencies-
 
       - run:
           name: Install dependencies
-          command: npm install
+          command: npm ci
 
       - save_cache:
           paths:
             - node_modules
-          key: v2-dependencies-{{ checksum "package.json" }}
+          key: v2-dependencies-{{ checksum "package-lock.json" }}
 
   main:
     docker:
       - image: circleci/node:8
-      - image: redis
-    steps:
-      - checkout
 
-      - restore_cache:
-          key: v2-dependencies-{{ checksum "package.json" }}
-          # https://github.com/badges/shields/issues/1937
-          key: v2-dependencies-
-
-      - run:
-          name: Install dependencies
-          command: npm install
-
-      - run:
-          name: Linter
-          when: always
-          command: npm run lint
-
-      - run:
-          name: Server unit tests
-          when: always
-          command: npm run test:js:server
-
-      - run:
-          name: Integration tests
-          when: always
-          command: npm run test:integration
-
-      - run:
-          name: Tests for gh-badges package
-          when: always
-          command: npm run test:js:package
-
-      - run:
-          name: 'Prettier check (quick fix: `npm run prettier`)'
-          when: always
-          command: npm run prettier-check
+    <<: *main_steps
 
   main@node-latest:
     docker:
       - image: circleci/node:latest
+
+    <<: *main_steps
+
+  integration:
+    docker:
+      - image: circleci/node:8
       - image: redis
-    steps:
-      - checkout
 
-      - restore_cache:
-          key: v2-dependencies-{{ checksum "package.json" }}
-          # https://github.com/badges/shields/issues/1937
-          key: v2-dependencies-
+    <<: *integration_steps
 
-      - run:
-          name: Install dependencies
-          command: npm install
+  integration@node-latest:
+    docker:
+      - image: circleci/node:latest
+      - image: redis
 
-      - run:
-          name: Linter
-          when: always
-          command: npm run lint
-
-      - run:
-          name: Server unit tests
-          when: always
-          command: npm run test:js:server
-
-      - run:
-          name: Integration tests
-          when: always
-          command: npm run test:integration
-
-      - run:
-          name: Tests for gh-badges package
-          when: always
-          command: npm run test:js:package
-
-      - run:
-          name: 'Prettier check (quick fix: `npm run prettier`)'
-          when: always
-          command: npm run prettier-check
+    <<: *integration_steps
 
   danger:
     docker:
@@ -111,17 +227,21 @@ jobs:
       - checkout
 
       - restore_cache:
-          key: v2-dependencies-{{ checksum "package.json" }}
-          # https://github.com/badges/shields/issues/1937
-          key: v2-dependencies-
+          keys:
+            - v2-dependencies-{{ checksum "package-lock.json" }}
+            # https://github.com/badges/shields/issues/1937
+            - v2-dependencies-
 
       - run:
           name: Install dependencies
-          command: npm install
+          command: npm ci
 
       - run:
           name: Danger
           when: always
+          environment:
+            # https://github.com/gatsbyjs/gatsby/pull/11555
+            NODE_ENV: test
           command: npm run danger ci
 
   frontend:
@@ -131,129 +251,165 @@ jobs:
       - checkout
 
       - restore_cache:
-          key: v2-dependencies-{{ checksum "package.json" }}
-          # https://github.com/badges/shields/issues/1937
-          key: v2-dependencies-
+          keys:
+            - v2-dependencies-{{ checksum "package-lock.json" }}
+            # https://github.com/badges/shields/issues/1937
+            - v2-dependencies-
 
       - run:
           name: Install dependencies
-          command: npm install
+          command: npm ci
+
+      - run:
+          name: Prepare frontend tests
+          command: npm run defs && npm run features
 
       - run:
           name: Frontend unit tests
-          when: always
-          command: npm run test:js:frontend
+          environment:
+            mocha_reporter: mocha-junit-reporter
+            MOCHA_FILE: junit/frontend/results.xml
+          command: npm run test:frontend
+
+      - store_test_results:
+          path: junit
 
       - run:
           name: Frontend build completes successfully
           when: always
           command: npm run build
 
+  package:
+    machine: true
+
+    <<: *package_steps
+
   services:
     docker:
       - image: circleci/node:8
-    steps:
-      - checkout
 
-      - run:
-          name: Prepare service tests
-          command: |
-            mkdir private
-            echo "{\"gh_token\":\"$GITHUB_TOKEN\"}" > private/secret.json
-
-      - restore_cache:
-          key: v2-dependencies-{{ checksum "package.json" }}
-          # https://github.com/badges/shields/issues/1937
-          key: v2-dependencies-
-
-      - run:
-          name: Install dependencies
-          command: npm install
-
-      - run:
-          name: Identify services tagged in the PR title
-          command: |
-            if [[ ! -z $CI_PULL_REQUEST ]]; then
-              npm run test:services:pr:prepare
-            else
-              echo 'This is not a pull request. Skipping.'
-            fi
-
-      - run:
-          name: Run tests for tagged services
-          command: |
-            if [[ ! -z $CI_PULL_REQUEST ]]; then
-              npm run test:services:pr:run
-            else
-              echo 'This is not a pull request. Skipping.'
-            fi
+    <<: *services_steps
 
   services@node-latest:
     docker:
       - image: circleci/node:latest
+
+    <<: *services_steps
+
+  e2e:
+    docker:
+      - image: cypress/base:8
     steps:
       - checkout
 
-      - run:
-          name: Prepare service tests
-          command: |
-            mkdir private
-            echo "{\"gh_token\":\"$GITHUB_TOKEN\"}" > private/secret.json
-
       - restore_cache:
-          key: v2-dependencies-{{ checksum "package.json" }}
-          # https://github.com/badges/shields/issues/1937
-          key: v2-dependencies-
+          keys:
+            - v2-dependencies-{{ checksum "package-lock.json" }}
+            # https://github.com/badges/shields/issues/1937
+            - v2-dependencies-
 
       - run:
           name: Install dependencies
-          command: npm install
+          command: npm ci
 
       - run:
-          name: Identify services tagged in the PR title
-          command: |
-            if [[ ! -z $CI_PULL_REQUEST ]]; then
-              npm run test:services:pr:prepare
-            else
-              echo 'This is not a pull request. Skipping.'
-            fi
+          name: Frontend build
+          command: GATSBY_BASE_URL=http://localhost:8080 npm run build
 
       - run:
-          name: Run tests for tagged services
-          command: |
-            if [[ ! -z $CI_PULL_REQUEST ]]; then
-              npm run test:services:pr:run
-            else
-              echo 'This is not a pull request. Skipping.'
-            fi
+          name: Run tests
+          environment:
+            CYPRESS_REPORTER: junit
+            MOCHA_FILE: junit/e2e/results.xml
+          command: npm run e2e-on-build
+
+      - store_test_results:
+          path: junit
+
+      - store_artifacts:
+          path: cypress/videos
+
+      - store_artifacts:
+          path: cypress/screenshots
 
 workflows:
   version: 2
 
   on-commit:
     jobs:
-      - npm-install:
+      - main:
           filters:
             branches:
               ignore: gh-pages
-      - main:
-          requires:
-            - npm-install
       - main@node-latest:
-          requires:
-            - npm-install
-      - frontend:
-          requires:
-            - npm-install
-      - services:
-          requires:
-            - npm-install
-      - services@node-latest:
-          requires:
-            - npm-install
-      - danger:
-          requires:
-            - npm-install
           filters:
             branches:
-              ignore: /dependabot\/.*/
+              ignore: gh-pages
+      - integration@node-latest:
+          filters:
+            branches:
+              ignore: gh-pages
+      - frontend:
+          filters:
+            branches:
+              ignore: gh-pages
+      - package:
+          filters:
+            branches:
+              ignore: gh-pages
+      - services:
+          filters:
+            branches:
+              ignore:
+                - master
+                - gh-pages
+      - services@node-latest:
+          filters:
+            branches:
+              ignore:
+                - master
+                - gh-pages
+      - danger:
+          filters:
+            branches:
+              ignore:
+                - master
+                - gh-pages
+                - /dependabot\/.*/
+      - e2e:
+          filters:
+            branches:
+              ignore: gh-pages
+  # on-commit-with-cache:
+  #   jobs:
+  #     - npm-install:
+  #         filters:
+  #           branches:
+  #             ignore: gh-pages
+  #     - main:
+  #         requires:
+  #           - npm-install
+  #     - main@node-latest:
+  #         requires:
+  #           - npm-install
+  #     - frontend:
+  #         requires:
+  #           - npm-install
+  #     - services:
+  #         requires:
+  #           - npm-install
+  #         filters:
+  #           branches:
+  #             ignore: master
+  #     - services@node-latest:
+  #         requires:
+  #           - npm-install
+  #         filters:
+  #           branches:
+  #             ignore: master
+  #     - danger:
+  #         requires:
+  #           - npm-install
+  #         filters:
+  #           branches:
+  #             ignore: /dependabot\/.*/

.dependabot/config.yml

@@ -0,0 +1,11 @@
+version: 1
+update_configs:
+  # shields.io dependencies
+  - package_manager: 'javascript'
+    directory: '/'
+    update_schedule: 'weekly'
+
+  # gh-badges package dependencies
+  - package_manager: 'javascript'
+    directory: '/gh-badges'
+    update_schedule: 'weekly'

.dockerignore

@@ -2,3 +2,7 @@ node_modules/
 shields.env
 .git/
 .gitignore
+.vscode/
+
+# Improve layer cacheability.
+Dockerfile

.eslintignore

@@ -1,3 +1,5 @@
 /build
 /coverage
 /__snapshots__
+/public
+gh-badges/node_modules/

.eslintrc-frontend.yml

@@ -3,22 +3,26 @@ env:
 
 plugins:
   - import
+  - react-hooks
 
-parser: "babel-eslint"
+parser: 'babel-eslint'
 
 parserOptions:
-  sourceType: "module"
+  sourceType: 'module'
 
 extends:
-  - "standard-jsx"
-  - "standard-react"
-  - "./.eslintrc.yml"
+  - 'standard-jsx'
+  - 'standard-react'
+  - './.eslintrc.yml'
 
 settings:
   react:
-    version: "16.4"
+    version: '16.4'
 
 rules:
-  no-console: "error"
+  no-console: 'error'
 
-  import/extensions: ["error", "never", { "json": "always" }]
+  import/extensions: ['error', 'never', { 'json': 'always', 'yml': 'always' }]
+  react/jsx-sort-props: 'error'
+  react-hooks/rules-of-hooks: 'error'
+  react-hooks/exhaustive-deps: 'error'

.eslintrc.yml

@@ -9,41 +9,76 @@ env:
 parserOptions:
   # Override eslint-config-standard, which incorrectly sets this to "module",
   # though that setting is only for ES6 modules, not CommonJS modules.
-  sourceType: "script"
+  sourceType: 'script'
+
+overrides:
+  - files:
+      - gatsby-browser.js
+    parserOptions:
+      sourceType: 'module'
+  - files:
+      - 'core/base-service/**/*.js'
+      - 'services/**/*.js'
+    rules:
+      sort-class-members/sort-class-members:
+        [
+          'error',
+          {
+            order:
+              [
+                'name',
+                'category',
+                'isDeprecated',
+                'route',
+                'examples',
+                '_cacheLength',
+                'defaultBadgeData',
+                'render',
+                'constructor',
+                'fetch',
+                'transform',
+                'handle',
+              ],
+          },
+        ]
 
 plugins:
   - mocha
   - no-extension-in-require
-  - "chai-friendly"
+  - chai-friendly
+  - sort-class-members
 
 rules:
   # Disable some rules from eslint:recommended.
-  no-console: "off"
-  no-empty: ["error", { "allowEmptyCatch": true }]
+  no-console: 'off'
+  no-empty: ['error', { 'allowEmptyCatch': true }]
   # Allow unused parameters. In callbacks, removing them seems to obscure
   # what the functions are doing.
-  no-unused-vars: ["error", {"args": "none"}]
+  no-unused-vars: ['error', { 'args': 'none' }]
 
   # These should be disabled by eslint-config-prettier, but are not.
-  spaced-comment: "off"
-  standard/object-curly-even-spacing: "off"
-  one-var: "off"
+  spaced-comment: 'off'
+  standard/object-curly-even-spacing: 'off'
+  one-var: 'off'
 
   # Shields additions.
-  no-var: "error"
-  prefer-const: "error"
-  strict: "error"
-  arrow-body-style: ["error", "as-needed"]
-  no-extension-in-require/main: "error"
-  object-shorthand: ["error", "properties"]
-  prefer-template: "error"
-  promise/prefer-await-to-then: "error"
+  no-var: 'error'
+  prefer-const: 'error'
+  strict: 'error'
+  arrow-body-style: ['error', 'as-needed']
+  no-extension-in-require/main: 'error'
+  object-shorthand: ['error', 'properties']
+  prefer-template: 'error'
+  promise/prefer-await-to-then: 'error'
+  func-style: ['error', 'declaration', { 'allowArrowFunctions': true }]
+  new-cap: ['error', { 'capIsNew': true }]
+  import/order: ['error', { 'newlines-between': 'never' }]
 
   # Mocha-related.
-  mocha/no-exclusive-tests: "error"
-  mocha/no-mocha-arrows: "error"
-  mocha/prefer-arrow-callback: "error"
+  mocha/no-exclusive-tests: 'error'
+  mocha/no-mocha-arrows: 'error'
+  mocha/prefer-arrow-callback: 'error'
 
   # Chai friendly.
-  no-unused-expressions: "off"
-  chai-friendly/no-unused-expressions: "error"
+  no-unused-expressions: 'off'
+  chai-friendly/no-unused-expressions: 'error'

.github/FUNDING.yml

@@ -0,0 +1 @@
+open_collective: shields

.github/ISSUE_TEMPLATE/1_Bug_report.md

@@ -1,26 +1,28 @@
 ---
 name: 🐛 Bug Report
 about: Report errors and problems
-
 ---
 
 Are you experiencing an issue with...
- - [ ] [shields.io](https://shields.io/#/)
- - [ ] My own instance
- - [ ] [gh-badges NPM package](https://www.npmjs.com/package/gh-badges)
+
+- [ ] [shields.io](https://shields.io/#/)
+- [ ] My own instance
+- [ ] [gh-badges NPM package](https://www.npmjs.com/package/gh-badges)
 
 :beetle: **Description**
+
 <!-- A clear and concise description of the problem. -->
 
 :link: **Link to the badge**
+
 <!--
 If you are reporting a problem with a specific badge on shields.io,
 provide a link to a badge demonstrating the error
 -->
 
 :bulb: **Possible Solution**
-<!--- Optional: only if you have suggestions on a fix/reason for the bug -->
 
+<!--- Optional: only if you have suggestions on a fix/reason for the bug -->
 
 <!-- Love Shields? Please consider donating $10 to sustain our activities:
 👉  https://opencollective.com/shields -->

.github/ISSUE_TEMPLATE/2_Failing_service_test.md

@@ -0,0 +1,35 @@
+---
+name: 💚 Failing service test
+about: Note failing service tests
+---
+
+:clock11: **When did the problem start?**
+
+<!-- Indicate when the problem started -->
+
+:camera: **Live badge**
+
+<!-- Provide a link to the live badge in plain text and markdown.  -->
+
+![]( url goes here )
+
+:wrench: **Is the live badge working?**
+
+<!-- Indicate whether or not the live badge is working. -->
+
+:link: **CircleCI link**
+
+<!-- Provide a link to the failing test in CircleCI. -->
+
+:beetle: **Stack trace**
+
+```
+<!-- Provide the complete stack trace from the CircleCI test summary. -->
+```
+
+:bulb: **Possible solution**
+
+<!--- Optional: only if you have suggestions on a fix/reason for the bug -->
+
+<!-- Love Shields? Please consider donating $10 to sustain our activities:
+👉  https://opencollective.com/shields -->

.github/ISSUE_TEMPLATE/3_Badge_request.md

@@ -1,10 +1,10 @@
 ---
 name: 💡 Badge Request
 about: Ideas for new badges
-
 ---
 
 :clipboard: **Description**
+
 <!--
 A clear and concise description of the new badge.
 
@@ -15,6 +15,7 @@ A clear and concise description of the new badge.
 -->
 
 :link: **Data**
+
 <!--
 Where can we get the data from?
 
@@ -23,6 +24,13 @@ Where can we get the data from?
 - Link to the API documentation.
 -->
 
+:microphone: **Motivation**
+
+<!--
+Please explain why this feature should be implemented and how it would be used.
+
+- What is the specific use case?
+-->
 
 <!-- Love Shields? Please consider donating $10 to sustain our activities:
 👉  https://opencollective.com/shields -->

.github/ISSUE_TEMPLATE/4_Feature_request.md

@@ -1,12 +1,11 @@
 ---
 name: 💡 Feature Request
 about: Ideas for other new features or improvements
-
 ---
 
 :clipboard: **Description**
-<!-- A clear and concise description of the new feature. -->
 
+<!-- A clear and concise description of the new feature. -->
 
 <!-- Love Shields? Please consider donating $10 to sustain our activities:
 👉  https://opencollective.com/shields -->

.github/ISSUE_TEMPLATE/5_Support_question.md

@@ -1,10 +1,10 @@
 ---
 name: ❓ Support Question
 about: Ask a question about shields.io
-
 ---
 
 :question: **Question**
+
 <!--
 Ask your question clearly and concisely.
 
@@ -12,6 +12,5 @@ Ask your question clearly and concisely.
 is also a great place to ask questions and get help
 -->
 
-
 <!-- Love Shields? Please consider donating $10 to sustain our activities:
 👉  https://opencollective.com/shields -->

.gitignore

@@ -17,6 +17,9 @@ Desktop.ini
 ._*
 Thumbs.db
 
+# Visual Studio Code User Settings
+.vscode/settings.json
+
 # eclipse
 .project
 .settings
@@ -92,3 +95,18 @@ typings/
 .next
 badge-examples.json
 supported-features.json
+service-definitions.yml
+
+# Local runtime configuration.
+/config/local*.yml
+
+# Template for the local runtime configuration.
+!/config/local*.template.yml
+
+# Gatsby
+/.cache
+/public
+
+# Cypress
+/cypress/videos/
+/cypress/screenshots/

.gitpod.yml

@@ -0,0 +1,5 @@
+ports:
+  - port: 8080
+tasks:
+  - init: npm ci && npm run build
+    command: node server 8080 0.0.0.0

.mocharc-frontend.yml

@@ -0,0 +1,6 @@
+reporter: mocha-env-reporter
+require:
+  - '@babel/polyfill'
+  - '@babel/register'
+  - mocha-yaml-loader
+  - frontend/mocha-ignore-pngs

.mocharc.yml

@@ -0,0 +1 @@
+reporter: mocha-env-reporter

.nowignore

@@ -0,0 +1,30 @@
+*
+!frontend/
+!gh-badges/
+!lib/
+!core/
+!logo/
+!pages/
+!public/
+!templates/
+!services/
+!package-lock.json
+!/*.js
+!scripts/export-*.js
+!config/
+config/local*.yml
+*.spec.js
+*~
+.env
+.circleci
+.github
+.vscode
+__snapshots__
+.buildpacks
+.eslint*
+.editorconfig
+.nycrc*
+.gitpod*
+.prettier*
+CONTRIBUTING.md
+Dockerfile

.nycrc-frontend.json

@@ -0,0 +1,10 @@
+{
+  "reporter": ["lcov"],
+  "all": false,
+  "silent": true,
+  "clean": false,
+  "sourceMap": false,
+  "instrument": false,
+  "include": ["frontend/**/*.js"],
+  "exclude": ["**/*.spec.js", "**/mocha-*.js"]
+}

.nycrc.json

@@ -1,16 +1,24 @@
 {
   "reporter": ["lcov"],
   "all": true,
+  "silent": true,
+  "clean": false,
   "exclude": [
     "**/*.spec.js",
     "**/*.integration.js",
+    "**/test-helpers.js",
+    "**/*-test-helpers.js",
+    "**/*-fixtures.js",
     "dangerfile.js",
+    "gatsby-*.js",
+    "core/service-test-runner",
     "services/**/*.tester.js",
-    "test-fixtures",
+    "services/test-validators.js",
+    "services/tester.js",
+    "core/base-service/loader-test-fixtures",
     "scripts",
     "coverage",
-    "build"
-  ],
-  "silent": true,
-  "clean": false
+    "build",
+    ".github"
+  ]
 }

.prettierignore

@@ -2,7 +2,13 @@ package.json
 package-lock.json
 /__snapshots__
 /.next
+/.cache
 /build
+/public
 /coverage
-**/*.md
 private/*.json
+/.nyc_output
+analytics.json
+gh-badges/templates/default-template.json
+supported-features.json
+service-definitions.yml

.prettierrc.yml

@@ -2,3 +2,4 @@ semi: false
 singleQuote: true
 trailingComma: es5
 bracketSpacing: true
+endOfLine: lf

.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "esbenp.prettier-vscode",
+    "EditorConfig.EditorConfig",
+    "dbaeumer.vscode-eslint"
+  ]
+}

.vscode/launch.json

@@ -0,0 +1,13 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "attach",
+      "name": "Node: Nodemon",
+      "processId": "${command:PickProcess}",
+      "restart": true,
+      "protocol": "inspector"
+    }
+  ]
+}

CONTRIBUTING.md

@@ -1,12 +1,9 @@
-Contributing to Shields
-=======================
+# Contributing to Shields
 
 Shields is a community project. We invite your participation through
 financial contributions, issues, and pull requests!
 
-
-Ways you can help
------------------
+## Ways you can help
 
 ### Financial contributions
 
@@ -38,7 +35,7 @@ wonderful side effect of making the code more readable and therefore more
 approachable. It's also a great way to teach and learn. Feel free to jump in!
 Be welcoming, appreciative, and helpful. You can perform first reviews of
 simple changes, like badge additions. These are usually tagged with
-[service badge][service badge PR tag].
+[service badge][service badge pr tag].
 
 Please review [these impeccable guidelines][code review guidelines].
 
@@ -48,8 +45,8 @@ have questions about contributing to Shields, or using it for their projects.
 Feel free to reach out to one of the [maintainers][]
 if you need help getting started.
 
-[service badge PR tag]: https://github.com/badges/shields/pulls?q=is%3Apr+is%3Aopen+label%3Aservice-badge
-[code review guidelines]: http://amyciavolino.com/assets/MindfulCommunicationInCodeReviews.pdf
+[service badge pr tag]: https://github.com/badges/shields/pulls?q=is%3Apr+is%3Aopen+label%3Aservice-badge
+[code review guidelines]: https://kickstarter.engineering/a-guide-to-mindful-communication-in-code-reviews-48aab5282e5e
 [issues]: https://github.com/badges/shields/issues
 [chat room]: https://discordapp.com/invite/HjJCwm5
 [maintainers]: https://github.com/badges/shields#project-leaders
@@ -72,10 +69,9 @@ don't see it, feel free to [open a new issue][open an issue].
 
 Feel free to star the repository. This will help increase the visibility of the project, therefore attracting more users and contributors to Shields!
 
-We're also asking for [one-time $10 donations](https://opencollective.com/shields) from developers who use and love Shields, please spread the word!
+We're also asking for [one-time \$10 donations](https://opencollective.com/shields) from developers who use and love Shields, please spread the word!
 
-Getting help
-------------
+## Getting help
 
 There are three places to get help:
 
@@ -87,21 +83,16 @@ There are three places to get help:
 
 [tutorial]: doc/TUTORIAL.md
 
-
-Badge guidelines
-----------------
+## Badge guidelines
 
 - Shields.io hosts integrations for services which are primarily
   used by developers or which are widely used by developers
-- The left-hand side of a badge should not advertise. It should be a lowercase *noun*
+- The left-hand side of a badge should not advertise. It should be a lowercase _noun_
   succinctly describing the meaning of the right-hand side.
-- Query parameters must be *declared by the service*. See `request-handler.js`.
-- Except for badges using the `social` style, logos should be *turned off by
-  default*.
+- Except for badges using the `social` style, logos should be _turned off by
+  default_.
 
-
-Badge URLs
-----------
+## Badge URLs
 
 - The format of new badges should be of the form
   `/SERVICE/NOUN/PARAMETERS/QUALIFIERS.format`. For instance,
@@ -111,14 +102,12 @@ Badge URLs
   `/SERVICE/SCHEME/HOST/NOUN/PARAMETERS/QUALIFIERS.format`. For instance,
   `/discourse/https/discourse.example.com/topics.svg`.
 
-
-Coding guidelines
------------------
+## Coding guidelines
 
 ### Prettier
 
 This project formats its source code using Prettier. The most enjoyable way to
-use Prettier is to let is format code for you when you save. You can [integrate
+use Prettier is to let it format code for you when you save. You can [integrate
 it into your editor][integrate prettier].
 
 Whether you integrate it into your editor or not, a pre-commit hook will run
@@ -145,21 +134,8 @@ start the server automatically.
 
 ### Code organization
 
-Function declarations are placed in `lib/`, not directly in `server.js`.
+There is a [High-level code walkthrough](doc/code-walkthrough.md) describing the layout of the project.
 
+### Logos
 
-Logos
------
-
-We support a wide range of logos via [SimpleIcons][] and encourage you to [contribute logos to that project][simple-icons github].
-
-We also accept logos directly. In general, we do this only when we have a corresponding badge on the homepage, (e.g. the Eclipse logo because we support service badges for the Eclipse Marketplace). We may also approve logos for tools widely used by developers (e.g. our Slack logo). We will happily consider all requests, but don't expect systematic approval, it's at the discretion of the maintainers.
-
-Please minimize checked-in SVG files through [SVGO][]. You can use [svgomg][].
-
-If you want to use a logo that does not meet our guidelines, a custom logo can be passed in a URL parameter by base64 encoding it. For example this badge ![](https://img.shields.io/badge/play-station-blue.svg?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZlcnNpb249IjEiIHdpZHRoPSI2MDAiIGhlaWdodD0iNjAwIj48cGF0aCBkPSJNMTI5IDExMWMtNTUgNC05MyA2Ni05MyA3OEwwIDM5OGMtMiA3MCAzNiA5MiA2OSA5MWgxYzc5IDAgODctNTcgMTMwLTEyOGgyMDFjNDMgNzEgNTAgMTI4IDEyOSAxMjhoMWMzMyAxIDcxLTIxIDY5LTkxbC0zNi0yMDljMC0xMi00MC03OC05OC03OGgtMTBjLTYzIDAtOTIgMzUtOTIgNDJIMjM2YzAtNy0yOS00Mi05Mi00MmgtMTV6IiBmaWxsPSIjZmZmIi8+PC9zdmc+) could be generated by calling: https://img.shields.io/badge/play-station-blue.svg?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZlcnNpb249IjEiIHdpZHRoPSI2MDAiIGhlaWdodD0iNjAwIj48cGF0aCBkPSJNMTI5IDExMWMtNTUgNC05MyA2Ni05MyA3OEwwIDM5OGMtMiA3MCAzNiA5MiA2OSA5MWgxYzc5IDAgODctNTcgMTMwLTEyOGgyMDFjNDMgNzEgNTAgMTI4IDEyOSAxMjhoMWMzMyAxIDcxLTIxIDY5LTkxbC0zNi0yMDljMC0xMi00MC03OC05OC03OGgtMTBjLTYzIDAtOTIgMzUtOTIgNDJIMjM2YzAtNy0yOS00Mi05Mi00MmgtMTV6IiBmaWxsPSIjZmZmIi8+PC9zdmc+
-
-[simpleicons]: https://simpleicons.org/
-[simple-icons github]: https://github.com/simple-icons/simple-icons
-[SVGO]: https://github.com/svg/svgo
-[svgomg]: https://jakearchibald.github.io/svgomg/
+We have [documentation for logo usage](doc/logos.md) which includes [contribution guidance](doc/logos.md#contributing-logos)

Dockerfile

@@ -1,4 +1,4 @@
-FROM node:8.9.4-alpine
+FROM node:8-alpine
 
 RUN apk add --no-cache gettext imagemagick librsvg git
 
@@ -6,16 +6,21 @@ RUN mkdir -p /usr/src/app
 RUN mkdir /usr/src/app/private
 WORKDIR /usr/src/app
 
-ARG NODE_ENV
-ENV NODE_ENV $NODE_ENV
-COPY package.json /usr/src/app/
-RUN npm install
+COPY package.json package-lock.json /usr/src/app/
+# Without the gh-badges package.json and CLI script in place, `npm ci` will fail.
+COPY gh-badges /usr/src/app/gh-badges/
+
+# We need dev deps to build the front end.
+RUN NODE_ENV=development npm ci
+
 COPY . /usr/src/app
 RUN npm run build
 RUN npm prune --production
 RUN npm cache clean --force
 
-CMD envsubst < secret.tpl.json > ./private/secret.json \
- && node server
+# Run the server using production configs.
+ENV NODE_ENV production
+
+CMD node server
 
 EXPOSE 80

Makefile

@@ -8,10 +8,7 @@ FRONTEND_TMP=${TMPDIR}shields-frontend-deploy
 # pushing secrets to GitHub, this branch is configured to reject pushes.
 WORKING_BRANCH=server-deploy-working-branch
 
-all: website test
-
-website:
-	LONG_CACHE=false npm run build
+all: test
 
 deploy: deploy-s0 deploy-s1 deploy-s2 clean-server-deploy deploy-gh-pages deploy-gh-pages-clean
 
@@ -19,18 +16,19 @@ deploy-s0: prepare-server-deploy push-s0
 deploy-s1: prepare-server-deploy push-s1
 deploy-s2: prepare-server-deploy push-s2
 
-prepare-server-deploy: website
+prepare-server-deploy:
 	# Ship a copy of the front end to each server for debugging.
 	# https://github.com/badges/shields/issues/1220
+	INCLUDE_DEV_PAGES=false \
+		npm run build
 	rm -rf ${SERVER_TMP}
 	git worktree prune
 	git worktree add -B ${WORKING_BRANCH} ${SERVER_TMP}
-	cp -r build ${SERVER_TMP}
-	git -C ${SERVER_TMP} add -f build/
+	cp -r public ${SERVER_TMP}
+	git -C ${SERVER_TMP} add -f public/
 	git -C ${SERVER_TMP} commit --no-verify -m '[DEPLOY] Add frontend for debugging'
-	mkdir -p ${SERVER_TMP}/private
-	cp private/secret-production.json ${SERVER_TMP}/private/secret.json
-	git -C ${SERVER_TMP} add -f private/secret.json
+	cp config/local-shields-io-production.yml ${SERVER_TMP}/config/
+	git -C ${SERVER_TMP} add -f config/local-shields-io-production.yml
 	git -C ${SERVER_TMP} commit --no-verify -m '[DEPLOY] MUST NOT BE ON GITHUB'
 
 clean-server-deploy:
@@ -49,15 +47,13 @@ push-s2:
 deploy-gh-pages:
 	rm -rf ${FRONTEND_TMP}
 	git worktree prune
-	LONG_CACHE=true \
-		BASE_URL=https://img.shields.io \
-		NEXT_ASSET_PREFIX=https://shields.io \
+	GATSBY_BASE_URL=https://img.shields.io \
+		INCLUDE_DEV_PAGES=false \
 		npm run build
 	git worktree add -B gh-pages ${FRONTEND_TMP}
 	git -C ${FRONTEND_TMP} ls-files | xargs git -C ${FRONTEND_TMP} rm
 	git -C ${FRONTEND_TMP} commit --no-verify -m '[DEPLOY] Completely clean the index'
-	cp -r build/* ${FRONTEND_TMP}
-	cp favicon.png ${FRONTEND_TMP}
+	cp -r public/* ${FRONTEND_TMP}
 	echo shields.io > ${FRONTEND_TMP}/CNAME
 	touch ${FRONTEND_TMP}/.nojekyll
 	git -C ${FRONTEND_TMP} add .
@@ -68,17 +64,7 @@ deploy-gh-pages-clean:
 	rm -rf ${FRONTEND_TMP}
 	git worktree prune
 
-deploy-heroku:
-	git add -f private/secret.json build/
-	git commit --no-verify -m'MUST NOT BE ON GITHUB'
-	git push -f heroku HEAD:master
-	git reset HEAD~1
-	(git checkout -B gh-pages && \
-	git merge master && \
-	git push -f origin gh-pages:gh-pages) || git checkout master
-	git checkout master
-
 test:
 	npm test
 
-.PHONY: all website deploy prepare-server-deploy clean-server-deploy deploy-s0 deploy-s1 deploy-s2 push-s0 push-s1 push-s2 deploy-gh-pages deploy-gh-pages-clean deploy-heroku setup redis test
+.PHONY: all deploy prepare-server-deploy clean-server-deploy deploy-s0 deploy-s1 deploy-s2 push-s0 push-s1 push-s2 deploy-gh-pages deploy-gh-pages-clean deploy-heroku setup redis test

Procfile

@@ -1 +1 @@
-web: node server
+web: npm run start:server:prod

README.md

@@ -1,27 +1,30 @@
 <p align="center">
-    <img src="https://rawgit.com/badges/shields/master/static/logo.svg"
+    <img src="./frontend/images/logo.svg"
         height="130">
 </p>
 <p align="center">
+    <a href="https://github.com/badges/shields/graphs/contributors" alt="Contributors">
+        <img src="https://img.shields.io/github/contributors/badges/shields.svg" /></a>
     <a href="#backers" alt="Backers on Open Collective">
-        <img src="https://opencollective.com/shields/backers/badge.svg" /></a>
+        <img src="https://img.shields.io/opencollective/backers/shields.svg" /></a>
     <a href="#sponsors" alt="Sponsors on Open Collective">
-        <img src="https://opencollective.com/shields/sponsors/badge.svg" /></a>
+        <img src="https://img.shields.io/opencollective/sponsors/shields.svg" /></a>
+    <a href="https://github.com/badges/shields/pulse" alt="Activity">
+        <img src="https://img.shields.io/github/commit-activity/m/badges/shields.svg" /></a>
     <a href="https://circleci.com/gh/badges/shields/tree/master">
-        <img src="https://img.shields.io/circleci/project/github/badges/shields/master.svg"
-            alt="build status"></a>
+        <img src="https://img.shields.io/circleci/project/github/badges/shields/master.svg" alt="build status"></a>
     <a href="https://circleci.com/gh/badges/daily-tests">
-        <img src="https://img.shields.io/circleci/project/github/badges/daily-tests.svg?label=daily%20tests"
-            alt="daily build status"></a>
+        <img src="https://img.shields.io/circleci/project/github/badges/daily-tests.svg?label=service%20tests"
+            alt="service-test status"></a>
     <a href="https://coveralls.io/github/badges/shields">
         <img src="https://img.shields.io/coveralls/github/badges/shields.svg"
             alt="coverage"></a>
+    <a href="https://lgtm.com/projects/g/badges/shields/alerts/">
+        <img src="https://img.shields.io/lgtm/alerts/g/badges/shields.svg"
+            alt="Total alerts"/></a>
     <a href="https://github.com/badges/shields/compare/gh-pages...master">
         <img src="https://img.shields.io/github/commits-since/badges/shields/gh-pages.svg?label=commits%20to%20be%20deployed"
             alt="commits to be deployed"></a>
-    <a href="https://lgtm.com/projects/g/badges/shields/alerts/">
-        <img src="https://img.shields.io/lgtm/alerts/g/badges/shields.svg?logo=lgtm&logoWidth=18"
-            alt="Total alerts"/></a>
     <a href="https://discord.gg/HjJCwm5">
         <img src="https://img.shields.io/discord/308323056592486420.svg?logo=discord"
             alt="chat on Discord"></a>
@@ -39,12 +42,11 @@ Every month it serves over 470 million images.
 
 This repo hosts:
 
-* The [Shields.io][shields.io] frontend and server code
-* An [NPM library for generating badges][gh-badges]
-    * [documentation][gh-badges-docs]
-    * [changelog][gh-badges-changelog]
-* The [badge design specification][badge-spec]
-
+- The [Shields.io][shields.io] frontend and server code
+- An [NPM library for generating badges][gh-badges]
+  - [documentation][gh-badges-docs]
+  - [changelog][gh-badges-changelog]
+- The [badge design specification][badge-spec]
 
 [shields.io]: https://shields.io/
 [gh-badges]: https://www.npmjs.com/package/gh-badges
@@ -52,20 +54,18 @@ This repo hosts:
 [gh-badges-docs]: https://github.com/badges/shields/tree/master/gh-badges/README.md
 [gh-badges-changelog]: https://github.com/badges/shields/tree/master/gh-badges/CHANGELOG.md
 
+## Examples
 
-Examples
---------
-
-* code coverage percentage: ![coverage](https://img.shields.io/badge/coverage-80%25-yellowgreen.svg?maxAge=2592000)
-* stable release version: ![version](https://img.shields.io/badge/version-1.2.3-blue.svg?maxAge=2592000)
-* package manager release: ![gem](https://img.shields.io/badge/gem-2.2.0-blue.svg?maxAge=2592000)
-* status of third-party dependencies: ![dependencies](https://img.shields.io/badge/dependencies-out%20of%20date-orange.svg?maxAge=2592000)
-* static code analysis grade: ![codacy](https://img.shields.io/badge/codacy-B-green.svg?maxAge=2592000)
-* [SemVer](https://semver.org/) version observance: ![semver](https://img.shields.io/badge/semver-2.0.0-blue.svg?maxAge=2592000)
-* amount of [Liberapay](https://liberapay.com/) donations per week: ![receives](https://img.shields.io/badge/receives-2.00%20USD%2Fweek-yellow.svg?maxAge=2592000)
-* Python package downloads: ![downloads](https://img.shields.io/badge/downloads-13k%2Fmonth-brightgreen.svg?maxAge=2592000)
-* Chrome Web Store extension rating: ![rating](https://img.shields.io/badge/rating-★★★★☆-brightgreen.svg?maxAge=2592000)
-* [Uptime Robot](https://uptimerobot.com) percentage: ![uptime](https://img.shields.io/badge/uptime-100%25-brightgreen.svg?maxAge=2592000)
+- code coverage percentage: ![coverage](https://img.shields.io/badge/coverage-80%25-yellowgreen.svg?cacheSeconds=2592000)
+- stable release version: ![version](https://img.shields.io/badge/version-1.2.3-blue.svg?cacheSeconds=2592000)
+- package manager release: ![gem](https://img.shields.io/badge/gem-2.2.0-blue.svg?cacheSeconds=2592000)
+- status of third-party dependencies: ![dependencies](https://img.shields.io/badge/dependencies-out%20of%20date-orange.svg?cacheSeconds=2592000)
+- static code analysis grade: ![codacy](https://img.shields.io/badge/codacy-B-green.svg?cacheSeconds=2592000)
+- [SemVer](https://semver.org/) version observance: ![semver](https://img.shields.io/badge/semver-2.0.0-blue.svg?cacheSeconds=2592000)
+- amount of [Liberapay](https://liberapay.com/) donations per week: ![receives](https://img.shields.io/badge/receives-2.00%20USD%2Fweek-yellow.svg?cacheSeconds=2592000)
+- Python package downloads: ![downloads](https://img.shields.io/badge/downloads-13k%2Fmonth-brightgreen.svg?cacheSeconds=2592000)
+- Chrome Web Store extension rating: ![rating](https://img.shields.io/badge/rating-★★★★☆-brightgreen.svg?cacheSeconds=2592000)
+- [Uptime Robot](https://uptimerobot.com) percentage: ![uptime](https://img.shields.io/badge/uptime-100%25-brightgreen.svg?cacheSeconds=2592000)
 
 [Make your own badges!][custom badges]
 (Quick example: `https://img.shields.io/badge/left-right-f39f37.svg`)
@@ -74,9 +74,7 @@ Browse a [complete list of badges][shields.io].
 
 [custom badges]: http://shields.io/#your-badge
 
-
-Contributing
-------------
+## Contributing
 
 Shields is a community project. We invite your participation through issues
 and pull requests! You can peruse the [contributing guidelines][contributing].
@@ -94,23 +92,35 @@ You can read a [tutorial on how to add a badge][tutorial].
 [tutorial]: doc/TUTORIAL.md
 [contributing]: CONTRIBUTING.md
 
-
-Development
------------
+## Development
 
 1. Install Node 8 or later. You can use the [package manager][] of your choice.
-   Tests need to pass in Node 8 and 9.
+   Tests need to pass in Node 8 and 10.
 2. Clone this repository.
-3. Run `npm install` to install the dependencies.
-4. Run `npm run build` to build the frontend.
-5. Run `npm start` to start the server.
-6. Open `http://[::]:8080/` to view the home page.
+3. Run `npm ci` to install the dependencies.
+4. Run `npm start` to start the badge server and the frontend dev server.
+5. Open `http://localhost:3000/` to view the frontend.
 
-To generate the frontend using production cache settings &ndash; that is,
-badge preview URIs with `maxAge` &ndash; run `LONG_CACHE=true npm run build`.
+When server source files change, the badge server should automatically restart
+itself (using [nodemon][]). When the frontend files change, the frontend dev
+server (`gatsby dev`) should also automatically reload. However the badge
+definitions are built only before the server first starts. To regenerate those,
+either run `npm run defs` or manually restart the server.
 
-To analyze the frontend bundle, run `npm install webpack-bundle-analyzer` and
-then `ANALYZE=true npm start`.
+To debug a badge from the command line, run `npm run badge -- /npm/v/nock.svg`.
+It also works with full URLs like
+`npm run badge -- https://img.shields.io/npm/v/nock.svg`.
+
+Use `npm run debug:server` to start server in debug mode.
+[This recipe][nodemon debug] shows how to debug Node.js application in [VS Code][].
+
+Shields has experimental support for [Gitpod Beta][gitpod], a pre-configured development
+environment that runs in your browser. To use Gitpod, click the button below and
+sign in with GitHub. Gitpod also offers a browser add-on, though it is not required.
+Please report any Gitpod bugs, questions, or suggestions in issue
+[#2772](https://github.com/badges/shields/issues/2772).
+
+[![Edit with Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/badges/shields)
 
 [Snapshot tests][] ensure we don't inadvertently make changes that affect the
 SVG or JSON output. When deliberately changing the output, run
@@ -122,23 +132,24 @@ The server can be configured to use [Sentry][] ([configuration][sentry configura
 Daily tests, including a full run of the service tests and overall code coverage, are run via [badges/daily-tests][daily-tests].
 
 [package manager]: https://nodejs.org/en/download/package-manager/
+[gitpod]: https://www.gitpod.io/
 [snapshot tests]: https://glebbahmutov.com/blog/snapshot-testing/
-[Prometheus]: https://prometheus.io/
+[prometheus]: https://prometheus.io/
 [prometheus configuration]: doc/self-hosting.md#prometheus
-[Sentry]: https://sentry.io/
+[sentry]: https://sentry.io/
 [sentry configuration]: doc/self-hosting.md#sentry
 [daily-tests]: https://github.com/badges/daily-tests
+[nodemon]: https://nodemon.io/
+[nodemon debug]: https://github.com/Microsoft/vscode-recipes/tree/master/nodemon
+[vs code]: https://code.visualstudio.com/
 
-Hosting your own server
------------------------
+## Hosting your own server
 
 There is documentation about [hosting your own server][self-hosting].
 
 [self-hosting]: doc/self-hosting.md
 
-
-History
--------
+## History
 
 b.adge.me was the original website for this service. Heroku back then had a
 thing which made it hard to use a toplevel domain with it, hence the odd
@@ -165,26 +176,29 @@ You can read more about [the project's inception][thread],
 [spec]: spec/SPECIFICATION.md
 [thread]: https://github.com/h5bp/lazyweb-requests/issues/150
 
+## Project leaders
 
-Project leaders
----------------
+Maintainers:
 
-[espadrine](https://github.com/espadrine) is the sysadmin.
+- [calebcartwright](https://github.com/calebcartwright) (core team)
+- [chris48s](https://github.com/chris48s) (core team)
+- [Daniel15](https://github.com/Daniel15) (core team)
+- [espadrine](https://github.com/espadrine) (core team)
+- [paulmelnikow](https://github.com/paulmelnikow) (core team)
+- [platan](https://github.com/platan) (core team)
+- [PyvesB](https://github.com/PyvesB) (core team)
+- [RedSparr0w](https://github.com/RedSparr0w) (core team)
 
-These contributors donate time on a consistent basis to help guide and
-maintain the project:
+Operations:
 
-* [chris48s](https://github.com/chris48s)
-* [Daniel15](https://github.com/Daniel15)
-* [espadrine](https://github.com/espadrine)
-* [paulmelnikow](https://github.com/paulmelnikow)
-* [platan](https://github.com/platan)
-* [PyvesB](https://github.com/PyvesB)
-* [RedSparr0w](https://github.com/RedSparr0w)
+- [espadrine](https://github.com/espadrine) (sysadmin)
+- [paulmelnikow](https://github.com/paulmelnikow) (limited access)
 
+Alumni:
 
-Related projects
-----------------
+- [olivierlacan](https://github.com/olivierlacan)
+
+## Related projects
 
 - [badgerbadgerbadger gem][gem]
 - [pybadges python library][pybadges]
@@ -192,8 +206,7 @@ Related projects
 [gem]: https://github.com/badges/badgerbadgerbadger
 [pybadges]: https://github.com/google/pybadges
 
-License
--------
+## License
 
 All assets and code are under the [CC0 LICENSE](LICENSE) and in the public
 domain unless specified otherwise.
@@ -206,14 +219,12 @@ under their terms and license.
 This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
 <a href="https://github.com/badges/shields/graphs/contributors"><img src="https://opencollective.com/shields/contributors.svg?width=890" /></a>
 
-
 ## Backers
 
 Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/shields#backer)]
 
 <a href="https://opencollective.com/shields#backers" target="_blank"><img src="https://opencollective.com/shields/backers.svg?width=890"></a>
 
-
 ## Sponsors
 
 Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/shields#sponsor)]
@@ -228,5 +239,3 @@ Support this project by becoming a sponsor. Your logo will show up here with a l
 <a href="https://opencollective.com/shields/sponsor/7/website" target="_blank"><img src="https://opencollective.com/shields/sponsor/7/avatar.svg"></a>
 <a href="https://opencollective.com/shields/sponsor/8/website" target="_blank"><img src="https://opencollective.com/shields/sponsor/8/avatar.svg"></a>
 <a href="https://opencollective.com/shields/sponsor/9/website" target="_blank"><img src="https://opencollective.com/shields/sponsor/9/avatar.svg"></a>
-
-

__snapshots__/make-badge.spec.js

@@ -2,25 +2,18 @@ exports['The badge generator SVG should always produce the same SVG (unless we h
 <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="90" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="90" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#555" d="M0 0h45v20H0z"/><path fill="#4c1" d="M45 0h45v20H45z"/><path fill="url(#b)" d="M0 0h90v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110"> <text x="235" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="350">cactus</text><text x="235" y="140" transform="scale(.1)" textLength="350">cactus</text><text x="665" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="350">grown</text><text x="665" y="140" transform="scale(.1)" textLength="350">grown</text></g> </svg>
 `
 
-exports['The badge generator JSON should always produce the same JSON (unless we have changed something!) 1'] = `
-{
-  "name": "cactus",
-  "value": "grown"
-}
-`
-
-exports['The badge generator badges with logos should always produce the same badge shields GitHub logo default color (#333333) 1'] = `
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="113" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="113" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#555" d="M0 0h54v20H0z"/><path fill="#4c1" d="M54 0h59v20H54z"/><path fill="url(#b)" d="M0 0h113v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110"><image x="5" y="3" width="14" height="14" xlink:href="github"/> <text x="365" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="270">label</text><text x="365" y="140" transform="scale(.1)" textLength="270">label</text><text x="825" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="490">message</text><text x="825" y="140" transform="scale(.1)" textLength="490">message</text></g> </svg>
-`
-
 exports['The badge generator badges with logos should always produce the same badge shields GitHub logo custom color (whitesmoke) 1'] = `
 <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="113" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="113" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#555" d="M0 0h54v20H0z"/><path fill="#4c1" d="M54 0h59v20H54z"/><path fill="url(#b)" d="M0 0h113v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110"><image x="5" y="3" width="14" height="14" xlink:href="github"/> <text x="365" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="270">label</text><text x="365" y="140" transform="scale(.1)" textLength="270">label</text><text x="825" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="490">message</text><text x="825" y="140" transform="scale(.1)" textLength="490">message</text></g> </svg>
 `
 
-exports['The badge generator badges with logos should always produce the same badge simple-icons javascript logo default color (#F7DF1E) 1'] = `
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="113" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="113" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#555" d="M0 0h54v20H0z"/><path fill="#4c1" d="M54 0h59v20H54z"/><path fill="url(#b)" d="M0 0h113v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110"><image x="5" y="3" width="14" height="14" xlink:href="javascript"/> <text x="365" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="270">label</text><text x="365" y="140" transform="scale(.1)" textLength="270">label</text><text x="825" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="490">message</text><text x="825" y="140" transform="scale(.1)" textLength="490">message</text></g> </svg>
+exports['The badge generator badges with logos should always produce the same badge shields GitHub logo default color (#333333) 1'] = `
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="113" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="113" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#555" d="M0 0h54v20H0z"/><path fill="#4c1" d="M54 0h59v20H54z"/><path fill="url(#b)" d="M0 0h113v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110"><image x="5" y="3" width="14" height="14" xlink:href="github"/> <text x="365" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="270">label</text><text x="365" y="140" transform="scale(.1)" textLength="270">label</text><text x="825" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="490">message</text><text x="825" y="140" transform="scale(.1)" textLength="490">message</text></g> </svg>
 `
 
 exports['The badge generator badges with logos should always produce the same badge simple-icons javascript logo custom color (rgba(46,204,113,0.8)) 1'] = `
 <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="113" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="113" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#555" d="M0 0h54v20H0z"/><path fill="#4c1" d="M54 0h59v20H54z"/><path fill="url(#b)" d="M0 0h113v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110"><image x="5" y="3" width="14" height="14" xlink:href="javascript"/> <text x="365" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="270">label</text><text x="365" y="140" transform="scale(.1)" textLength="270">label</text><text x="825" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="490">message</text><text x="825" y="140" transform="scale(.1)" textLength="490">message</text></g> </svg>
 `
+
+exports['The badge generator badges with logos should always produce the same badge simple-icons javascript logo default color (#F7DF1E) 1'] = `
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="113" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="113" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#555" d="M0 0h54v20H0z"/><path fill="#4c1" d="M54 0h59v20H54z"/><path fill="url(#b)" d="M0 0h113v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110"><image x="5" y="3" width="14" height="14" xlink:href="javascript"/> <text x="365" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="270">label</text><text x="365" y="140" transform="scale(.1)" textLength="270">label</text><text x="825" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="490">message</text><text x="825" y="140" transform="scale(.1)" textLength="490">message</text></g> </svg>
+`

app.json

@@ -1,19 +1,18 @@
 {
   "name": "Shields",
   "description": "Concise, consistent, and legible badges in SVG and raster format.",
-  "keywords": [
-    "badge",
-    "github",
-    "svg",
-    "status"
-  ],
+  "keywords": ["badge", "github", "svg", "status"],
   "website": "https://shields.io/",
   "repository": "https://github.com/badges/shields",
   "logo": "http://shields.io/favicon.png",
   "env": {
-    "NPM_CONFIG_PRODUCTION": {
-      "description": "Configure whether devDependencies are installed (they are needed for the build).",
-      "value": "false"
+    "WHEELMAP_TOKEN": {
+      "description": "Configure the token to be used for the Wheelmap service.",
+      "required": false
+    },
+    "GH_TOKEN": {
+      "description": "Configure the token to be used for the GitHub services.",
+      "required": false
     }
   },
   "formation": {

config/custom-environment-variables.yml

@@ -0,0 +1,64 @@
+public:
+  bind:
+    address: 'BIND_ADDRESS'
+    port: 'PORT'
+
+  metrics:
+    prometheus:
+      enabled: 'METRICS_PROMETHEUS_ENABLED'
+
+  ssl:
+    isSecure: 'HTTPS'
+    key: 'HTTPS_KEY'
+    cert: 'HTTPS_CRT'
+
+  redirectUri: 'REDIRECT_URI'
+
+  cors:
+    allowedOrigin:
+      __name: 'ALLOWED_ORIGIN'
+      __format: 'json'
+
+  persistence:
+    dir: 'PERSISTENCE_DIR'
+    redisUrl: 'REDIS_URL'
+
+  services:
+    github:
+      baseUri: 'GITHUB_URL'
+      debug:
+        enabled: 'GITHUB_DEBUG_ENABLED'
+        intervalSeconds: 'GITHUB_DEBUG_INTERVAL_SECONDS'
+    trace: 'TRACE_SERVICES'
+
+  profiling:
+    makeBadge: 'PROFILE_MAKE_BADGE'
+
+  cacheHeaders:
+    defaultCacheLengthSeconds: 'BADGE_MAX_AGE_SECONDS'
+
+  rateLimit: 'RATE_LIMIT'
+
+  fetchLimit: 'FETCH_LIMIT'
+
+private:
+  azure_devops_token: 'AZURE_DEVOPS_TOKEN'
+  bintray_user: 'BINTRAY_USER'
+  bintray_apikey: 'BINTRAY_API_KEY'
+  drone_token: 'DRONE_TOKEN'
+  gh_client_id: 'GH_CLIENT_ID'
+  gh_client_secret: 'GH_CLIENT_SECRET'
+  gh_token: 'GH_TOKEN'
+  jenkins_user: 'JENKINS_USER'
+  jenkins_pass: 'JENKINS_PASS'
+  jira_user: 'JIRA_USER'
+  jira_pass: 'JIRA_PASS'
+  nexus_user: 'NEXUS_USER'
+  nexus_pass: 'NEXUS_PASS'
+  npm_token: 'NPM_TOKEN'
+  sentry_dsn: 'SENTRY_DSN'
+  shields_secret: 'SHIELDS_SECRET'
+  sl_insight_userUuid: 'SL_INSIGHT_USER_UUID'
+  sl_insight_apiToken: 'SL_INSIGHT_API_TOKEN'
+  sonarqube_token: 'SONARQUBE_TOKEN'
+  wheelmap_token: 'WHEELMAP_TOKEN'

config/default.yml

@@ -0,0 +1,38 @@
+public:
+  bind:
+    address: '::'
+
+  metrics:
+    prometheus:
+      enabled: false
+
+  ssl:
+    isSecure: false
+
+  cors:
+    allowedOrigin: []
+
+  persistence:
+    dir: './private'
+
+  services:
+    github:
+      baseUri: 'https://api.github.com/'
+      debug:
+        enabled: false
+        intervalSeconds: 200
+    trace: false
+
+  profiling:
+    makeBadge: false
+
+  cacheHeaders:
+    defaultCacheLengthSeconds: 120
+
+  rateLimit: true
+
+  handleInternalErrors: true
+
+  fetchLimit: '10MB'
+
+private: {}

config/development.yml

@@ -0,0 +1,10 @@
+public:
+  bind:
+    address: 'localhost'
+
+  cors:
+    allowedOrigin: ['http://localhost:3000']
+
+  rateLimit: false
+
+  handleInternalErrors: false

config/local-shields-io-production.template.yml

@@ -0,0 +1,10 @@
+private:
+  bintray_user: ...
+  bintray_apikey: ...
+  gh_client_id: ...
+  gh_client_secret: ...
+  sentry_dsn: ...
+  shields_secret: ...
+  sl_insight_userUuid: ...
+  sl_insight_apiToken: ...
+  wheelmap_token: ...

config/local.template.yml

@@ -0,0 +1,8 @@
+# Copy this file to `config/local.yml` and fill it in! It will be gitignored.
+
+private:
+  # The possible values are documented in `doc/server-secrets.md`. Note that
+  # you can also set these values through environment variables, which may be
+  # preferable for self hosting.
+  gh_token: '...'
+  wheelmap_token: '...'

config/production.yml

@@ -0,0 +1,3 @@
+public:
+  bind:
+    address: '0.0.0.0'

config/shields-io-production.yml

@@ -0,0 +1,16 @@
+public:
+  metrics:
+    prometheus:
+      enabled: true
+
+  ssl:
+    isSecure: true
+
+  cors:
+    allowedOrigin: ['http://shields.io', 'https://shields.io']
+
+  redirectUrl: 'https://shields.io/'
+
+private:
+  # These are not really private; they should be moved to `public`.
+  shields_ips: ['192.99.59.72', '51.254.114.150', '149.56.96.133']

config/test.yml

@@ -0,0 +1,10 @@
+public:
+  bind:
+    address: 'localhost'
+    port: 1111
+
+  rateLimit: false
+
+  redirectUrl: 'http://badge-server.example.com'
+
+  handleInternalErrors: false

core/badge-urls/make-badge-url.js

@@ -0,0 +1,144 @@
+'use strict'
+
+const queryString = require('query-string')
+const pathToRegexp = require('path-to-regexp')
+
+function badgeUrlFromPath({
+  baseUrl = '',
+  path,
+  queryParams,
+  style,
+  format = 'svg',
+  longCache = false,
+}) {
+  const outExt = format.length ? `.${format}` : ''
+
+  const outQueryString = queryString.stringify({
+    cacheSeconds: longCache ? '2592000' : undefined,
+    style,
+    ...queryParams,
+  })
+  const suffix = outQueryString ? `?${outQueryString}` : ''
+
+  return `${baseUrl}${path}${outExt}${suffix}`
+}
+
+function badgeUrlFromPattern({
+  baseUrl = '',
+  pattern,
+  namedParams,
+  queryParams,
+  style,
+  format = 'svg',
+  longCache = false,
+}) {
+  const toPath = pathToRegexp.compile(pattern, {
+    strict: true,
+    sensitive: true,
+  })
+
+  const path = toPath(namedParams)
+
+  return badgeUrlFromPath({
+    baseUrl,
+    path,
+    queryParams,
+    style,
+    format,
+    longCache,
+  })
+}
+
+function encodeField(s) {
+  return encodeURIComponent(s.replace(/-/g, '--').replace(/_/g, '__'))
+}
+
+function staticBadgeUrl({
+  baseUrl = '',
+  label,
+  message,
+  color = 'lightgray',
+  style,
+  namedLogo,
+  format = 'svg',
+}) {
+  const path = [label, message, color].map(encodeField).join('-')
+  const outQueryString = queryString.stringify({
+    style,
+    logo: namedLogo,
+  })
+  const suffix = outQueryString ? `?${outQueryString}` : ''
+  return `${baseUrl}/badge/${path}.${format}${suffix}`
+}
+
+function queryStringStaticBadgeUrl({
+  baseUrl = '',
+  label,
+  message,
+  color,
+  labelColor,
+  style,
+  namedLogo,
+  logoColor,
+  logoWidth,
+  logoPosition,
+  format = 'svg',
+}) {
+  // schemaVersion could be a parameter if we iterate on it,
+  // for now it's hardcoded to the only supported version.
+  const schemaVersion = '1'
+  const suffix = `?${queryString.stringify({
+    label,
+    message,
+    color,
+    labelColor,
+    style,
+    logo: namedLogo,
+    logoColor,
+    logoWidth,
+    logoPosition,
+  })}`
+  return `${baseUrl}/static/v${schemaVersion}.${format}${suffix}`
+}
+
+function dynamicBadgeUrl({
+  baseUrl,
+  datatype,
+  label,
+  dataUrl,
+  query,
+  prefix,
+  suffix,
+  color,
+  style,
+  format = 'svg',
+}) {
+  const queryParams = {
+    label,
+    url: dataUrl,
+    query,
+    style,
+  }
+
+  if (color) {
+    queryParams.color = color
+  }
+  if (prefix) {
+    queryParams.prefix = prefix
+  }
+  if (suffix) {
+    queryParams.suffix = suffix
+  }
+
+  const outQueryString = queryString.stringify(queryParams)
+  return `${baseUrl}/badge/dynamic/${datatype}.${format}?${outQueryString}`
+}
+
+module.exports = {
+  badgeUrlFromPath,
+  badgeUrlFromPattern,
+  encodeField,
+  staticBadgeUrl,
+  queryStringStaticBadgeUrl,
+  dynamicBadgeUrl,
+}

core/badge-urls/make-badge-url.spec.js

@@ -0,0 +1,159 @@
+'use strict'
+
+const { test, given } = require('sazerac')
+const {
+  badgeUrlFromPath,
+  badgeUrlFromPattern,
+  encodeField,
+  staticBadgeUrl,
+  queryStringStaticBadgeUrl,
+  dynamicBadgeUrl,
+} = require('./make-badge-url')
+
+describe('Badge URL generation functions', function() {
+  test(badgeUrlFromPath, () => {
+    given({
+      baseUrl: 'http://example.com',
+      path: '/npm/v/gh-badges',
+      style: 'flat-square',
+      longCache: true,
+    }).expect(
+      'http://example.com/npm/v/gh-badges.svg?cacheSeconds=2592000&style=flat-square'
+    )
+  })
+
+  test(badgeUrlFromPattern, () => {
+    given({
+      baseUrl: 'http://example.com',
+      pattern: '/npm/v/:packageName',
+      namedParams: { packageName: 'gh-badges' },
+      style: 'flat-square',
+      longCache: true,
+    }).expect(
+      'http://example.com/npm/v/gh-badges.svg?cacheSeconds=2592000&style=flat-square'
+    )
+  })
+
+  test(encodeField, () => {
+    given('foo').expect('foo')
+    given('').expect('')
+    given('happy go lucky').expect('happy%20go%20lucky')
+    given('do-right').expect('do--right')
+    given('it_is_a_snake').expect('it__is__a__snake')
+  })
+
+  test(staticBadgeUrl, () => {
+    given({
+      label: 'foo',
+      message: 'bar',
+      color: 'blue',
+      style: 'flat-square',
+    }).expect('/badge/foo-bar-blue.svg?style=flat-square')
+    given({
+      label: 'foo',
+      message: 'bar',
+      color: 'blue',
+      style: 'flat-square',
+      format: 'png',
+      namedLogo: 'github',
+    }).expect('/badge/foo-bar-blue.png?logo=github&style=flat-square')
+    given({
+      label: 'Hello World',
+      message: 'Привет Мир',
+      color: '#aabbcc',
+    }).expect(
+      '/badge/Hello%20World-%D0%9F%D1%80%D0%B8%D0%B2%D0%B5%D1%82%20%D0%9C%D0%B8%D1%80-%23aabbcc.svg'
+    )
+    given({
+      label: '123-123',
+      message: 'abc-abc',
+      color: 'blue',
+    }).expect('/badge/123--123-abc--abc-blue.svg')
+    given({
+      label: '123-123',
+      message: '',
+      color: 'blue',
+      style: 'social',
+    }).expect('/badge/123--123--blue.svg?style=social')
+    given({
+      label: '',
+      message: 'blue',
+      color: 'blue',
+    }).expect('/badge/-blue-blue.svg')
+  })
+
+  test(queryStringStaticBadgeUrl, () => {
+    // the query-string library sorts parameters by name
+    given({
+      label: 'foo',
+      message: 'bar',
+      color: 'blue',
+      style: 'flat-square',
+    }).expect(
+      '/static/v1.svg?color=blue&label=foo&message=bar&style=flat-square'
+    )
+    given({
+      label: 'foo Bar',
+      message: 'bar Baz',
+      color: 'blue',
+      style: 'flat-square',
+      format: 'png',
+      namedLogo: 'github',
+    }).expect(
+      '/static/v1.png?color=blue&label=foo%20Bar&logo=github&message=bar%20Baz&style=flat-square'
+    )
+    given({
+      label: 'Hello World',
+      message: 'Привет Мир',
+      color: '#aabbcc',
+    }).expect(
+      '/static/v1.svg?color=%23aabbcc&label=Hello%20World&message=%D0%9F%D1%80%D0%B8%D0%B2%D0%B5%D1%82%20%D0%9C%D0%B8%D1%80'
+    )
+  })
+
+  test(dynamicBadgeUrl, () => {
+    const dataUrl = 'http://example.com/foo.json'
+    const query = '$.bar'
+    const prefix = 'value: '
+    given({
+      baseUrl: 'http://img.example.com',
+      datatype: 'json',
+      label: 'foo',
+      dataUrl,
+      query,
+      prefix,
+      style: 'plastic',
+    }).expect(
+      [
+        'http://img.example.com/badge/dynamic/json.svg',
+        '?label=foo',
+        `&prefix=${encodeURIComponent(prefix)}`,
+        `&query=${encodeURIComponent(query)}`,
+        '&style=plastic',
+        `&url=${encodeURIComponent(dataUrl)}`,
+      ].join('')
+    )
+    const suffix = '<- value'
+    const color = 'blue'
+    given({
+      baseUrl: 'http://img.example.com',
+      datatype: 'json',
+      label: 'foo',
+      dataUrl,
+      query,
+      suffix,
+      color,
+      style: 'plastic',
+    }).expect(
+      [
+        'http://img.example.com/badge/dynamic/json.svg',
+        '?color=blue',
+        '&label=foo',
+        `&query=${encodeURIComponent(query)}`,
+        '&style=plastic',
+        `&suffix=${encodeURIComponent(suffix)}`,
+        `&url=${encodeURIComponent(dataUrl)}`,
+      ].join('')
+    )
+  })
+})

core/badge-urls/path-helpers.js

@@ -16,15 +16,6 @@ function escapeFormat(t) {
   )
 }
 
-function escapeFormatSlashes(t) {
-  return (
-    escapeFormat(t)
-      // Double slash
-      .replace(/\/\//g, '/')
-  )
-}
-
 module.exports = {
   escapeFormat,
-  escapeFormatSlashes,
 }

core/base-service/base-json.js

@@ -7,8 +7,25 @@ const trace = require('./trace')
 const { InvalidResponse } = require('./errors')
 
 class BaseJsonService extends BaseService {
-  async _requestJson({ schema, url, options = {}, errorMessages = {} }) {
+  _parseJson(buffer) {
     const logTrace = (...args) => trace.logTrace('fetch', ...args)
+    let json
+    try {
+      json = JSON.parse(buffer)
+    } catch (err) {
+      logTrace(emojic.dart, 'Response JSON (unparseable)', buffer)
+      throw new InvalidResponse({
+        prettyMessage: 'unparseable json response',
+        underlyingError: err,
+      })
+    }
+    logTrace(emojic.dart, 'Response JSON (before validation)', json, {
+      deep: true,
+    })
+    return json
+  }
+
+  async _requestJson({ schema, url, options = {}, errorMessages = {} }) {
     const mergedOptions = {
       ...{ headers: { Accept: 'application/json' } },
       ...options,
@@ -18,19 +35,7 @@ class BaseJsonService extends BaseService {
       options: mergedOptions,
       errorMessages,
     })
-    let json
-    try {
-      json = JSON.parse(buffer)
-    } catch (err) {
-      logTrace(emojic.dart, 'Response JSON (unparseable)', json)
-      throw new InvalidResponse({
-        prettyMessage: 'unparseable json response',
-        underlyingError: err,
-      })
-    }
-    logTrace(emojic.dart, 'Response JSON (before validation)', json, {
-      deep: true,
-    })
+    const json = this._parseJson(buffer)
     return this.constructor._validate(json, schema)
   }
 }

core/base-service/base-json.spec.js

@@ -1,14 +1,10 @@
 'use strict'
 
 const Joi = require('joi')
-const chai = require('chai')
-const { expect } = chai
+const { expect } = require('chai')
 const sinon = require('sinon')
-
 const BaseJsonService = require('./base-json')
 
-chai.use(require('chai-as-promised'))
-
 const dummySchema = Joi.object({
   requiredString: Joi.string().required(),
 }).required()
@@ -35,7 +31,7 @@ class DummyJsonService extends BaseJsonService {
 
 describe('BaseJsonService', function() {
   describe('Making requests', function() {
-    let sendAndCacheRequest, serviceInstance
+    let sendAndCacheRequest
     beforeEach(function() {
       sendAndCacheRequest = sinon.stub().returns(
         Promise.resolve({
@@ -43,25 +39,22 @@ describe('BaseJsonService', function() {
           res: { statusCode: 200 },
         })
       )
-      serviceInstance = new DummyJsonService(
-        { sendAndCacheRequest },
-        { handleInternalErrors: false }
-      )
     })
 
     it('invokes _sendAndCacheRequest', async function() {
-      await serviceInstance.invokeHandler({}, {})
+      await DummyJsonService.invoke(
+        { sendAndCacheRequest },
+        { handleInternalErrors: false }
+      )
 
       expect(sendAndCacheRequest).to.have.been.calledOnceWith(
         'http://example.com/foo.json',
-        {
-          headers: { Accept: 'application/json' },
-        }
+        { headers: { Accept: 'application/json' } }
       )
     })
 
     it('forwards options to _sendAndCacheRequest', async function() {
-      Object.assign(serviceInstance, {
+      class WithOptions extends DummyJsonService {
         async handle() {
           const { value } = await this._requestJson({
             schema: dummySchema,
@@ -69,10 +62,13 @@ describe('BaseJsonService', function() {
             options: { method: 'POST', qs: { queryParam: 123 } },
           })
           return { message: value }
-        },
-      })
+        }
+      }
 
-      await serviceInstance.invokeHandler({}, {})
+      await WithOptions.invoke(
+        { sendAndCacheRequest },
+        { handleInternalErrors: false }
+      )
 
       expect(sendAndCacheRequest).to.have.been.calledOnceWith(
         'http://example.com/foo.json',
@@ -91,12 +87,12 @@ describe('BaseJsonService', function() {
         buffer: '{"requiredString": "some-string"}',
         res: { statusCode: 200 },
       })
-      const serviceInstance = new DummyJsonService(
-        { sendAndCacheRequest },
-        { handleInternalErrors: false }
-      )
-      const serviceData = await serviceInstance.invokeHandler({}, {})
-      expect(serviceData).to.deep.equal({
+      expect(
+        await DummyJsonService.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
         message: 'some-string',
       })
     })
@@ -106,12 +102,13 @@ describe('BaseJsonService', function() {
         buffer: '{"unexpectedKey": "some-string"}',
         res: { statusCode: 200 },
       })
-      const serviceInstance = new DummyJsonService(
-        { sendAndCacheRequest },
-        { handleInternalErrors: false }
-      )
-      const serviceData = await serviceInstance.invokeHandler({}, {})
-      expect(serviceData).to.deep.equal({
+      expect(
+        await DummyJsonService.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
+        isError: true,
         color: 'lightgray',
         message: 'invalid response data',
       })
@@ -122,12 +119,13 @@ describe('BaseJsonService', function() {
         buffer: 'not json',
         res: { statusCode: 200 },
       })
-      const serviceInstance = new DummyJsonService(
-        { sendAndCacheRequest },
-        { handleInternalErrors: false }
-      )
-      const serviceData = await serviceInstance.invokeHandler({}, {})
-      expect(serviceData).to.deep.equal({
+      expect(
+        await DummyJsonService.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
+        isError: true,
         color: 'lightgray',
         message: 'unparseable json response',
       })

core/base-service/base-non-memory-caching.js

@@ -0,0 +1,70 @@
+'use strict'
+
+const makeBadge = require('../../gh-badges/lib/make-badge')
+const BaseService = require('./base')
+const { setCacheHeaders } = require('./cache-headers')
+const { makeSend } = require('./legacy-result-sender')
+const coalesceBadge = require('./coalesce-badge')
+const { prepareRoute, namedParamsForMatch } = require('./route')
+
+// Badges are subject to two independent types of caching: in-memory and
+// downstream.
+//
+// Services deriving from `NonMemoryCachingBaseService` are not cached in
+// memory on the server. This means that each request that hits the server
+// triggers another call to the handler. When using badges for server
+// diagnostics, that's useful!
+//
+// In contrast, The `handle()` function of most other `BaseService`
+// subclasses is wrapped in onboard, in-memory caching. See `lib /request-
+// handler.js` and `BaseService.prototype.register()`.
+//
+// All services, including those extending NonMemoryCachingBaseServices, may
+// be cached _downstream_. This is governed by cache headers, which are
+// configured by the service, the user's request, and the server's default
+// cache length.
+module.exports = class NonMemoryCachingBaseService extends BaseService {
+  static register({ camp, requestCounter }, serviceConfig) {
+    const { cacheHeaders: cacheHeaderConfig } = serviceConfig
+    const { _cacheLength: serviceDefaultCacheLengthSeconds } = this
+    const { regex, captureNames } = prepareRoute(this.route)
+
+    const serviceRequestCounter = this._createServiceRequestCounter({
+      requestCounter,
+    })
+
+    camp.route(regex, async (queryParams, match, end, ask) => {
+      const namedParams = namedParamsForMatch(captureNames, match, this)
+      const serviceData = await this.invoke(
+        {},
+        serviceConfig,
+        namedParams,
+        queryParams
+      )
+
+      const badgeData = coalesceBadge(
+        queryParams,
+        serviceData,
+        this.defaultBadgeData,
+        this
+      )
+
+      // The final capture group is the extension.
+      const format = match.slice(-1)[0]
+      badgeData.format = format
+
+      const svg = makeBadge(badgeData)
+
+      setCacheHeaders({
+        cacheHeaderConfig,
+        serviceDefaultCacheLengthSeconds,
+        queryParams,
+        res: ask.res,
+      })
+
+      makeSend(format, ask.res, end)(svg)
+
+      serviceRequestCounter.inc()
+    })
+  }
+}

core/base-service/base-static.js

@@ -0,0 +1,66 @@
+'use strict'
+
+const makeBadge = require('../../gh-badges/lib/make-badge')
+const BaseService = require('./base')
+const {
+  serverHasBeenUpSinceResourceCached,
+  setCacheHeadersForStaticResource,
+} = require('./cache-headers')
+const { makeSend } = require('./legacy-result-sender')
+const coalesceBadge = require('./coalesce-badge')
+const { prepareRoute, namedParamsForMatch } = require('./route')
+
+module.exports = class BaseStaticService extends BaseService {
+  static register({ camp, requestCounter }, serviceConfig) {
+    const {
+      profiling: { makeBadge: shouldProfileMakeBadge },
+    } = serviceConfig
+    const { regex, captureNames } = prepareRoute(this.route)
+
+    const serviceRequestCounter = this._createServiceRequestCounter({
+      requestCounter,
+    })
+
+    camp.route(regex, async (queryParams, match, end, ask) => {
+      if (serverHasBeenUpSinceResourceCached(ask.req)) {
+        // Send Not Modified.
+        ask.res.statusCode = 304
+        ask.res.end()
+        return
+      }
+
+      const namedParams = namedParamsForMatch(captureNames, match, this)
+      const serviceData = await this.invoke(
+        {},
+        serviceConfig,
+        namedParams,
+        queryParams
+      )
+
+      const badgeData = coalesceBadge(
+        queryParams,
+        serviceData,
+        this.defaultBadgeData,
+        this
+      )
+
+      // The final capture group is the extension.
+      const format = match.slice(-1)[0]
+      badgeData.format = format
+
+      if (shouldProfileMakeBadge) {
+        console.time('makeBadge total')
+      }
+      const svg = makeBadge(badgeData)
+      if (shouldProfileMakeBadge) {
+        console.timeEnd('makeBadge total')
+      }
+
+      setCacheHeadersForStaticResource(ask.res)
+
+      makeSend(format, ask.res, end)(svg)
+
+      serviceRequestCounter.inc()
+    })
+  }
+}

core/base-service/base-svg-scraping.js

@@ -12,7 +12,7 @@ const leadingWhitespace = /(?:\r\n\s*|\r\s*|\n\s*)/g
 class BaseSvgScrapingService extends BaseService {
   static valueFromSvgBadge(svg, valueMatcher = defaultValueMatcher) {
     if (typeof svg !== 'string') {
-      throw TypeError('Parameter should be a string')
+      throw new TypeError('Parameter should be a string')
     }
     const stripped = svg.replace(leadingWhitespace, '')
     const match = valueMatcher.exec(stripped)

core/base-service/base-svg-scraping.spec.js

@@ -1,19 +1,13 @@
 'use strict'
 
-const chai = require('chai')
 const { expect } = require('chai')
 const sinon = require('sinon')
 const Joi = require('joi')
-const { makeBadgeData } = require('../lib/badge-data')
-const makeBadge = require('../gh-badges/lib/make-badge')
+const makeBadge = require('../../gh-badges/lib/make-badge')
 const BaseSvgScrapingService = require('./base-svg-scraping')
 
-chai.use(require('chai-as-promised'))
-
 function makeExampleSvg({ label, message }) {
-  const badgeData = makeBadgeData('this is the label', {})
-  badgeData.text[1] = 'this is the result!'
-  return makeBadge(badgeData)
+  return makeBadge({ text: ['this is the label', 'this is the result!'] })
 }
 
 const schema = Joi.object({
@@ -56,7 +50,7 @@ describe('BaseSvgScrapingService', function() {
   })
 
   describe('Making requests', function() {
-    let sendAndCacheRequest, serviceInstance
+    let sendAndCacheRequest
     beforeEach(function() {
       sendAndCacheRequest = sinon.stub().returns(
         Promise.resolve({
@@ -64,27 +58,24 @@ describe('BaseSvgScrapingService', function() {
           res: { statusCode: 200 },
         })
       )
-      serviceInstance = new DummySvgScrapingService(
-        { sendAndCacheRequest },
-        { handleInternalErrors: false }
-      )
     })
 
     it('invokes _sendAndCacheRequest with the expected header', async function() {
-      await serviceInstance.invokeHandler({}, {})
+      await DummySvgScrapingService.invoke(
+        { sendAndCacheRequest },
+        { handleInternalErrors: false }
+      )
 
       expect(sendAndCacheRequest).to.have.been.calledOnceWith(
         'http://example.com/foo.svg',
-        {
-          headers: { Accept: 'image/svg+xml' },
-        }
+        { headers: { Accept: 'image/svg+xml' } }
       )
     })
 
     it('forwards options to _sendAndCacheRequest', async function() {
-      Object.assign(serviceInstance, {
+      class WithCustomOptions extends DummySvgScrapingService {
         async handle() {
-          const { value } = await this._requestSvg({
+          const { message } = await this._requestSvg({
             schema,
             url: 'http://example.com/foo.svg',
             options: {
@@ -92,11 +83,14 @@ describe('BaseSvgScrapingService', function() {
               qs: { queryParam: 123 },
             },
           })
-          return { message: value }
-        },
-      })
+          return { message }
+        }
+      }
 
-      await serviceInstance.invokeHandler({}, {})
+      await WithCustomOptions.invoke(
+        { sendAndCacheRequest },
+        { handleInternalErrors: false }
+      )
 
       expect(sendAndCacheRequest).to.have.been.calledOnceWith(
         'http://example.com/foo.svg',
@@ -115,36 +109,40 @@ describe('BaseSvgScrapingService', function() {
         buffer: exampleSvg,
         res: { statusCode: 200 },
       })
-      const serviceInstance = new DummySvgScrapingService(
-        { sendAndCacheRequest },
-        { handleInternalErrors: false }
-      )
-      const serviceData = await serviceInstance.invokeHandler({}, {})
-      expect(serviceData).to.deep.equal({
+      expect(
+        await DummySvgScrapingService.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
         message: exampleMessage,
       })
     })
 
     it('allows overriding the valueMatcher', async function() {
-      const sendAndCacheRequest = async () => ({
-        buffer: '<desc>a different message</desc>',
-        res: { statusCode: 200 },
-      })
-      const serviceInstance = new DummySvgScrapingService(
-        { sendAndCacheRequest },
-        { handleInternalErrors: false }
-      )
-      Object.assign(serviceInstance, {
+      class WithValueMatcher extends BaseSvgScrapingService {
+        static get route() {
+          return {}
+        }
+
         async handle() {
           return this._requestSvg({
             schema,
             valueMatcher: />([^<>]+)<\/desc>/,
             url: 'http://example.com/foo.svg',
           })
-        },
+        }
+      }
+      const sendAndCacheRequest = async () => ({
+        buffer: '<desc>a different message</desc>',
+        res: { statusCode: 200 },
       })
-      const serviceData = await serviceInstance.invokeHandler({}, {})
-      expect(serviceData).to.deep.equal({
+      expect(
+        await WithValueMatcher.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
         message: 'a different message',
       })
     })
@@ -154,12 +152,13 @@ describe('BaseSvgScrapingService', function() {
         buffer: 'not svg yo',
         res: { statusCode: 200 },
       })
-      const serviceInstance = new DummySvgScrapingService(
-        { sendAndCacheRequest },
-        { handleInternalErrors: false }
-      )
-      const serviceData = await serviceInstance.invokeHandler({}, {})
-      expect(serviceData).to.deep.equal({
+      expect(
+        await DummySvgScrapingService.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
+        isError: true,
         color: 'lightgray',
         message: 'unparseable svg response',
       })

core/base-service/base-xml.spec.js

@@ -1,14 +1,10 @@
 'use strict'
 
 const Joi = require('joi')
-const chai = require('chai')
-const { expect } = chai
+const { expect } = require('chai')
 const sinon = require('sinon')
-
 const BaseXmlService = require('./base-xml')
 
-chai.use(require('chai-as-promised'))
-
 const dummySchema = Joi.object({
   requiredString: Joi.string().required(),
 }).required()
@@ -35,7 +31,7 @@ class DummyXmlService extends BaseXmlService {
 
 describe('BaseXmlService', function() {
   describe('Making requests', function() {
-    let sendAndCacheRequest, serviceInstance
+    let sendAndCacheRequest
     beforeEach(function() {
       sendAndCacheRequest = sinon.stub().returns(
         Promise.resolve({
@@ -43,36 +39,40 @@ describe('BaseXmlService', function() {
           res: { statusCode: 200 },
         })
       )
-      serviceInstance = new DummyXmlService(
-        { sendAndCacheRequest },
-        { handleInternalErrors: false }
-      )
     })
 
     it('invokes _sendAndCacheRequest', async function() {
-      await serviceInstance.invokeHandler({}, {})
+      await DummyXmlService.invoke(
+        { sendAndCacheRequest },
+        { handleInternalErrors: false }
+      )
 
       expect(sendAndCacheRequest).to.have.been.calledOnceWith(
         'http://example.com/foo.xml',
-        {
-          headers: { Accept: 'application/xml, text/xml' },
-        }
+        { headers: { Accept: 'application/xml, text/xml' } }
       )
     })
 
     it('forwards options to _sendAndCacheRequest', async function() {
-      Object.assign(serviceInstance, {
+      class WithCustomOptions extends BaseXmlService {
+        static get route() {
+          return {}
+        }
+
         async handle() {
-          const { value } = await this._requestXml({
+          const { requiredString } = await this._requestXml({
             schema: dummySchema,
             url: 'http://example.com/foo.xml',
             options: { method: 'POST', qs: { queryParam: 123 } },
           })
-          return { message: value }
-        },
-      })
+          return { message: requiredString }
+        }
+      }
 
-      await serviceInstance.invokeHandler({}, {})
+      await WithCustomOptions.invoke(
+        { sendAndCacheRequest },
+        { handleInternalErrors: false }
+      )
 
       expect(sendAndCacheRequest).to.have.been.calledOnceWith(
         'http://example.com/foo.xml',
@@ -91,12 +91,12 @@ describe('BaseXmlService', function() {
         buffer: '<requiredString>some-string</requiredString>',
         res: { statusCode: 200 },
       })
-      const serviceInstance = new DummyXmlService(
-        { sendAndCacheRequest },
-        { handleInternalErrors: false }
-      )
-      const serviceData = await serviceInstance.invokeHandler({}, {})
-      expect(serviceData).to.deep.equal({
+      expect(
+        await DummyXmlService.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
         message: 'some-string',
       })
     })
@@ -118,14 +118,12 @@ describe('BaseXmlService', function() {
           '<requiredString>some-string with trailing whitespace   </requiredString>',
         res: { statusCode: 200 },
       })
-      const serviceInstance = new DummyXmlServiceWithParserOption(
-        { sendAndCacheRequest },
-        { handleInternalErrors: false }
-      )
-
-      const serviceData = await serviceInstance.invokeHandler({}, {})
-
-      expect(serviceData).to.deep.equal({
+      expect(
+        await DummyXmlServiceWithParserOption.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
         message: 'some-string with trailing whitespace   ',
       })
     })
@@ -135,12 +133,13 @@ describe('BaseXmlService', function() {
         buffer: '<unexpectedAttribute>some-string</unexpectedAttribute>',
         res: { statusCode: 200 },
       })
-      const serviceInstance = new DummyXmlService(
-        { sendAndCacheRequest },
-        { handleInternalErrors: false }
-      )
-      const serviceData = await serviceInstance.invokeHandler({}, {})
-      expect(serviceData).to.deep.equal({
+      expect(
+        await DummyXmlService.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
+        isError: true,
         color: 'lightgray',
         message: 'invalid response data',
       })
@@ -151,12 +150,13 @@ describe('BaseXmlService', function() {
         buffer: 'not xml',
         res: { statusCode: 200 },
       })
-      const serviceInstance = new DummyXmlService(
-        { sendAndCacheRequest },
-        { handleInternalErrors: false }
-      )
-      const serviceData = await serviceInstance.invokeHandler({}, {})
-      expect(serviceData).to.deep.equal({
+      expect(
+        await DummyXmlService.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
+        isError: true,
         color: 'lightgray',
         message: 'unparseable xml response',
       })

core/base-service/base-yaml.js

@@ -0,0 +1,49 @@
+'use strict'
+
+const emojic = require('emojic')
+const yaml = require('js-yaml')
+const BaseService = require('./base')
+const { InvalidResponse } = require('./errors')
+const trace = require('./trace')
+
+class BaseYamlService extends BaseService {
+  async _requestYaml({
+    schema,
+    url,
+    options = {},
+    errorMessages = {},
+    encoding = 'utf8',
+  }) {
+    const logTrace = (...args) => trace.logTrace('fetch', ...args)
+    const mergedOptions = {
+      ...{
+        headers: {
+          Accept:
+            'text/x-yaml, text/yaml, application/x-yaml, application/yaml, text/plain',
+        },
+      },
+      ...options,
+    }
+    const { buffer } = await this._request({
+      url,
+      options: mergedOptions,
+      errorMessages,
+    })
+    let parsed
+    try {
+      parsed = yaml.safeLoad(buffer.toString(), encoding)
+    } catch (err) {
+      logTrace(emojic.dart, 'Response YAML (unparseable)', buffer)
+      throw new InvalidResponse({
+        prettyMessage: 'unparseable yaml response',
+        underlyingError: err,
+      })
+    }
+    logTrace(emojic.dart, 'Response YAML (before validation)', parsed, {
+      deep: true,
+    })
+    return this.constructor._validate(parsed, schema)
+  }
+}
+
+module.exports = BaseYamlService

core/base-service/base-yaml.spec.js

@@ -0,0 +1,158 @@
+'use strict'
+
+const Joi = require('joi')
+const { expect } = require('chai')
+const sinon = require('sinon')
+const BaseYamlService = require('./base-yaml')
+
+const dummySchema = Joi.object({
+  requiredString: Joi.string().required(),
+}).required()
+
+class DummyYamlService extends BaseYamlService {
+  static get category() {
+    return 'cat'
+  }
+
+  static get route() {
+    return {
+      base: 'foo',
+    }
+  }
+
+  async handle() {
+    const { requiredString } = await this._requestYaml({
+      schema: dummySchema,
+      url: 'http://example.com/foo.yaml',
+    })
+    return { message: requiredString }
+  }
+}
+
+const expectedYaml = `
+---
+requiredString: some-string
+`
+
+const unexpectedYaml = `
+---
+unexpectedKey: some-string
+`
+
+const invalidYaml = `
+---
+foo: bar
+foo: baz
+`
+
+describe('BaseYamlService', function() {
+  describe('Making requests', function() {
+    let sendAndCacheRequest
+    beforeEach(function() {
+      sendAndCacheRequest = sinon.stub().returns(
+        Promise.resolve({
+          buffer: expectedYaml,
+          res: { statusCode: 200 },
+        })
+      )
+    })
+
+    it('invokes _sendAndCacheRequest', async function() {
+      await DummyYamlService.invoke(
+        { sendAndCacheRequest },
+        { handleInternalErrors: false }
+      )
+
+      expect(sendAndCacheRequest).to.have.been.calledOnceWith(
+        'http://example.com/foo.yaml',
+        {
+          headers: {
+            Accept:
+              'text/x-yaml, text/yaml, application/x-yaml, application/yaml, text/plain',
+          },
+        }
+      )
+    })
+
+    it('forwards options to _sendAndCacheRequest', async function() {
+      class WithOptions extends DummyYamlService {
+        async handle() {
+          const { requiredString } = await this._requestYaml({
+            schema: dummySchema,
+            url: 'http://example.com/foo.yaml',
+            options: { method: 'POST', qs: { queryParam: 123 } },
+          })
+          return { message: requiredString }
+        }
+      }
+
+      await WithOptions.invoke(
+        { sendAndCacheRequest },
+        { handleInternalErrors: false }
+      )
+
+      expect(sendAndCacheRequest).to.have.been.calledOnceWith(
+        'http://example.com/foo.yaml',
+        {
+          headers: {
+            Accept:
+              'text/x-yaml, text/yaml, application/x-yaml, application/yaml, text/plain',
+          },
+          method: 'POST',
+          qs: { queryParam: 123 },
+        }
+      )
+    })
+  })
+
+  describe('Making badges', function() {
+    it('handles valid yaml responses', async function() {
+      const sendAndCacheRequest = async () => ({
+        buffer: expectedYaml,
+        res: { statusCode: 200 },
+      })
+      expect(
+        await DummyYamlService.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
+        message: 'some-string',
+      })
+    })
+
+    it('handles yaml responses which do not match the schema', async function() {
+      const sendAndCacheRequest = async () => ({
+        buffer: unexpectedYaml,
+        res: { statusCode: 200 },
+      })
+      expect(
+        await DummyYamlService.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
+        isError: true,
+        color: 'lightgray',
+        message: 'invalid response data',
+      })
+    })
+
+    it('handles unparseable yaml responses', async function() {
+      const sendAndCacheRequest = async () => ({
+        buffer: invalidYaml,
+        res: { statusCode: 200 },
+      })
+      expect(
+        await DummyYamlService.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
+        isError: true,
+        color: 'lightgray',
+        message: 'unparseable yaml response',
+      })
+    })
+  })
+})

core/base-service/base.js

@@ -0,0 +1,424 @@
+'use strict'
+
+const decamelize = require('decamelize')
+// See available emoji at http://emoji.muan.co/
+const emojic = require('emojic')
+const Joi = require('joi')
+const { assertValidCategory } = require('./categories')
+const checkErrorResponse = require('./check-error-response')
+const coalesceBadge = require('./coalesce-badge')
+const {
+  NotFound,
+  InvalidResponse,
+  Inaccessible,
+  InvalidParameter,
+  Deprecated,
+} = require('./errors')
+const { validateExample, transformExample } = require('./examples')
+const {
+  makeFullUrl,
+  assertValidRoute,
+  prepareRoute,
+  namedParamsForMatch,
+  getQueryParamNames,
+} = require('./route')
+const { assertValidServiceDefinition } = require('./service-definitions')
+const trace = require('./trace')
+const validate = require('./validate')
+
+const defaultBadgeDataSchema = Joi.object({
+  label: Joi.string(),
+  color: Joi.string(),
+  labelColor: Joi.string(),
+  namedLogo: Joi.string(),
+}).required()
+
+const optionalStringWhenNamedLogoPrsent = Joi.alternatives().when('namedLogo', {
+  is: Joi.string().required(),
+  then: Joi.string(),
+})
+
+const optionalNumberWhenAnyLogoPresent = Joi.alternatives()
+  .when('namedLogo', { is: Joi.string().required(), then: Joi.number() })
+  .when('logoSvg', { is: Joi.string().required(), then: Joi.number() })
+
+const serviceDataSchema = Joi.object({
+  isError: Joi.boolean(),
+  label: Joi.string().allow(''),
+  // While a number of badges pass a number here, in the long run we may want
+  // `render()` to always return a string.
+  message: Joi.alternatives(Joi.string().allow(''), Joi.number()).required(),
+  color: Joi.string(),
+  link: Joi.array()
+    .items(Joi.string().uri())
+    .single()
+    .max(2),
+  // Generally services should not use these options, which are provided to
+  // support the Endpoint badge.
+  labelColor: Joi.string(),
+  namedLogo: Joi.string(),
+  logoSvg: Joi.string(),
+  logoColor: optionalStringWhenNamedLogoPrsent,
+  logoWidth: optionalNumberWhenAnyLogoPresent,
+  logoPosition: optionalNumberWhenAnyLogoPresent,
+  cacheSeconds: Joi.number()
+    .integer()
+    .min(0),
+  style: Joi.string(),
+})
+  .oxor('namedLogo', 'logoSvg')
+  .required()
+
+module.exports = class BaseService {
+  /**
+   * Name of the category to sort this badge into (eg. "build"). Used to sort
+   * the badges on the main shields.io website.
+   */
+  static get category() {
+    throw new Error(`Category not set for ${this.name}`)
+  }
+
+  static get isDeprecated() {
+    return false
+  }
+
+  /**
+   * Returns an object:
+   *  - base: (Optional) The base path of the routes for this service. This is
+   *    used as a prefix.
+   *  - format: Regular expression to use for routes for this service's badges
+   *  - capture: Array of names for the capture groups in the regular
+   *             expression. The handler will be passed an object containing
+   *             the matches.
+   *  - queryParamSchema: (Optional) A Joi schema (`Joi.object({ ... }).required()`)
+   *                      for the query param object. If you know a parameter
+   *                      will never receive a numeric string, you can use
+   *                      `Joi.string()`. Because of quirks in Scoutcamp and Joi,
+   *                      alphanumeric strings should be declared using
+   *                      `Joi.alternatives().try(Joi.string(), Joi.number())`,
+   *                      otherwise a value like `?success_color=999` will fail.
+   *                      A parameter requiring a numeric string can use
+   *                      `Joi.number()`. A parameter that receives only non-numeric
+   *                      strings can use `Joi.string()`. A parameter that never
+   *                      receives numeric can use `Joi.string()`. A boolean
+   *                      parameter should use `Joi.equal('')` and will receive an
+   *                      empty string on e.g. `?compact_message` and undefined
+   *                      when the parameter is absent. (Note that in,
+   *                      `examples.queryParams` boolean query params should be given
+   *                      `null` values.)
+   */
+  static get route() {
+    throw new Error(`Route not defined for ${this.name}`)
+  }
+
+  /**
+   * Example URLs for this service. These should use the format
+   * specified in `route`, and can be used to demonstrate how to use badges for
+   * this service.
+   *
+   * The preferred way to specify an example is with `namedParams` which are
+   * substituted into the service's compiled route pattern. The rendered badge
+   * is specified with `staticPreview`.
+   *
+   * For services which use a route `format`, the `pattern` can be specified as
+   * part of the example.
+   *
+   * title: Descriptive text that will be shown next to the badge. The default
+   *   is to use the service class name, which probably is not what you want.
+   * namedParams: An object containing the values of named parameters to
+   *   substitute into the compiled route pattern.
+   * queryParams: An object containing query parameters to include in the
+   *   example URLs. For alphanumeric query parameters, specify a string value.
+   *   For boolean query parameters, specify `null`.
+   * pattern: The route pattern to compile. Defaults to `this.route.pattern`.
+   * staticPreview: A rendered badge of the sort returned by `handle()` or
+   *   `render()`: an object containing `message` and optional `label` and
+   *   `color`. This is usually generated by invoking `this.render()` with some
+   *   explicit props.
+   * keywords: Additional keywords, other than words in the title. This helps
+   *   users locate relevant badges.
+   * documentation: An HTML string that is included in the badge popup.
+   */
+  static get examples() {
+    return []
+  }
+
+  static get _cacheLength() {
+    const cacheLengths = {
+      build: 30,
+      license: 3600,
+      version: 300,
+      debug: 60,
+    }
+    return cacheLengths[this.category]
+  }
+
+  /**
+   * Default data for the badge. Can include label, logo, and color. These
+   * defaults are used if the value is neither included in the service data
+   * from the handler nor overridden by the user via query parameters.
+   */
+  static get defaultBadgeData() {
+    return {}
+  }
+
+  static render(props) {
+    throw new Error(`render() function not implemented for ${this.name}`)
+  }
+
+  static validateDefinition() {
+    assertValidCategory(this.category, `Category for ${this.name}`)
+
+    assertValidRoute(this.route, `Route for ${this.name}`)
+
+    Joi.assert(
+      this.defaultBadgeData,
+      defaultBadgeDataSchema,
+      `Default badge data for ${this.name}`
+    )
+
+    this.examples.forEach((example, index) =>
+      validateExample(example, index, this)
+    )
+  }
+
+  static getDefinition() {
+    const { category, name, isDeprecated } = this
+    const { base, format, pattern } = this.route
+    const queryParams = getQueryParamNames(this.route)
+
+    const examples = this.examples.map((example, index) =>
+      transformExample(example, index, this)
+    )
+
+    let route
+    if (pattern) {
+      route = { pattern: makeFullUrl(base, pattern), queryParams }
+    } else if (format) {
+      route = { format, queryParams }
+    } else {
+      route = undefined
+    }
+
+    const result = { category, name, isDeprecated, route, examples }
+
+    assertValidServiceDefinition(result, `getDefinition() for ${this.name}`)
+
+    return result
+  }
+
+  constructor({ sendAndCacheRequest }, { handleInternalErrors }) {
+    this._requestFetcher = sendAndCacheRequest
+    this._handleInternalErrors = handleInternalErrors
+  }
+
+  async _request({ url, options = {}, errorMessages = {} }) {
+    const logTrace = (...args) => trace.logTrace('fetch', ...args)
+    logTrace(emojic.bowAndArrow, 'Request', url, '\n', options)
+    const { res, buffer } = await this._requestFetcher(url, options)
+    logTrace(emojic.dart, 'Response status code', res.statusCode)
+    return checkErrorResponse(errorMessages)({ buffer, res })
+  }
+
+  static _validate(
+    data,
+    schema,
+    {
+      prettyErrorMessage = 'invalid response data',
+      includeKeys = false,
+      allowAndStripUnknownKeys = true,
+    } = {}
+  ) {
+    return validate(
+      {
+        ErrorClass: InvalidResponse,
+        prettyErrorMessage,
+        includeKeys,
+        traceErrorMessage: 'Response did not match schema',
+        traceSuccessMessage: 'Response after validation',
+        allowAndStripUnknownKeys,
+      },
+      data,
+      schema
+    )
+  }
+
+  /**
+   * Asynchronous function to handle requests for this service. Take the route
+   * parameters (as defined in the `route` property), perform a request using
+   * `this._sendAndCacheRequest`, and return the badge data.
+   */
+  async handle(namedParams, queryParams) {
+    throw new Error(`Handler not implemented for ${this.constructor.name}`)
+  }
+
+  _handleError(error) {
+    if (error instanceof NotFound || error instanceof InvalidParameter) {
+      trace.logTrace('outbound', emojic.noGoodWoman, 'Handled error', error)
+      return {
+        isError: true,
+        message: error.prettyMessage,
+        color: 'red',
+      }
+    } else if (
+      error instanceof InvalidResponse ||
+      error instanceof Inaccessible ||
+      error instanceof Deprecated
+    ) {
+      trace.logTrace('outbound', emojic.noGoodWoman, 'Handled error', error)
+      return {
+        isError: true,
+        message: error.prettyMessage,
+        color: 'lightgray',
+      }
+    } else if (this._handleInternalErrors) {
+      if (
+        !trace.logTrace(
+          'unhandledError',
+          emojic.boom,
+          'Unhandled internal error',
+          error
+        )
+      ) {
+        // This is where we end up if an unhandled exception is thrown in
+        // production. Send the error to the logs.
+        console.log(error)
+      }
+      return {
+        isError: true,
+        label: 'shields',
+        message: 'internal error',
+        color: 'lightgray',
+      }
+    } else {
+      trace.logTrace(
+        'unhandledError',
+        emojic.boom,
+        'Unhandled internal error',
+        error
+      )
+      throw error
+    }
+  }
+
+  static async invoke(
+    context = {},
+    config = {},
+    namedParams = {},
+    queryParams = {}
+  ) {
+    trace.logTrace('inbound', emojic.womanCook, 'Service class', this.name)
+    trace.logTrace('inbound', emojic.ticket, 'Named params', namedParams)
+    trace.logTrace('inbound', emojic.crayon, 'Query params', queryParams)
+
+    const serviceInstance = new this(context, config)
+
+    let serviceError
+    const { queryParamSchema } = this.route
+    let transformedQueryParams
+    if (queryParamSchema) {
+      try {
+        transformedQueryParams = validate(
+          {
+            ErrorClass: InvalidParameter,
+            prettyErrorMessage: 'invalid query parameter',
+            includeKeys: true,
+            traceErrorMessage: 'Query params did not match schema',
+            traceSuccessMessage: 'Query params after validation',
+          },
+          queryParams,
+          queryParamSchema
+        )
+        trace.logTrace(
+          'inbound',
+          emojic.crayon,
+          'Query params after validation',
+          queryParams
+        )
+      } catch (error) {
+        serviceError = error
+      }
+    } else {
+      transformedQueryParams = {}
+    }
+
+    let serviceData
+    if (!serviceError) {
+      try {
+        serviceData = await serviceInstance.handle(
+          namedParams,
+          transformedQueryParams
+        )
+        Joi.assert(serviceData, serviceDataSchema)
+      } catch (error) {
+        serviceError = error
+      }
+    }
+
+    if (serviceError) {
+      serviceData = serviceInstance._handleError(serviceError)
+    }
+
+    trace.logTrace('outbound', emojic.shield, 'Service data', serviceData)
+
+    return serviceData
+  }
+
+  static _createServiceRequestCounter({ requestCounter }) {
+    if (requestCounter) {
+      const { category, serviceFamily, name } = this
+      const service = decamelize(name)
+      return requestCounter.labels(category, serviceFamily, service)
+    } else {
+      // When metrics are disabled, return a mock counter.
+      return { inc: () => {} }
+    }
+  }
+
+  static register(
+    { camp, handleRequest, githubApiProvider, requestCounter },
+    serviceConfig
+  ) {
+    const { cacheHeaders: cacheHeaderConfig, fetchLimitBytes } = serviceConfig
+    const { regex, captureNames } = prepareRoute(this.route)
+    const queryParams = getQueryParamNames(this.route)
+
+    const serviceRequestCounter = this._createServiceRequestCounter({
+      requestCounter,
+    })
+
+    camp.route(
+      regex,
+      handleRequest(cacheHeaderConfig, {
+        queryParams,
+        handler: async (queryParams, match, sendBadge, request) => {
+          const namedParams = namedParamsForMatch(captureNames, match, this)
+          const serviceData = await this.invoke(
+            {
+              sendAndCacheRequest: request.asPromise,
+              sendAndCacheRequestWithCallbacks: request,
+              githubApiProvider,
+            },
+            serviceConfig,
+            namedParams,
+            queryParams
+          )
+
+          const badgeData = coalesceBadge(
+            queryParams,
+            serviceData,
+            this.defaultBadgeData,
+            this
+          )
+          // The final capture group is the extension.
+          const format = match.slice(-1)[0]
+          sendBadge(format, badgeData)
+
+          serviceRequestCounter.inc()
+        },
+        cacheLength: this._cacheLength,
+        fetchLimitBytes,
+      })
+    )
+  }
+}

core/base-service/base.spec.js

@@ -0,0 +1,485 @@
+'use strict'
+
+const Joi = require('joi')
+const { expect } = require('chai')
+const sinon = require('sinon')
+const trace = require('./trace')
+const {
+  NotFound,
+  Inaccessible,
+  InvalidResponse,
+  InvalidParameter,
+  Deprecated,
+} = require('./errors')
+const BaseService = require('./base')
+
+require('../register-chai-plugins.spec')
+
+const queryParamSchema = Joi.object({
+  queryParamA: Joi.string(),
+})
+  .rename('legacyQueryParamA', 'queryParamA', {
+    ignoreUndefined: true,
+    override: true,
+  })
+  .required()
+
+class DummyService extends BaseService {
+  static get category() {
+    return 'other'
+  }
+
+  static get route() {
+    return {
+      base: 'foo',
+      pattern: ':namedParamA',
+      queryParamSchema,
+    }
+  }
+
+  static get examples() {
+    return [
+      {
+        pattern: ':world',
+        namedParams: { world: 'World' },
+        staticPreview: this.render({ namedParamA: 'foo', queryParamA: 'bar' }),
+        keywords: ['hello'],
+      },
+    ]
+  }
+
+  static get defaultBadgeData() {
+    return { label: 'cat', namedLogo: 'appveyor' }
+  }
+
+  static render({ namedParamA, queryParamA }) {
+    return {
+      message: `Hello namedParamA: ${namedParamA} with queryParamA: ${queryParamA}`,
+    }
+  }
+
+  async handle({ namedParamA }, { queryParamA }) {
+    return this.constructor.render({ namedParamA, queryParamA })
+  }
+}
+
+describe('BaseService', function() {
+  const defaultConfig = { handleInternalErrors: false }
+
+  it('Invokes the handler as expected', async function() {
+    expect(
+      await DummyService.invoke(
+        {},
+        defaultConfig,
+        { namedParamA: 'bar.bar.bar' },
+        { queryParamA: '!' }
+      )
+    ).to.deep.equal({
+      message: 'Hello namedParamA: bar.bar.bar with queryParamA: !',
+    })
+  })
+
+  it('Validates query params', async function() {
+    expect(
+      await DummyService.invoke(
+        {},
+        defaultConfig,
+        { namedParamA: 'bar.bar.bar' },
+        { queryParamA: ['foo', 'bar'] }
+      )
+    ).to.deep.equal({
+      color: 'red',
+      isError: true,
+      message: 'invalid query parameter: queryParamA',
+    })
+  })
+
+  describe('Required overrides', function() {
+    it('Should throw if render() is not overridden', function() {
+      expect(() => BaseService.render()).to.throw(
+        'render() function not implemented for BaseService'
+      )
+    })
+
+    it('Should throw if route is not overridden', async function() {
+      try {
+        await BaseService.invoke({}, {}, {})
+        expect.fail('Expected to throw')
+      } catch (e) {
+        expect(e.message).to.equal('Route not defined for BaseService')
+      }
+    })
+
+    class WithRoute extends BaseService {
+      static get route() {
+        return {}
+      }
+    }
+    it('Should throw if handle() is not overridden', async function() {
+      try {
+        await WithRoute.invoke({}, {}, {})
+        expect.fail('Expected to throw')
+      } catch (e) {
+        expect(e.message).to.equal('Handler not implemented for WithRoute')
+      }
+    })
+
+    it('Should throw if category is not overridden', function() {
+      expect(() => BaseService.category).to.throw(
+        'Category not set for BaseService'
+      )
+    })
+  })
+
+  describe('Logging', function() {
+    let sandbox
+    beforeEach(function() {
+      sandbox = sinon.createSandbox()
+    })
+    afterEach(function() {
+      sandbox.restore()
+    })
+    beforeEach(function() {
+      sandbox.stub(trace, 'logTrace')
+    })
+    it('Invokes the logger as expected', async function() {
+      await DummyService.invoke(
+        {},
+        defaultConfig,
+        { namedParamA: 'bar.bar.bar' },
+        { queryParamA: '!' }
+      )
+      expect(trace.logTrace).to.be.calledWithMatch(
+        'inbound',
+        sinon.match.string,
+        'Service class',
+        'DummyService'
+      )
+      expect(trace.logTrace).to.be.calledWith(
+        'inbound',
+        sinon.match.string,
+        'Named params',
+        { namedParamA: 'bar.bar.bar' }
+      )
+      expect(trace.logTrace).to.be.calledWith(
+        'inbound',
+        sinon.match.string,
+        'Query params after validation',
+        { queryParamA: '!' }
+      )
+    })
+  })
+
+  describe('Service data validation', function() {
+    it('Allows a link array', async function() {
+      const message = 'hello'
+      const link = ['https://example.com/', 'https://other.example.com/']
+      class LinkService extends DummyService {
+        async handle() {
+          return { message, link }
+        }
+      }
+
+      const serviceData = await LinkService.invoke(
+        {},
+        { handleInternalErrors: false },
+        { namedParamA: 'bar.bar.bar' }
+      )
+
+      expect(serviceData).to.deep.equal({
+        message,
+        link,
+      })
+    })
+
+    it('Throws a validation error on invalid data', async function() {
+      class ThrowingService extends DummyService {
+        async handle() {
+          return {
+            some: 'nonsense',
+          }
+        }
+      }
+      try {
+        await ThrowingService.invoke(
+          {},
+          { handleInternalErrors: false },
+          { namedParamA: 'bar.bar.bar' }
+        )
+        expect.fail('Expected to throw')
+      } catch (e) {
+        expect(e.name).to.equal('ValidationError')
+        expect(e.details.map(({ message }) => message)).to.deep.equal([
+          '"message" is required',
+        ])
+      }
+    })
+  })
+
+  describe('Error handling', function() {
+    it('Handles internal errors', async function() {
+      class ThrowingService extends DummyService {
+        async handle() {
+          throw Error("I've made a huge mistake")
+        }
+      }
+      expect(
+        await ThrowingService.invoke(
+          {},
+          { handleInternalErrors: true },
+          { namedParamA: 'bar.bar.bar' }
+        )
+      ).to.deep.equal({
+        isError: true,
+        color: 'lightgray',
+        label: 'shields',
+        message: 'internal error',
+      })
+    })
+
+    describe('Handles known subtypes of ShieldsInternalError', function() {
+      it('handles NotFound errors', async function() {
+        class ThrowingService extends DummyService {
+          async handle() {
+            throw new NotFound()
+          }
+        }
+        expect(
+          await ThrowingService.invoke({}, {}, { namedParamA: 'bar.bar.bar' })
+        ).to.deep.equal({
+          isError: true,
+          color: 'red',
+          message: 'not found',
+        })
+      })
+
+      it('handles Inaccessible errors', async function() {
+        class ThrowingService extends DummyService {
+          async handle() {
+            throw new Inaccessible()
+          }
+        }
+        expect(
+          await ThrowingService.invoke({}, {}, { namedParamA: 'bar.bar.bar' })
+        ).to.deep.equal({
+          isError: true,
+          color: 'lightgray',
+          message: 'inaccessible',
+        })
+      })
+
+      it('handles InvalidResponse errors', async function() {
+        class ThrowingService extends DummyService {
+          async handle() {
+            throw new InvalidResponse()
+          }
+        }
+        expect(
+          await ThrowingService.invoke({}, {}, { namedParamA: 'bar.bar.bar' })
+        ).to.deep.equal({
+          isError: true,
+          color: 'lightgray',
+          message: 'invalid',
+        })
+      })
+
+      it('handles Deprecated', async function() {
+        class ThrowingService extends DummyService {
+          async handle() {
+            throw new Deprecated()
+          }
+        }
+        expect(
+          await ThrowingService.invoke({}, {}, { namedParamA: 'bar.bar.bar' })
+        ).to.deep.equal({
+          isError: true,
+          color: 'lightgray',
+          message: 'no longer available',
+        })
+      })
+
+      it('handles InvalidParameter errors', async function() {
+        class ThrowingService extends DummyService {
+          async handle() {
+            throw new InvalidParameter()
+          }
+        }
+        expect(
+          await ThrowingService.invoke({}, {}, { namedParamA: 'bar.bar.bar' })
+        ).to.deep.equal({
+          isError: true,
+          color: 'red',
+          message: 'invalid parameter',
+        })
+      })
+    })
+  })
+
+  describe('ScoutCamp integration', function() {
+    const expectedRouteRegex = /^\/foo\/([^/]+?)\.(svg|png|gif|jpg|json)$/
+
+    let mockCamp
+    let mockHandleRequest
+
+    beforeEach(function() {
+      mockCamp = {
+        route: sinon.spy(),
+      }
+      mockHandleRequest = sinon.spy()
+      DummyService.register(
+        { camp: mockCamp, handleRequest: mockHandleRequest },
+        defaultConfig
+      )
+    })
+
+    it('registers the service', function() {
+      expect(mockCamp.route).to.have.been.calledOnce
+      expect(mockCamp.route).to.have.been.calledWith(expectedRouteRegex)
+    })
+
+    it('handles the request', async function() {
+      expect(mockHandleRequest).to.have.been.calledOnce
+
+      const {
+        queryParams: serviceQueryParams,
+        handler: requestHandler,
+      } = mockHandleRequest.getCall(0).args[1]
+      expect(serviceQueryParams).to.deep.equal([
+        'queryParamA',
+        'legacyQueryParamA',
+      ])
+
+      const mockSendBadge = sinon.spy()
+      const mockRequest = {
+        asPromise: sinon.spy(),
+      }
+      const queryParams = { queryParamA: '?' }
+      const match = '/foo/bar.svg'.match(expectedRouteRegex)
+      await requestHandler(queryParams, match, mockSendBadge, mockRequest)
+
+      const expectedFormat = 'svg'
+      expect(mockSendBadge).to.have.been.calledOnce
+      expect(mockSendBadge).to.have.been.calledWith(expectedFormat, {
+        text: ['cat', 'Hello namedParamA: bar with queryParamA: ?'],
+        color: 'lightgrey',
+        template: undefined,
+        namedLogo: undefined,
+        logo: undefined,
+        logoWidth: undefined,
+        logoPosition: undefined,
+        links: [],
+        labelColor: undefined,
+        cacheLengthSeconds: undefined,
+      })
+    })
+  })
+
+  describe('getDefinition', function() {
+    it('returns the expected result', function() {
+      const {
+        category,
+        name,
+        isDeprecated,
+        route,
+        examples,
+      } = DummyService.getDefinition()
+      expect({
+        category,
+        name,
+        isDeprecated,
+        route,
+      }).to.deep.equal({
+        category: 'other',
+        name: 'DummyService',
+        isDeprecated: false,
+        route: {
+          pattern: '/foo/:namedParamA',
+          queryParams: ['queryParamA', 'legacyQueryParamA'],
+        },
+      })
+      // The in-depth tests for examples reside in examples.spec.js
+      expect(examples).to.have.lengthOf(1)
+    })
+  })
+
+  describe('validate', function() {
+    const dummySchema = Joi.object({
+      requiredString: Joi.string().required(),
+    }).required()
+
+    it('throws error for invalid responses', async function() {
+      try {
+        DummyService._validate(
+          { requiredString: ['this', "shouldn't", 'work'] },
+          dummySchema
+        )
+        expect.fail('Expected to throw')
+      } catch (e) {
+        expect(e).to.be.an.instanceof(InvalidResponse)
+      }
+    })
+  })
+
+  describe('request', function() {
+    let sandbox
+    beforeEach(function() {
+      sandbox = sinon.createSandbox()
+    })
+    afterEach(function() {
+      sandbox.restore()
+    })
+    beforeEach(function() {
+      sandbox.stub(trace, 'logTrace')
+    })
+
+    it('logs appropriate information', async function() {
+      const sendAndCacheRequest = async () => ({
+        buffer: '',
+        res: { statusCode: 200 },
+      })
+      const serviceInstance = new DummyService(
+        { sendAndCacheRequest },
+        defaultConfig
+      )
+
+      const url = 'some-url'
+      const options = { headers: { Cookie: 'some-cookie' } }
+      await serviceInstance._request({ url, options })
+
+      expect(trace.logTrace).to.be.calledWithMatch(
+        'fetch',
+        sinon.match.string,
+        'Request',
+        url,
+        '\n',
+        options
+      )
+      expect(trace.logTrace).to.be.calledWithMatch(
+        'fetch',
+        sinon.match.string,
+        'Response status code',
+        200
+      )
+    })
+
+    it('handles errors', async function() {
+      const sendAndCacheRequest = async () => ({
+        buffer: '',
+        res: { statusCode: 404 },
+      })
+      const serviceInstance = new DummyService(
+        { sendAndCacheRequest },
+        defaultConfig
+      )
+
+      try {
+        await serviceInstance._request({})
+        expect.fail('Expected to throw')
+      } catch (e) {
+        expect(e).to.be.an.instanceof(NotFound)
+        expect(e.message).to.equal('Not Found')
+        expect(e.prettyMessage).to.equal('not found')
+      }
+    })
+  })
+})

core/base-service/cache-headers.js

@@ -0,0 +1,115 @@
+'use strict'
+
+const assert = require('assert')
+const Joi = require('joi')
+const coalesce = require('./coalesce')
+
+const serverStartTimeGMTString = new Date().toGMTString()
+const serverStartTimestamp = Date.now()
+
+const isOptionalNonNegativeInteger = Joi.number()
+  .integer()
+  .min(0)
+
+const queryParamSchema = Joi.object({
+  cacheSeconds: isOptionalNonNegativeInteger,
+  maxAge: isOptionalNonNegativeInteger,
+})
+  .oxor('cacheSeconds', 'maxAge')
+  .unknown(true)
+  .required()
+
+function overrideCacheLengthFromQueryParams(queryParams) {
+  try {
+    const {
+      cacheSeconds: overrideCacheLength,
+      maxAge: legacyOverrideCacheLength,
+    } = Joi.attempt(queryParams, queryParamSchema)
+    return coalesce(overrideCacheLength, legacyOverrideCacheLength)
+  } catch (e) {
+    return undefined
+  }
+}
+
+function coalesceCacheLength({
+  cacheHeaderConfig,
+  serviceDefaultCacheLengthSeconds,
+  serviceOverrideCacheLengthSeconds,
+  queryParams,
+}) {
+  const { defaultCacheLengthSeconds } = cacheHeaderConfig
+  // The config returns a number so this should never happen. But this logic
+  // would be completely broken if it did.
+  assert(defaultCacheLengthSeconds !== undefined)
+
+  const cacheLength = coalesce(
+    serviceDefaultCacheLengthSeconds,
+    defaultCacheLengthSeconds
+  )
+
+  // Overrides can apply _more_ caching, but not less. Query param overriding
+  // can request more overriding than service override, but not less.
+  const candidateOverrides = [
+    serviceOverrideCacheLengthSeconds,
+    overrideCacheLengthFromQueryParams(queryParams),
+  ].filter(x => x !== undefined)
+
+  return Math.max(cacheLength, ...candidateOverrides)
+}
+
+function setHeadersForCacheLength(res, cacheLengthSeconds) {
+  const now = new Date()
+  const nowGMTString = now.toGMTString()
+
+  // Send both Cache-Control max-age and Expires in case the client implements
+  // HTTP/1.0 but not HTTP/1.1.
+  let cacheControl, expires
+  if (cacheLengthSeconds === 0) {
+    // Prevent as much downstream caching as possible.
+    cacheControl = 'no-cache, no-store, must-revalidate'
+    expires = nowGMTString
+  } else {
+    cacheControl = `max-age=${cacheLengthSeconds}`
+    expires = new Date(now.getTime() + cacheLengthSeconds * 1000).toGMTString()
+  }
+
+  res.setHeader('Date', nowGMTString)
+  res.setHeader('Cache-Control', cacheControl)
+  res.setHeader('Expires', expires)
+}
+
+function setCacheHeaders({
+  cacheHeaderConfig,
+  serviceDefaultCacheLengthSeconds,
+  serviceOverrideCacheLengthSeconds,
+  queryParams,
+  res,
+}) {
+  const cacheLengthSeconds = coalesceCacheLength({
+    cacheHeaderConfig,
+    serviceDefaultCacheLengthSeconds,
+    serviceOverrideCacheLengthSeconds,
+    queryParams,
+  })
+  setHeadersForCacheLength(res, cacheLengthSeconds)
+}
+
+const staticCacheControlHeader = `max-age=${24 * 3600}` // 1 day.
+function setCacheHeadersForStaticResource(res) {
+  res.setHeader('Cache-Control', staticCacheControlHeader)
+  res.setHeader('Last-Modified', serverStartTimeGMTString)
+}
+
+function serverHasBeenUpSinceResourceCached(req) {
+  return (
+    serverStartTimestamp <= new Date(req.headers['if-modified-since']).getTime()
+  )
+}
+
+module.exports = {
+  coalesceCacheLength,
+  setCacheHeaders,
+  setHeadersForCacheLength,
+  setCacheHeadersForStaticResource,
+  serverHasBeenUpSinceResourceCached,
+}

core/base-service/cache-headers.spec.js

@@ -0,0 +1,241 @@
+'use strict'
+
+const { test, given } = require('sazerac')
+const chai = require('chai')
+const { expect } = require('chai')
+const sinon = require('sinon')
+const httpMocks = require('node-mocks-http')
+const {
+  coalesceCacheLength,
+  setHeadersForCacheLength,
+  setCacheHeaders,
+  setCacheHeadersForStaticResource,
+  serverHasBeenUpSinceResourceCached,
+} = require('./cache-headers')
+
+chai.use(require('chai-datetime'))
+
+describe('Cache header functions', function() {
+  let res
+  beforeEach(function() {
+    res = httpMocks.createResponse()
+  })
+
+  describe('coalesceCacheLength', function() {
+    const cacheHeaderConfig = { defaultCacheLengthSeconds: 777 }
+    test(coalesceCacheLength, () => {
+      given({ cacheHeaderConfig, queryParams: {} }).expect(777)
+      given({
+        cacheHeaderConfig,
+        serviceDefaultCacheLengthSeconds: 900,
+        queryParams: {},
+      }).expect(900)
+      given({
+        cacheHeaderConfig,
+        serviceDefaultCacheLengthSeconds: 900,
+        queryParams: { cacheSeconds: 1000 },
+      }).expect(1000)
+      given({
+        cacheHeaderConfig,
+        serviceDefaultCacheLengthSeconds: 900,
+        queryParams: { cacheSeconds: 1000, other: 'here', maybe: 'bogus' },
+      }).expect(1000)
+      given({
+        cacheHeaderConfig,
+        serviceDefaultCacheLengthSeconds: 900,
+        queryParams: { cacheSeconds: 400 },
+      }).expect(900)
+      given({
+        cacheHeaderConfig,
+        serviceDefaultCacheLengthSeconds: 900,
+        queryParams: { cacheSeconds: '-1000' },
+      }).expect(900)
+      given({
+        cacheHeaderConfig,
+        serviceDefaultCacheLengthSeconds: 900,
+        queryParams: { cacheSeconds: '' },
+      }).expect(900)
+      given({
+        cacheHeaderConfig,
+        serviceDefaultCacheLengthSeconds: 900,
+        queryParams: { cacheSeconds: 'not a number' },
+      }).expect(900)
+      given({
+        cacheHeaderConfig,
+        serviceDefaultCacheLengthSeconds: 900,
+        // Legacy name.
+        queryParams: { maxAge: 1000 },
+      }).expect(1000)
+      given({
+        cacheHeaderConfig,
+        serviceDefaultCacheLengthSeconds: 900,
+        // Both legacy and new name provided -> both ignored.
+        queryParams: { maxAge: 1000, cacheSeconds: 1000 },
+      }).expect(900)
+      given({
+        cacheHeaderConfig,
+        serviceDefaultCacheLengthSeconds: 900,
+        serviceOverrideCacheLengthSeconds: 400,
+        queryParams: {},
+      }).expect(900)
+      given({
+        cacheHeaderConfig,
+        serviceOverrideCacheLengthSeconds: 400,
+        queryParams: {},
+      }).expect(777)
+      given({
+        cacheHeaderConfig,
+        serviceOverrideCacheLengthSeconds: 900,
+        queryParams: {},
+      }).expect(900)
+      given({
+        cacheHeaderConfig,
+        serviceOverrideCacheLengthSeconds: 800,
+        queryParams: { cacheSeconds: 500 },
+      }).expect(800)
+      given({
+        cacheHeaderConfig,
+        serviceOverrideCacheLengthSeconds: 900,
+        queryParams: { cacheSeconds: 800 },
+      }).expect(900)
+    })
+  })
+
+  describe('setHeadersForCacheLength', function() {
+    let sandbox
+    beforeEach(function() {
+      sandbox = sinon.createSandbox()
+      sandbox.useFakeTimers()
+    })
+    afterEach(function() {
+      sandbox.restore()
+      sandbox = undefined
+    })
+
+    it('should set the correct Date header', function() {
+      // Confidence check.
+      expect(res._headers.date).to.equal(undefined)
+
+      // Act.
+      setHeadersForCacheLength(res, 123)
+
+      // Assert.
+      const now = new Date().toGMTString()
+      expect(res._headers.date).to.equal(now)
+    })
+
+    context('cacheLengthSeconds is zero', function() {
+      beforeEach(function() {
+        setHeadersForCacheLength(res, 0)
+      })
+
+      it('should set the expected Cache-Control header', function() {
+        expect(res._headers['cache-control']).to.equal(
+          'no-cache, no-store, must-revalidate'
+        )
+      })
+
+      it('should set the expected Expires header', function() {
+        expect(res._headers.expires).to.equal(new Date().toGMTString())
+      })
+    })
+
+    context('cacheLengthSeconds is nonzero', function() {
+      beforeEach(function() {
+        setHeadersForCacheLength(res, 123)
+      })
+
+      it('should set the expected Cache-Control header', function() {
+        expect(res._headers['cache-control']).to.equal('max-age=123')
+      })
+
+      it('should set the expected Expires header', function() {
+        const expires = new Date(Date.now() + 123 * 1000).toGMTString()
+        expect(res._headers.expires).to.equal(expires)
+      })
+    })
+  })
+
+  describe('setCacheHeaders', function() {
+    it('sets the expected fields', function() {
+      const expectedFields = ['date', 'cache-control', 'expires']
+      expectedFields.forEach(field =>
+        expect(res._headers[field]).to.equal(undefined)
+      )
+
+      setCacheHeaders({
+        cacheHeaderConfig: { defaultCacheLengthSeconds: 1234 },
+        serviceDefaultCacheLengthSeconds: 567,
+        queryParams: { cacheSeconds: 999999 },
+        res,
+      })
+
+      expectedFields.forEach(field =>
+        expect(res._headers[field])
+          .to.be.a('string')
+          .and.have.lengthOf.at.least(1)
+      )
+    })
+  })
+
+  describe('setCacheHeadersForStaticResource', function() {
+    beforeEach(function() {
+      setCacheHeadersForStaticResource(res)
+    })
+
+    it('should set the expected Cache-Control header', function() {
+      expect(res._headers['cache-control']).to.equal(`max-age=${24 * 3600}`)
+    })
+
+    it('should set the expected Last-Modified header', function() {
+      const lastModified = res._headers['last-modified']
+      expect(new Date(lastModified)).to.be.withinTime(
+        // Within the last 60 seconds.
+        new Date(Date.now() - 60 * 1000),
+        new Date()
+      )
+    })
+  })
+
+  describe('serverHasBeenUpSinceResourceCached', function() {
+    // The stringified req's are hard to understand. I thought Sazerac
+    // provided a way to override the describe message, though I can't find it.
+    context('when there is no If-Modified-Since header', function() {
+      it('returns false', function() {
+        const req = httpMocks.createRequest()
+        expect(serverHasBeenUpSinceResourceCached(req)).to.equal(false)
+      })
+    })
+    context('when the If-Modified-Since header is invalid', function() {
+      it('returns false', function() {
+        const req = httpMocks.createRequest({
+          headers: { 'If-Modified-Since': 'this-is-not-a-date' },
+        })
+        expect(serverHasBeenUpSinceResourceCached(req)).to.equal(false)
+      })
+    })
+    context(
+      'when the If-Modified-Since header is before the process started',
+      function() {
+        it('returns false', function() {
+          const req = httpMocks.createRequest({
+            headers: { 'If-Modified-Since': '2018-02-01T05:00:00.000Z' },
+          })
+          expect(serverHasBeenUpSinceResourceCached(req)).to.equal(false)
+        })
+      }
+    )
+    context(
+      'when the If-Modified-Since header is after the process started',
+      function() {
+        it('returns true', function() {
+          const modifiedTimeStamp = new Date(Date.now() + 1800000)
+          const req = httpMocks.createRequest({
+            headers: { 'If-Modified-Since': modifiedTimeStamp.toISOString() },
+          })
+          expect(serverHasBeenUpSinceResourceCached(req)).to.equal(true)
+        })
+      }
+    )
+  })
+})

core/base-service/categories.js

@@ -0,0 +1,19 @@
+'use strict'
+
+const Joi = require('joi')
+const categories = require('../../services/categories')
+
+const isRealCategory = Joi.equal(categories.map(({ id }) => id)).required()
+
+const isValidCategory = Joi.alternatives()
+  .try(isRealCategory, Joi.equal('debug', 'dynamic', 'static').required())
+  .required()
+
+function assertValidCategory(category, message = undefined) {
+  Joi.assert(category, isValidCategory, message)
+}
+
+module.exports = {
+  isValidCategory,
+  assertValidCategory,
+}

core/base-service/check-error-response.js

@@ -0,0 +1,37 @@
+'use strict'
+
+const { NotFound, InvalidResponse, Inaccessible } = require('./errors')
+
+const defaultErrorMessages = {
+  404: 'not found',
+}
+
+module.exports = function checkErrorResponse(errorMessages = {}) {
+  return async function({ buffer, res }) {
+    let error
+    errorMessages = { ...defaultErrorMessages, ...errorMessages }
+    if (res.statusCode === 404) {
+      error = new NotFound({ prettyMessage: errorMessages[404] })
+    } else if (res.statusCode !== 200) {
+      const underlying = Error(
+        `Got status code ${res.statusCode} (expected 200)`
+      )
+      const props = { underlyingError: underlying }
+      if (errorMessages[res.statusCode] !== undefined) {
+        props.prettyMessage = errorMessages[res.statusCode]
+      }
+      if (res.statusCode >= 500) {
+        error = new Inaccessible(props)
+      } else {
+        error = new InvalidResponse(props)
+      }
+    }
+    if (error) {
+      error.response = res
+      error.buffer = buffer
+      throw error
+    } else {
+      return { buffer, res }
+    }
+  }
+}

core/base-service/check-error-response.spec.js

@@ -1,82 +1,43 @@
 'use strict'
 
 const { expect } = require('chai')
-const { checkErrorResponse } = require('./error-helper')
-const {
-  NotFound,
-  InvalidResponse,
-  Inaccessible,
-} = require('../services/errors')
-
-describe('Standard Error Handler', function() {
-  it('makes inaccessible badge', function() {
-    const badgeData = { text: [] }
-    expect(checkErrorResponse(badgeData, 'something other than null', {})).to.be
-      .true
-    expect(badgeData.text[1]).to.equal('inaccessible')
-    expect(badgeData.colorscheme).to.equal('red')
-  })
-
-  it('makes not found badge', function() {
-    const badgeData = { text: [] }
-    expect(checkErrorResponse(badgeData, null, { statusCode: 404 })).to.be.true
-    expect(badgeData.text[1]).to.equal('not found')
-    expect(badgeData.colorscheme).to.equal('lightgrey')
-  })
-
-  it('makes not found badge with custom error', function() {
-    const badgeData = { text: [] }
-    expect(
-      checkErrorResponse(
-        badgeData,
-        null,
-        { statusCode: 404 },
-        { 404: 'custom message' }
-      )
-    ).to.be.true
-    expect(badgeData.text[1]).to.equal('custom message')
-    expect(badgeData.colorscheme).to.equal('lightgrey')
-  })
-
-  it('makes invalid badge', function() {
-    const badgeData = { text: [] }
-    expect(checkErrorResponse(badgeData, null, { statusCode: 500 })).to.be.true
-    expect(badgeData.text[1]).to.equal('invalid')
-    expect(badgeData.colorscheme).to.equal('lightgrey')
-  })
-
-  it('return false on 200 status', function() {
-    expect(checkErrorResponse({ text: [] }, null, { statusCode: 200 })).to.be
-      .false
-  })
-})
+const { NotFound, InvalidResponse, Inaccessible } = require('./errors')
+const checkErrorResponse = require('./check-error-response')
 
 describe('async error handler', function() {
+  const buffer = Buffer.from('some stuff')
+
   context('when status is 200', function() {
     it('passes through the inputs', async function() {
-      const args = { buffer: 'buffer', res: { statusCode: 200 } }
-      expect(await checkErrorResponse.asPromise()(args)).to.deep.equal(args)
+      const res = { statusCode: 200 }
+      expect(await checkErrorResponse()({ res, buffer })).to.deep.equal({
+        res,
+        buffer,
+      })
     })
   })
 
   context('when status is 404', function() {
+    const buffer = Buffer.from('some stuff')
     const res = { statusCode: 404 }
 
     it('throws NotFound', async function() {
       try {
-        await checkErrorResponse.asPromise()({ res })
+        await checkErrorResponse()({ res, buffer })
         expect.fail('Expected to throw')
       } catch (e) {
         expect(e).to.be.an.instanceof(NotFound)
         expect(e.message).to.equal('Not Found')
         expect(e.prettyMessage).to.equal('not found')
+        expect(e.response).to.equal(res)
+        expect(e.buffer).to.equal(buffer)
       }
     })
 
     it('displays the custom not found message', async function() {
       const notFoundMessage = 'no goblins found'
       try {
-        await checkErrorResponse.asPromise({ 404: notFoundMessage })({ res })
+        await checkErrorResponse({ 404: notFoundMessage })({ res, buffer })
         expect.fail('Expected to throw')
       } catch (e) {
         expect(e).to.be.an.instanceof(NotFound)
@@ -90,7 +51,7 @@ describe('async error handler', function() {
     it('throws InvalidResponse', async function() {
       const res = { statusCode: 499 }
       try {
-        await checkErrorResponse.asPromise()({ res })
+        await checkErrorResponse()({ res, buffer })
         expect.fail('Expected to throw')
       } catch (e) {
         expect(e).to.be.an.instanceof(InvalidResponse)
@@ -98,15 +59,15 @@ describe('async error handler', function() {
           'Invalid Response: Got status code 499 (expected 200)'
         )
         expect(e.prettyMessage).to.equal('invalid')
+        expect(e.response).to.equal(res)
+        expect(e.buffer).to.equal(buffer)
       }
     })
 
     it('displays the custom error message', async function() {
       const res = { statusCode: 403 }
       try {
-        await checkErrorResponse.asPromise({
-          403: 'access denied',
-        })({ res })
+        await checkErrorResponse({ 403: 'access denied' })({ res })
         expect.fail('Expected to throw')
       } catch (e) {
         expect(e).to.be.an.instanceof(InvalidResponse)
@@ -122,7 +83,7 @@ describe('async error handler', function() {
     it('throws Inaccessible', async function() {
       const res = { statusCode: 503 }
       try {
-        await checkErrorResponse.asPromise()({ res })
+        await checkErrorResponse()({ res, buffer })
         expect.fail('Expected to throw')
       } catch (e) {
         expect(e).to.be.an.instanceof(Inaccessible)
@@ -130,15 +91,15 @@ describe('async error handler', function() {
           'Inaccessible: Got status code 503 (expected 200)'
         )
         expect(e.prettyMessage).to.equal('inaccessible')
+        expect(e.response).to.equal(res)
+        expect(e.buffer).to.equal(buffer)
       }
     })
 
     it('displays the custom error message', async function() {
       const res = { statusCode: 500 }
       try {
-        await checkErrorResponse.asPromise({
-          500: 'server overloaded',
-        })({ res })
+        await checkErrorResponse({ 500: 'server overloaded' })({ res, buffer })
         expect.fail('Expected to throw')
       } catch (e) {
         expect(e).to.be.an.instanceof(Inaccessible)

core/base-service/coalesce-badge.js

@@ -0,0 +1,174 @@
+'use strict'
+
+const {
+  decodeDataUrlFromQueryParam,
+  prepareNamedLogo,
+} = require('../../lib/logos')
+const { svg2base64 } = require('../../lib/svg-helpers')
+const coalesce = require('./coalesce')
+const toArray = require('./to-array')
+
+// Translate modern badge data to the legacy schema understood by the badge
+// maker. Allow the user to override the label, color, logo, etc. through the
+// query string. Provide support for most badge options via `serviceData` so
+// the Endpoint badge can specify logos and colors, though allow that the
+// user's logo or color to take precedence. A notable exception is the case of
+// errors. When the service specifies that an error has occurred, the user's
+// requested color does not override the error color.
+//
+// Logos are resolved in this manner:
+//
+// 1. When `?logo=` contains the name of one of the Shields logos, or contains
+//    base64-encoded SVG, that logo is used. In the case of a named logo, when
+//    a `&logoColor=` is specified, that color is used. Otherwise the default
+//    color is used. `logoColor` will not be applied to a custom
+//    (base64-encoded) logo; if a custom color is desired the logo should be
+//    recolored prior to making the request. The appearance of the logo can be
+//    customized using `logoWidth`, and in the case of the popout badge,
+//    `logoPosition`. When `?logo=` is specified, any logo-related parameters
+//    specified dynamically by the service, or by default in the service, are
+//    ignored.
+// 2. The second precedence is the dynamic logo returned by a service. This is
+//    used only by the Endpoint badge. The `logoColor` can be overridden by the
+//    query string.
+// 3. In the case of the `social` style only, the last precedence is the
+//    service's default logo. The `logoColor` can be overridden by the query
+//    string.
+module.exports = function coalesceBadge(
+  overrides,
+  serviceData,
+  // These two parameters were kept separate to make tests clearer.
+  defaultBadgeData,
+  { category, _cacheLength: defaultCacheSeconds } = {}
+) {
+  // The "overrideX" naming is based on services that provide badge
+  // parameters themselves, which can be overridden by a query string
+  // parameter. (For a couple services, the dynamic badge and the
+  // query-string-based static badge, the service never sets a value
+  // so the query string overrides are the _only_ way to configure
+  // these badge parameters.
+  const {
+    style: overrideStyle,
+    label: overrideLabel,
+    logo: overrideLogo,
+    logoColor: overrideLogoColor,
+    link: overrideLink,
+    colorB: legacyOverrideColor,
+    colorA: legacyOverrideLabelColor,
+  } = overrides
+  let {
+    logoWidth: overrideLogoWidth,
+    logoPosition: overrideLogoPosition,
+    color: overrideColor,
+    labelColor: overrideLabelColor,
+  } = overrides
+
+  // Only use the legacy properties if the new ones are not provided
+  if (typeof overrideColor === 'undefined') {
+    overrideColor = legacyOverrideColor
+  }
+  if (typeof overrideLabelColor === 'undefined') {
+    overrideLabelColor = legacyOverrideLabelColor
+  }
+
+  // Scoutcamp converts numeric query params to numbers. Convert them back.
+  if (typeof overrideColor === 'number') {
+    overrideColor = `${overrideColor}`
+  }
+  if (typeof overrideLabelColor === 'number') {
+    overrideLabelColor = `${overrideLabelColor}`
+  }
+  overrideLogoWidth = +overrideLogoWidth || undefined
+  overrideLogoPosition = +overrideLogoPosition || undefined
+
+  const {
+    isError,
+    label: serviceLabel,
+    message: serviceMessage,
+    color: serviceColor,
+    labelColor: serviceLabelColor,
+    logoSvg: serviceLogoSvg,
+    namedLogo: serviceNamedLogo,
+    logoColor: serviceLogoColor,
+    logoWidth: serviceLogoWidth,
+    logoPosition: serviceLogoPosition,
+    link: serviceLink,
+    cacheSeconds: serviceCacheSeconds,
+    style: serviceStyle,
+  } = serviceData
+
+  const {
+    color: defaultColor,
+    namedLogo: defaultNamedLogo,
+    label: defaultLabel,
+    labelColor: defaultLabelColor,
+  } = defaultBadgeData
+
+  const style = coalesce(overrideStyle, serviceStyle)
+
+  let namedLogo, namedLogoColor, logoWidth, logoPosition, logoSvgBase64
+  if (overrideLogo) {
+    // `?logo=` could be a named logo or encoded svg.
+    const overrideLogoSvgBase64 = decodeDataUrlFromQueryParam(overrideLogo)
+    if (overrideLogoSvgBase64) {
+      logoSvgBase64 = overrideLogoSvgBase64
+    } else {
+      namedLogo = overrideLogo
+      // If the logo has been overridden it does not make sense to inherit the
+      // original color.
+      namedLogoColor = overrideLogoColor
+    }
+    // If the logo has been overridden it does not make sense to inherit the
+    // original width or position.
+    logoWidth = overrideLogoWidth
+    logoPosition = overrideLogoPosition
+  } else {
+    if (serviceLogoSvg) {
+      logoSvgBase64 = svg2base64(serviceLogoSvg)
+    } else {
+      namedLogo = coalesce(
+        serviceNamedLogo,
+        style === 'social' ? defaultNamedLogo : undefined
+      )
+      namedLogoColor = coalesce(overrideLogoColor, serviceLogoColor)
+    }
+    logoWidth = coalesce(overrideLogoWidth, serviceLogoWidth)
+    logoPosition = coalesce(overrideLogoPosition, serviceLogoPosition)
+  }
+  if (namedLogo) {
+    logoSvgBase64 = prepareNamedLogo({
+      name: namedLogo,
+      color: namedLogoColor,
+      style,
+    })
+  }
+
+  return {
+    text: [
+      // Use `coalesce()` to support empty labels and messages, as in the
+      // static badge.
+      coalesce(overrideLabel, serviceLabel, defaultLabel, category),
+      coalesce(serviceMessage, 'n/a'),
+    ],
+    color: coalesce(
+      // In case of an error, disregard user's color override.
+      isError ? undefined : overrideColor,
+      serviceColor,
+      defaultColor,
+      'lightgrey'
+    ),
+    labelColor: coalesce(
+      // In case of an error, disregard user's color override.
+      isError ? undefined : overrideLabelColor,
+      serviceLabelColor,
+      defaultLabelColor
+    ),
+    template: style,
+    namedLogo,
+    logo: logoSvgBase64,
+    logoWidth,
+    logoPosition,
+    links: toArray(overrideLink || serviceLink),
+    cacheLengthSeconds: coalesce(serviceCacheSeconds, defaultCacheSeconds),
+  }
+}

core/base-service/coalesce-badge.spec.js

@@ -0,0 +1,294 @@
+'use strict'
+
+const { expect } = require('chai')
+const { getShieldsIcon, getSimpleIcon } = require('../../lib/logos')
+const coalesceBadge = require('./coalesce-badge')
+
+describe('coalesceBadge', function() {
+  describe('Label', function() {
+    it('uses the default label', function() {
+      expect(coalesceBadge({}, {}, { label: 'heyo' }).text).to.deep.equal([
+        'heyo',
+        'n/a',
+      ])
+    })
+
+    // This behavior isn't great and we might want to remove it.
+    it('uses the category as a default label', function() {
+      expect(coalesceBadge({}, {}, {}, { category: 'cat' }).text).to.deep.equal(
+        ['cat', 'n/a']
+      )
+    })
+
+    it('preserves an empty label', function() {
+      expect(
+        coalesceBadge({}, { label: '', message: '10k' }, {}).text
+      ).to.deep.equal(['', '10k'])
+    })
+
+    it('overrides the label', function() {
+      expect(
+        coalesceBadge({ label: 'purr count' }, { label: 'purrs' }, {}).text
+      ).to.deep.equal(['purr count', 'n/a'])
+    })
+  })
+
+  describe('Message', function() {
+    it('applies the service message', function() {
+      expect(coalesceBadge({}, { message: '10k' }, {}).text).to.deep.equal([
+        undefined,
+        '10k',
+      ])
+    })
+
+    it('applies a numeric service message', function() {
+      // While a number of badges use this, in the long run we may want
+      // `render()` to always return a string.
+      expect(coalesceBadge({}, { message: 10 }, {}).text).to.deep.equal([
+        undefined,
+        10,
+      ])
+    })
+  })
+
+  describe('Right color', function() {
+    it('uses the default color', function() {
+      expect(coalesceBadge({}, {}, {}).color).to.equal('lightgrey')
+    })
+
+    it('overrides the color', function() {
+      expect(
+        coalesceBadge({ color: '10ADED' }, { color: 'red' }, {}).color
+      ).to.equal('10ADED')
+      // also expected for legacy name
+      expect(
+        coalesceBadge({ colorB: 'B0ADED' }, { color: 'red' }, {}).color
+      ).to.equal('B0ADED')
+    })
+
+    context('In case of an error', function() {
+      it('does not override the color', function() {
+        expect(
+          coalesceBadge(
+            { color: '10ADED' },
+            { isError: true, color: 'lightgray' },
+            {}
+          ).color
+        ).to.equal('lightgray')
+        // also expected for legacy name
+        expect(
+          coalesceBadge(
+            { colorB: 'B0ADED' },
+            { isError: true, color: 'lightgray' },
+            {}
+          ).color
+        ).to.equal('lightgray')
+      })
+    })
+
+    it('applies the service color', function() {
+      expect(coalesceBadge({}, { color: 'red' }, {}).color).to.equal('red')
+    })
+  })
+
+  describe('Left color', function() {
+    it('provides no default label color', function() {
+      expect(coalesceBadge({}, {}, {}).labelColor).to.be.undefined
+    })
+
+    it('applies the service label color', function() {
+      expect(coalesceBadge({}, { labelColor: 'red' }, {}).labelColor).to.equal(
+        'red'
+      )
+    })
+
+    it('overrides the label color', function() {
+      expect(
+        coalesceBadge({ labelColor: '42f483' }, { color: 'green' }, {})
+          .labelColor
+      ).to.equal('42f483')
+      // also expected for legacy name
+      expect(
+        coalesceBadge({ colorA: 'B2f483' }, { color: 'green' }, {}).labelColor
+      ).to.equal('B2f483')
+    })
+
+    it('converts a query-string numeric color to a string', function() {
+      expect(
+        coalesceBadge(
+          // Scoutcamp converts numeric query params to numbers.
+          { color: 123 },
+          { color: 'green' },
+          {}
+        ).color
+      ).to.equal('123')
+      // also expected for legacy name
+      expect(
+        coalesceBadge(
+          // Scoutcamp converts numeric query params to numbers.
+          { colorB: 123 },
+          { color: 'green' },
+          {}
+        ).color
+      ).to.equal('123')
+    })
+  })
+
+  describe('Named logos', function() {
+    it('when not a social badge, ignores the default named logo', function() {
+      expect(coalesceBadge({}, {}, { namedLogo: 'appveyor' }).logo).to.be
+        .undefined
+    })
+
+    it('when a social badge, uses the default named logo', function() {
+      // .not.be.empty for confidence that nothing has changed with `getShieldsIcon()`.
+      expect(
+        coalesceBadge({ style: 'social' }, {}, { namedLogo: 'appveyor' }).logo
+      ).to.equal(getSimpleIcon({ name: 'appveyor' })).and.not.be.empty
+    })
+
+    it('applies the named logo', function() {
+      expect(coalesceBadge({}, { namedLogo: 'npm' }, {}).namedLogo).to.equal(
+        'npm'
+      )
+      expect(coalesceBadge({}, { namedLogo: 'npm' }, {}).logo).to.equal(
+        getShieldsIcon({ name: 'npm' })
+      ).and.not.to.be.empty
+    })
+
+    it('applies the named logo with color', function() {
+      expect(
+        coalesceBadge({}, { namedLogo: 'npm', logoColor: 'blue' }, {}).logo
+      ).to.equal(getShieldsIcon({ name: 'npm', color: 'blue' })).and.not.to.be
+        .empty
+    })
+
+    it('overrides the logo', function() {
+      expect(
+        coalesceBadge({ logo: 'npm' }, { namedLogo: 'appveyor' }, {}).logo
+      ).to.equal(getShieldsIcon({ name: 'npm' })).and.not.be.empty
+    })
+
+    it('overrides the logo with a color', function() {
+      expect(
+        coalesceBadge(
+          { logo: 'npm', logoColor: 'blue' },
+          { namedLogo: 'appveyor' },
+          {}
+        ).logo
+      ).to.equal(getShieldsIcon({ name: 'npm', color: 'blue' })).and.not.be
+        .empty
+    })
+
+    it("when the logo is overridden, it ignores the service's logo color, position, and width", function() {
+      expect(
+        coalesceBadge(
+          { logo: 'npm' },
+          {
+            namedLogo: 'appveyor',
+            logoColor: 'red',
+            logoPosition: -3,
+            logoWidth: 100,
+          },
+          {}
+        ).logo
+      ).to.equal(getShieldsIcon({ name: 'npm' })).and.not.be.empty
+    })
+
+    it("overrides the service logo's color", function() {
+      expect(
+        coalesceBadge(
+          { logoColor: 'blue' },
+          { namedLogo: 'npm', logoColor: 'red' },
+          {}
+        ).logo
+      ).to.equal(getShieldsIcon({ name: 'npm', color: 'blue' })).and.not.be
+        .empty
+    })
+
+    // https://github.com/badges/shields/issues/2998
+    it('overrides logoSvg', function() {
+      const logoSvg = 'data:image/svg+xml;base64,PHN2ZyB4bWxu'
+      expect(coalesceBadge({ logo: 'npm' }, { logoSvg }, {}).logo).to.equal(
+        getShieldsIcon({ name: 'npm' })
+      ).and.not.be.empty
+    })
+  })
+
+  describe('Custom logos', function() {
+    it('overrides the logo with custom svg', function() {
+      const logoSvg = 'data:image/svg+xml;base64,PHN2ZyB4bWxu'
+      expect(
+        coalesceBadge({ logo: logoSvg }, { namedLogo: 'appveyor' }, {}).logo
+      ).to.equal(logoSvg)
+    })
+
+    it('ignores the color when custom svg is provided', function() {
+      const logoSvg = 'data:image/svg+xml;base64,PHN2ZyB4bWxu'
+      expect(
+        coalesceBadge(
+          { logo: logoSvg, logoColor: 'brightgreen' },
+          { namedLogo: 'appveyor' },
+          {}
+        ).logo
+      ).to.equal(logoSvg)
+    })
+  })
+
+  describe('Logo width', function() {
+    it('overrides the logoWidth', function() {
+      expect(coalesceBadge({ logoWidth: 20 }, {}, {}).logoWidth).to.equal(20)
+    })
+
+    it('applies the logo width', function() {
+      expect(
+        coalesceBadge({}, { namedLogo: 'npm', logoWidth: 275 }, {}).logoWidth
+      ).to.equal(275)
+    })
+  })
+
+  describe('Logo position', function() {
+    it('overrides the logoPosition', function() {
+      expect(
+        coalesceBadge({ logoPosition: -10 }, {}, {}).logoPosition
+      ).to.equal(-10)
+    })
+
+    it('applies the logo position', function() {
+      expect(
+        coalesceBadge({}, { namedLogo: 'npm', logoPosition: -10 }, {})
+          .logoPosition
+      ).to.equal(-10)
+    })
+  })
+
+  describe('Links', function() {
+    it('overrides the links', function() {
+      expect(
+        coalesceBadge(
+          { link: 'https://circleci.com/gh/badges/daily-tests' },
+          {
+            link:
+              'https://circleci.com/workflow-run/184ef3de-4836-4805-a2e4-0ceba099f92d',
+          },
+          {}
+        ).links
+      ).to.deep.equal(['https://circleci.com/gh/badges/daily-tests'])
+    })
+  })
+
+  describe('Style', function() {
+    it('overrides the template', function() {
+      expect(coalesceBadge({ style: 'pill' }, {}, {}).template).to.equal('pill')
+    })
+  })
+
+  describe('Cache length', function() {
+    it('overrides the cache length', function() {
+      expect(
+        coalesceBadge({ style: 'pill' }, { cacheSeconds: 123 }, {})
+          .cacheLengthSeconds
+      ).to.equal(123)
+    })
+  })
+})

core/base-service/coalesce.js

@@ -0,0 +1,5 @@
+'use strict'
+
+module.exports = function coalesce(...candidates) {
+  return candidates.find(c => c !== undefined && c !== null)
+}

core/base-service/coalesce.spec.js

@@ -0,0 +1,23 @@
+'use strict'
+
+const { test, given } = require('sazerac')
+const coalesce = require('./coalesce')
+
+// Sticking with our one-line spread implementation, and defaulting to
+// `undefined` instead of `null`, though h/t to
+// https://github.com/royriojas/coalescy for these tests!
+
+describe('coalesce', function() {
+  test(coalesce, function() {
+    given().expect(undefined)
+    given(null, []).expect([])
+    given(null, [], {}).expect([])
+    given(null, undefined, 0, {}).expect(0)
+
+    const a = null,
+      c = 0,
+      d = 1
+    let b
+    given(a, b, c, d).expect(0)
+  })
+})

core/base-service/deprecated-service.js

@@ -0,0 +1,63 @@
+'use strict'
+
+const Joi = require('joi')
+const camelcase = require('camelcase')
+const BaseService = require('./base')
+const { isValidCategory } = require('./categories')
+const { Deprecated } = require('./errors')
+const { isValidRoute } = require('./route')
+
+const attrSchema = Joi.object({
+  route: isValidRoute,
+  name: Joi.string(),
+  label: Joi.string(),
+  category: isValidCategory,
+  // The content of examples is validated later, via `transformExamples()`.
+  examples: Joi.array().default([]),
+  message: Joi.string(),
+  dateAdded: Joi.date().required(),
+}).required()
+
+function deprecatedService(attrs) {
+  const { route, name, label, category, examples, message } = Joi.attempt(
+    attrs,
+    attrSchema,
+    `Deprecated service for ${attrs.route.base}`
+  )
+
+  return class DeprecatedService extends BaseService {
+    static get name() {
+      return name
+        ? `Deprecated${name}`
+        : `Deprecated${camelcase(route.base.replace(/\//g, '_'), {
+            pascalCase: true,
+          })}`
+    }
+
+    static get category() {
+      return category
+    }
+
+    static get isDeprecated() {
+      return true
+    }
+
+    static get route() {
+      return route
+    }
+
+    static get examples() {
+      return examples
+    }
+
+    static get defaultBadgeData() {
+      return { label }
+    }
+
+    async handle() {
+      throw new Deprecated({ prettyMessage: message })
+    }
+  }
+}
+
+module.exports = deprecatedService

core/base-service/deprecated-service.spec.js

@@ -0,0 +1,69 @@
+'use strict'
+
+const { expect } = require('chai')
+const deprecatedService = require('./deprecated-service')
+
+describe('DeprecatedService', function() {
+  const route = {
+    base: 'service/that/no/longer/exists',
+    format: '(?:.+)',
+  }
+  const category = 'analysis'
+  const dateAdded = new Date()
+  const commonAttrs = { route, category, dateAdded }
+
+  it('returns true on isDeprecated', function() {
+    const service = deprecatedService({ ...commonAttrs })
+    expect(service.isDeprecated).to.be.true
+  })
+
+  it('has the expected name', function() {
+    const service = deprecatedService({ ...commonAttrs })
+    expect(service.name).to.equal('DeprecatedServiceThatNoLongerExists')
+  })
+
+  it('sets specified route', function() {
+    const service = deprecatedService({ ...commonAttrs })
+    expect(service.route).to.deep.equal(route)
+  })
+
+  it('sets specified label', function() {
+    const label = 'coverity'
+    const service = deprecatedService({ ...commonAttrs, label })
+    expect(service.defaultBadgeData.label).to.equal(label)
+  })
+
+  it('sets specified category', function() {
+    const service = deprecatedService({ ...commonAttrs })
+    expect(service.category).to.equal(category)
+  })
+
+  it('sets specified examples', function() {
+    const examples = [
+      {
+        title: 'Not sure we would have examples',
+      },
+    ]
+    const service = deprecatedService({ ...commonAttrs, examples })
+    expect(service.examples).to.deep.equal(examples)
+  })
+
+  it('uses default deprecation message when no message specified', async function() {
+    const service = deprecatedService({ ...commonAttrs })
+    expect(await service.invoke()).to.deep.equal({
+      isError: true,
+      color: 'lightgray',
+      message: 'no longer available',
+    })
+  })
+
+  it('uses custom deprecation message when specified', async function() {
+    const message = 'extended outage'
+    const service = deprecatedService({ ...commonAttrs, message })
+    expect(await service.invoke()).to.deep.equal({
+      isError: true,
+      color: 'lightgray',
+      message,
+    })
+  })
+})

core/base-service/errors.js

@@ -34,6 +34,7 @@ class NotFound extends ShieldsRuntimeError {
         ? 'Not Found'
         : `Not Found: ${prettyMessage}`
     super(props, message)
+    this.response = props.response
   }
 }
 
@@ -50,6 +51,7 @@ class InvalidResponse extends ShieldsRuntimeError {
       ? `Invalid Response: ${props.underlyingError.message}`
       : 'Invalid Response'
     super(props, message)
+    this.response = props.response
   }
 }
 
@@ -66,6 +68,7 @@ class Inaccessible extends ShieldsRuntimeError {
       ? `Inaccessible: ${props.underlyingError.message}`
       : 'Inaccessible'
     super(props, message)
+    this.response = props.response
   }
 }
 
@@ -82,6 +85,7 @@ class InvalidParameter extends ShieldsRuntimeError {
       ? `Invalid Parameter: ${props.underlyingError.message}`
       : 'Invalid Parameter'
     super(props, message)
+    this.response = props.response
   }
 }
 
@@ -100,6 +104,7 @@ class Deprecated extends ShieldsRuntimeError {
 }
 
 module.exports = {
+  ShieldsRuntimeError,
   NotFound,
   InvalidResponse,
   Inaccessible,

core/base-service/examples.js

@@ -0,0 +1,169 @@
+'use strict'
+
+const Joi = require('joi')
+const pathToRegexp = require('path-to-regexp')
+const coalesceBadge = require('./coalesce-badge')
+const { makeFullUrl } = require('./route')
+
+const optionalObjectOfKeyValues = Joi.object().pattern(
+  /./,
+  Joi.string().allow(null)
+)
+
+const schema = Joi.object({
+  // This should be:
+  // title: Joi.string().required(),
+  title: Joi.string(),
+  namedParams: optionalObjectOfKeyValues.required(),
+  queryParams: optionalObjectOfKeyValues.default({}),
+  pattern: Joi.string(),
+  staticPreview: Joi.object({
+    label: Joi.string(),
+    message: Joi.alternatives()
+      .try(
+        Joi.string()
+          .allow('')
+          .required(),
+        Joi.number()
+      )
+      .required(),
+    color: Joi.string(),
+    style: Joi.string(),
+  }).required(),
+  keywords: Joi.array()
+    .items(Joi.string())
+    .default([]),
+  documentation: Joi.string(), // Valid HTML.
+}).required()
+
+function validateExample(example, index, ServiceClass) {
+  const result = Joi.attempt(
+    example,
+    schema,
+    `Example for ${ServiceClass.name} at index ${index}`
+  )
+
+  const { pattern, namedParams } = result
+
+  if (!pattern && !ServiceClass.route.pattern) {
+    throw new Error(
+      `Example for ${
+        ServiceClass.name
+      } at index ${index} does not declare a pattern`
+    )
+  }
+  if (pattern === ServiceClass.route.pattern) {
+    throw new Error(
+      `Example for ${
+        ServiceClass.name
+      } at index ${index} declares a redundant pattern which should be removed`
+    )
+  }
+
+  // Make sure we can build the full URL using these patterns.
+  try {
+    pathToRegexp.compile(pattern || ServiceClass.route.pattern)(namedParams)
+  } catch (e) {
+    throw Error(
+      `In example for ${
+        ServiceClass.name
+      } at index ${index}, ${e.message.toLowerCase()}`
+    )
+  }
+  // Make sure there are no extra keys.
+  let keys = []
+  pathToRegexp(pattern || ServiceClass.route.pattern, keys)
+  keys = keys.map(({ name }) => name)
+  const extraKeys = Object.keys(namedParams).filter(k => !keys.includes(k))
+  if (extraKeys.length) {
+    throw Error(
+      `In example for ${
+        ServiceClass.name
+      } at index ${index}, namedParams contains unknown keys: ${extraKeys.join(
+        ', '
+      )}`
+    )
+  }
+
+  if (example.keywords) {
+    // Make sure the keywords are at least two characters long.
+    const tinyKeywords = example.keywords.filter(k => k.length < 2)
+    if (tinyKeywords.length) {
+      throw Error(
+        `In example for ${
+          ServiceClass.name
+        } at index ${index}, keywords contains words that are less than two characters long: ${tinyKeywords.join(
+          ', '
+        )}`
+      )
+    }
+    // Make sure none of the keywords are already included in the title.
+    const title = (example.title || ServiceClass.name).toLowerCase()
+    const redundantKeywords = example.keywords.filter(k =>
+      title.includes(k.toLowerCase())
+    )
+    if (redundantKeywords.length) {
+      throw Error(
+        `In example for ${
+          ServiceClass.name
+        } at index ${index}, keywords contains words that are already in the title: ${redundantKeywords.join(
+          ', '
+        )}`
+      )
+    }
+  }
+
+  return result
+}
+
+function transformExample(inExample, index, ServiceClass) {
+  const {
+    // We should get rid of this transform, since the class name is never what
+    // we want to see.
+    title = ServiceClass.name,
+    namedParams,
+    queryParams,
+    pattern,
+    staticPreview,
+    keywords,
+    documentation,
+  } = validateExample(inExample, index, ServiceClass)
+
+  const {
+    text: [label, message],
+    color,
+    template: style,
+    namedLogo,
+  } = coalesceBadge(
+    {},
+    staticPreview,
+    ServiceClass.defaultBadgeData,
+    ServiceClass
+  )
+
+  return {
+    title,
+    example: {
+      pattern: makeFullUrl(
+        ServiceClass.route.base,
+        pattern || ServiceClass.route.pattern
+      ),
+      namedParams,
+      queryParams,
+    },
+    preview: {
+      label,
+      message: `${message}`,
+      color,
+      style: style === 'flat' ? undefined : style,
+      namedLogo,
+    },
+    keywords,
+    documentation: documentation ? { __html: documentation } : undefined,
+  }
+}
+
+module.exports = {
+  validateExample,
+  transformExample,
+}

core/base-service/examples.spec.js

@@ -0,0 +1,168 @@
+'use strict'
+
+const { expect } = require('chai')
+const { test, given } = require('sazerac')
+const { validateExample, transformExample } = require('./examples')
+
+describe('validateExample function', function() {
+  it('passes valid examples', function() {
+    const validExamples = [
+      {
+        title: 'Package manager versioning badge',
+        staticPreview: { message: '123' },
+        pattern: 'dt/:package',
+        namedParams: { package: 'mypackage' },
+        keywords: ['semver', 'management'],
+      },
+    ]
+
+    validExamples.forEach(example => {
+      expect(() =>
+        validateExample(example, 0, { route: {}, name: 'mockService' })
+      ).not.to.throw(Error)
+    })
+  })
+
+  it('rejects invalid examples', function() {
+    const invalidExamples = [
+      {},
+      { staticPreview: { message: '123' } },
+      {
+        staticPreview: { message: '123' },
+        pattern: 'dt/:package',
+        namedParams: { package: 'mypackage' },
+        exampleUrl: 'dt/mypackage',
+      },
+      { staticPreview: { message: '123' }, pattern: 'dt/:package' },
+      {
+        staticPreview: { message: '123' },
+        pattern: 'dt/:package',
+        previewUrl: 'dt/mypackage',
+      },
+      {
+        staticPreview: { message: '123' },
+        pattern: 'dt/:package',
+        exampleUrl: 'dt/mypackage',
+      },
+      { previewUrl: 'dt/mypackage' },
+      {
+        staticPreview: { message: '123' },
+        pattern: 'dt/:package',
+        namedParams: { package: 'mypackage' },
+        keywords: ['a'], // Keyword too short.
+      },
+      {
+        staticPreview: { message: '123' },
+        pattern: 'dt/:package',
+        namedParams: { package: 'mypackage' },
+        keywords: ['mockService'], // No title and keyword matching the class name.
+      },
+      {
+        title: 'Package manager versioning badge',
+        staticPreview: { message: '123' },
+        pattern: 'dt/:package',
+        namedParams: { package: 'mypackage' },
+        keywords: ['version'], // Keyword included in title.
+      },
+    ]
+
+    invalidExamples.forEach(example => {
+      expect(() =>
+        validateExample(example, 0, { route: {}, name: 'mockService' })
+      ).to.throw(Error)
+    })
+  })
+})
+
+test(transformExample, function() {
+  const ExampleService = {
+    name: 'ExampleService',
+    route: {
+      base: 'some-service',
+      pattern: ':interval/:packageName',
+    },
+    defaultBadgeData: {
+      label: 'downloads',
+    },
+  }
+
+  given(
+    {
+      pattern: 'dt/:packageName',
+      namedParams: { packageName: 'express' },
+      staticPreview: { message: '50k' },
+      keywords: ['hello'],
+    },
+    0,
+    ExampleService
+  ).expect({
+    title: 'ExampleService',
+    example: {
+      pattern: '/some-service/dt/:packageName',
+      namedParams: { packageName: 'express' },
+      queryParams: {},
+    },
+    preview: {
+      label: 'downloads',
+      message: '50k',
+      color: 'lightgrey',
+      namedLogo: undefined,
+      style: undefined,
+    },
+    keywords: ['hello'],
+    documentation: undefined,
+  })
+
+  given(
+    {
+      namedParams: { interval: 'dt', packageName: 'express' },
+      staticPreview: { message: '50k' },
+      keywords: ['hello'],
+    },
+    0,
+    ExampleService
+  ).expect({
+    title: 'ExampleService',
+    example: {
+      pattern: '/some-service/:interval/:packageName',
+      namedParams: { interval: 'dt', packageName: 'express' },
+      queryParams: {},
+    },
+    preview: {
+      label: 'downloads',
+      message: '50k',
+      color: 'lightgrey',
+      namedLogo: undefined,
+      style: undefined,
+    },
+    keywords: ['hello'],
+    documentation: undefined,
+  })
+
+  given(
+    {
+      namedParams: { interval: 'dt', packageName: 'express' },
+      queryParams: { registry_url: 'http://example.com/' },
+      staticPreview: { message: '50k' },
+      keywords: ['hello'],
+    },
+    0,
+    ExampleService
+  ).expect({
+    title: 'ExampleService',
+    example: {
+      pattern: '/some-service/:interval/:packageName',
+      namedParams: { interval: 'dt', packageName: 'express' },
+      queryParams: { registry_url: 'http://example.com/' },
+    },
+    preview: {
+      label: 'downloads',
+      message: '50k',
+      color: 'lightgrey',
+      namedLogo: undefined,
+      style: undefined,
+    },
+    keywords: ['hello'],
+    documentation: undefined,
+  })
+})

core/base-service/index.js

@@ -0,0 +1,35 @@
+'use strict'
+
+const BaseService = require('./base')
+const BaseJsonService = require('./base-json')
+const NonMemoryCachingBaseService = require('./base-non-memory-caching')
+const BaseStaticService = require('./base-static')
+const BaseSvgScrapingService = require('./base-svg-scraping')
+const BaseXmlService = require('./base-xml')
+const BaseYamlService = require('./base-yaml')
+const deprecatedService = require('./deprecated-service')
+const redirector = require('./redirector')
+const {
+  NotFound,
+  InvalidResponse,
+  Inaccessible,
+  InvalidParameter,
+  Deprecated,
+} = require('./errors')
+
+module.exports = {
+  BaseService,
+  BaseJsonService,
+  NonMemoryCachingBaseService,
+  BaseStaticService,
+  BaseSvgScrapingService,
+  BaseXmlService,
+  BaseYamlService,
+  deprecatedService,
+  redirector,
+  NotFound,
+  InvalidResponse,
+  Inaccessible,
+  InvalidParameter,
+  Deprecated,
+}

core/base-service/legacy-request-handler.js

@@ -3,14 +3,18 @@
 // eslint-disable-next-line node/no-deprecated-api
 const domain = require('domain')
 const request = require('request')
-const { makeBadgeData: getBadgeData } = require('./badge-data')
-const log = require('./log')
-const LruCache = require('../gh-badges/lib/lru-cache')
-const makeBadge = require('../gh-badges/lib/make-badge')
-const analytics = require('./analytics')
-const { makeSend } = require('./result-sender')
 const queryString = require('query-string')
-const { Inaccessible } = require('../services/errors')
+const LruCache = require('../../gh-badges/lib/lru-cache')
+const makeBadge = require('../../gh-badges/lib/make-badge')
+const log = require('../server/log')
+const { setCacheHeaders } = require('./cache-headers')
+const {
+  Inaccessible,
+  InvalidResponse,
+  ShieldsRuntimeError,
+} = require('./errors')
+const { makeSend } = require('./legacy-result-sender')
+const coalesceBadge = require('./coalesce-badge')
 
 // We avoid calling the vendor's server for computation of the information in a
 // number of badges.
@@ -34,8 +38,8 @@ vendorDomain.on('error', err => {
   log.error('Vendor hook error:', err.stack)
 })
 
-// These query parameters are available to any badge. For the most part they
-// are used by makeBadgeData (see `lib/badge-data.js`) and related functions.
+// These query parameters are available to any badge. They are handled by
+// `coalesceBadge`.
 const globalQueryParams = new Set([
   'label',
   'style',
@@ -47,6 +51,8 @@ const globalQueryParams = new Set([
   'link',
   'colorA',
   'colorB',
+  'color',
+  'labelColor',
 ])
 
 function flattenQueryParams(queryParams) {
@@ -57,29 +63,13 @@ function flattenQueryParams(queryParams) {
   return Array.from(union).sort()
 }
 
-function getBadgeMaxAge(handlerOptions, queryParams) {
-  let maxAge = isInt(process.env.BADGE_MAX_AGE_SECONDS)
-    ? parseInt(process.env.BADGE_MAX_AGE_SECONDS)
-    : 120
-  if (handlerOptions.cacheLength) {
-    // If we've set a more specific cache length for this badge (or category),
-    // use that instead of env.BADGE_MAX_AGE_SECONDS.
-    maxAge = handlerOptions.cacheLength
-  }
-  if (isInt(queryParams.maxAge) && parseInt(queryParams.maxAge) > maxAge) {
-    // Only allow queryParams.maxAge to override the default if it is greater
-    // than the default.
-    maxAge = parseInt(queryParams.maxAge)
-  }
-  return maxAge
-}
-
 // handlerOptions can contain:
 // - handler: The service's request handler function
 // - queryParams: An array of the field names of any custom query parameters
 //   the service uses
 // - cacheLength: An optional badge or category-specific cache length
 //   (in number of seconds) to be used in preference to the default
+// - fetchLimitBytes: A limit on the response size we're willing to parse
 //
 // For safety, the service must declare the query parameters it wants to use.
 // Only the declared parameters (and the global parameters) are provided to
@@ -89,34 +79,47 @@ function getBadgeMaxAge(handlerOptions, queryParams) {
 // (undesirable and hard to debug).
 //
 // Pass just the handler function as shorthand.
-function handleRequest(handlerOptions) {
+function handleRequest(cacheHeaderConfig, handlerOptions) {
+  if (!cacheHeaderConfig) {
+    throw Error('cacheHeaderConfig is required')
+  }
+
   if (typeof handlerOptions === 'function') {
     handlerOptions = { handler: handlerOptions }
   }
 
   const allowedKeys = flattenQueryParams(handlerOptions.queryParams)
+  const {
+    cacheLength: serviceDefaultCacheLengthSeconds,
+    fetchLimitBytes,
+  } = handlerOptions
 
   return (queryParams, match, end, ask) => {
     const reqTime = new Date()
 
-    const maxAge = getBadgeMaxAge(handlerOptions, queryParams)
-    // send both Cache-Control max-age and Expires
-    // in case the client implements HTTP/1.0 but not HTTP/1.1
-    if (maxAge === 0) {
-      ask.res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate')
-      ask.res.setHeader('Expires', reqTime.toGMTString())
-    } else {
-      ask.res.setHeader('Cache-Control', `max-age=${maxAge}`)
-      ask.res.setHeader(
-        'Expires',
-        new Date(+reqTime + maxAge * 1000).toGMTString()
-      )
+    // `defaultCacheLengthSeconds` can be overridden by
+    // `serviceDefaultCacheLengthSeconds` (either by category or on a badge-
+    // by-badge basis). Then in turn that can be overridden by
+    // `serviceOverrideCacheLengthSeconds` (which we expect to be used only in
+    // the dynamic badge) but only if `serviceOverrideCacheLengthSeconds` is
+    // longer than `serviceDefaultCacheLengthSeconds` and then the `cacheSeconds`
+    // query param can also override both of those but again only if `cacheSeconds`
+    // is longer.
+    //
+    // When the legacy services have been rewritten, all the code in here
+    // will go away, which should achieve this goal in a simpler way.
+    //
+    // Ref: https://github.com/badges/shields/pull/2755
+    function setCacheHeadersOnResponse(res, serviceOverrideCacheLengthSeconds) {
+      setCacheHeaders({
+        cacheHeaderConfig,
+        serviceDefaultCacheLengthSeconds,
+        serviceOverrideCacheLengthSeconds,
+        queryParams,
+        res,
+      })
     }
 
-    ask.res.setHeader('Date', reqTime.toGMTString())
-
-    analytics.noteRequest(queryParams, match)
-
     const filteredQueryParams = {}
     allowedKeys.forEach(key => {
       filteredQueryParams[key] = queryParams[key]
@@ -135,6 +138,10 @@ function handleRequest(handlerOptions) {
       const tooSoon = +reqTime - cached.time < cached.interval
       if (tooSoon || cached.dataChange / cached.reqs <= freqRatioMax) {
         const svg = makeBadge(cached.data.badgeData)
+        setCacheHeadersOnResponse(
+          ask.res,
+          cached.data.badgeData.cacheLengthSeconds
+        )
         makeSend(cached.data.format, ask.res, end)(svg)
         cachedVersionSent = true
         // We do not wish to call the vendor servers.
@@ -152,21 +159,29 @@ function handleRequest(handlerOptions) {
         return
       }
       if (requestCache.has(cacheIndex)) {
-        const cached = requestCache.get(cacheIndex).data
-        const svg = makeBadge(cached.badgeData)
-        makeSend(cached.format, ask.res, end)(svg)
+        const cached = requestCache.get(cacheIndex)
+        const svg = makeBadge(cached.data.badgeData)
+        setCacheHeadersOnResponse(
+          ask.res,
+          cached.data.badgeData.cacheLengthSeconds
+        )
+        makeSend(cached.data.format, ask.res, end)(svg)
         return
       }
       ask.res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate')
-      const badgeData = getBadgeData('vendor', filteredQueryParams)
-      badgeData.text[1] = 'unresponsive'
+      const badgeData = coalesceBadge(
+        filteredQueryParams,
+        { label: 'vendor', message: 'unresponsive' },
+        {}
+      )
+      const svg = makeBadge(badgeData)
       let extension
       try {
         extension = match[0].split('.').pop()
       } catch (e) {
         extension = 'svg'
       }
-      const svg = makeBadge(badgeData)
+      setCacheHeadersOnResponse(ask.res)
       makeSend(extension, ask.res, end)(svg)
     }, 25000)
 
@@ -187,7 +202,8 @@ function handleRequest(handlerOptions) {
       options.headers['User-Agent'] =
         options.headers['User-Agent'] || 'Shields.io'
 
-      request(options, (err, res, body) => {
+      let bufferLength = 0
+      const r = request(options, (err, res, body) => {
         if (res != null && res.headers != null) {
           const cacheControl = res.headers['cache-control']
           if (cacheControl != null) {
@@ -201,6 +217,18 @@ function handleRequest(handlerOptions) {
         }
         callback(err, res, body)
       })
+      r.on('data', chunk => {
+        bufferLength += chunk.length
+        if (bufferLength > fetchLimitBytes) {
+          r.abort()
+          r.emit(
+            'error',
+            new InvalidResponse({
+              prettyMessage: 'Maximum response size exceeded',
+            })
+          )
+        }
+      })
     }
 
     // Wrapper around `cachingRequest` that returns a promise rather than
@@ -209,9 +237,13 @@ function handleRequest(handlerOptions) {
       new Promise((resolve, reject) => {
         cachingRequest(uri, options, (err, res, buffer) => {
           if (err) {
-            // Wrap the error in an Inaccessible so it can be identified
-            // by the BaseService handler.
-            reject(new Inaccessible({ underlyingError: err }))
+            if (err instanceof ShieldsRuntimeError) {
+              reject(err)
+            } else {
+              // Wrap the error in an Inaccessible so it can be identified
+              // by the BaseService handler.
+              reject(new Inaccessible({ underlyingError: err }))
+            }
           } else {
             resolve({ res, buffer })
           }
@@ -251,6 +283,7 @@ function handleRequest(handlerOptions) {
           requestCache.set(cacheIndex, updatedCache)
           if (!cachedVersionSent) {
             const svg = makeBadge(badgeData)
+            setCacheHeadersOnResponse(ask.res, badgeData.cacheLengthSeconds)
             makeSend(format, ask.res, end)(svg)
           }
         },
@@ -269,14 +302,9 @@ function clearRequestCache() {
   requestCache.clear()
 }
 
-function isInt(number) {
-  return number !== undefined && /^[0-9]+$/.test(number)
-}
-
 module.exports = {
   handleRequest,
   clearRequestCache,
   // Expose for testing.
   _requestCache: requestCache,
-  getBadgeMaxAge,
 }

core/base-service/legacy-request-handler.spec.js

@@ -0,0 +1,392 @@
+'use strict'
+
+const { expect } = require('chai')
+// https://github.com/nock/nock/issues/1523
+const got = require('got').extend({ retry: 0 })
+const nock = require('nock')
+const portfinder = require('portfinder')
+const Camp = require('camp')
+const coalesceBadge = require('./coalesce-badge')
+const {
+  handleRequest,
+  clearRequestCache,
+  _requestCache,
+} = require('./legacy-request-handler')
+
+async function performTwoRequests(baseUrl, first, second) {
+  expect((await got(`${baseUrl}${first}`)).statusCode).to.equal(200)
+  expect((await got(`${baseUrl}${second}`)).statusCode).to.equal(200)
+}
+
+function fakeHandler(queryParams, match, sendBadge, request) {
+  const [, someValue, format] = match
+  const badgeData = coalesceBadge(
+    queryParams,
+    {
+      label: 'testing',
+      message: someValue,
+    },
+    {}
+  )
+  sendBadge(format, badgeData)
+}
+
+function createFakeHandlerWithCacheLength(cacheLengthSeconds) {
+  return function fakeHandler(queryParams, match, sendBadge, request) {
+    const [, someValue, format] = match
+    const badgeData = coalesceBadge(
+      queryParams,
+      {
+        label: 'testing',
+        message: someValue,
+      },
+      {},
+      {
+        _cacheLength: cacheLengthSeconds,
+      }
+    )
+    sendBadge(format, badgeData)
+  }
+}
+
+function fakeHandlerWithNetworkIo(queryParams, match, sendBadge, request) {
+  const [, someValue, format] = match
+  request('https://www.google.com/foo/bar', (err, res, buffer) => {
+    let message
+    if (err) {
+      message = err.prettyMessage
+    } else {
+      message = someValue
+    }
+    const badgeData = coalesceBadge(
+      queryParams,
+      {
+        label: 'testing',
+        message,
+        format,
+      },
+      {}
+    )
+    sendBadge(format, badgeData)
+  })
+}
+
+describe('The request handler', function() {
+  let port, baseUrl
+  beforeEach(async function() {
+    port = await portfinder.getPortPromise()
+    baseUrl = `http://127.0.0.1:${port}`
+  })
+
+  let camp
+  beforeEach(function(done) {
+    camp = Camp.start({ port, hostname: '::' })
+    camp.on('listening', () => done())
+  })
+  afterEach(function(done) {
+    clearRequestCache()
+    if (camp) {
+      camp.close(() => done())
+      camp = null
+    }
+  })
+
+  const standardCacheHeaders = { defaultCacheLengthSeconds: 120 }
+
+  describe('the options object calling style', function() {
+    beforeEach(function() {
+      camp.route(
+        /^\/testing\/([^/]+)\.(svg|png|gif|jpg|json)$/,
+        handleRequest(standardCacheHeaders, { handler: fakeHandler })
+      )
+    })
+
+    it('should return the expected response', async function() {
+      const { statusCode, body } = await got(`${baseUrl}/testing/123.json`, {
+        json: true,
+      })
+      expect(statusCode).to.equal(200)
+      expect(body).to.deep.equal({
+        name: 'testing',
+        value: '123',
+        label: 'testing',
+        message: '123',
+        color: 'lightgrey',
+        link: [],
+      })
+    })
+  })
+
+  describe('the function shorthand calling style', function() {
+    beforeEach(function() {
+      camp.route(
+        /^\/testing\/([^/]+)\.(svg|png|gif|jpg|json)$/,
+        handleRequest(standardCacheHeaders, fakeHandler)
+      )
+    })
+
+    it('should return the expected response', async function() {
+      const { statusCode, body } = await got(`${baseUrl}/testing/123.json`, {
+        json: true,
+      })
+      expect(statusCode).to.equal(200)
+      expect(body).to.deep.equal({
+        name: 'testing',
+        value: '123',
+        label: 'testing',
+        message: '123',
+        color: 'lightgrey',
+        link: [],
+      })
+    })
+  })
+
+  describe('the response size limit', function() {
+    beforeEach(function() {
+      camp.route(
+        /^\/testing\/([^/]+)\.(svg|png|gif|jpg|json)$/,
+        handleRequest(standardCacheHeaders, {
+          handler: fakeHandlerWithNetworkIo,
+          fetchLimitBytes: 100,
+        })
+      )
+    })
+
+    it('should not throw an error if the response <= fetchLimitBytes', async function() {
+      nock('https://www.google.com')
+        .get('/foo/bar')
+        .once()
+        .reply(200, 'x'.repeat(100))
+      const { statusCode, body } = await got(`${baseUrl}/testing/123.json`, {
+        json: true,
+      })
+      expect(statusCode).to.equal(200)
+      expect(body).to.deep.equal({
+        name: 'testing',
+        value: '123',
+        label: 'testing',
+        message: '123',
+        color: 'lightgrey',
+        link: [],
+      })
+    })
+
+    it('should throw an error if the response is > fetchLimitBytes', async function() {
+      nock('https://www.google.com')
+        .get('/foo/bar')
+        .once()
+        .reply(200, 'x'.repeat(101))
+      const { statusCode, body } = await got(`${baseUrl}/testing/123.json`, {
+        json: true,
+      })
+      expect(statusCode).to.equal(200)
+      expect(body).to.deep.equal({
+        name: 'testing',
+        value: 'Maximum response size exceeded',
+        label: 'testing',
+        message: 'Maximum response size exceeded',
+        color: 'lightgrey',
+        link: [],
+      })
+    })
+
+    afterEach(function() {
+      nock.cleanAll()
+    })
+  })
+
+  describe('caching', function() {
+    describe('standard query parameters', function() {
+      let handlerCallCount
+      beforeEach(function() {
+        handlerCallCount = 0
+      })
+
+      function register({ cacheHeaderConfig }) {
+        camp.route(
+          /^\/testing\/([^/]+)\.(svg|png|gif|jpg|json)$/,
+          handleRequest(
+            cacheHeaderConfig,
+            (queryParams, match, sendBadge, request) => {
+              ++handlerCallCount
+              fakeHandler(queryParams, match, sendBadge, request)
+            }
+          )
+        )
+      }
+
+      context('With standard cache settings', function() {
+        beforeEach(function() {
+          register({ cacheHeaderConfig: standardCacheHeaders })
+        })
+
+        it('should cache identical requests', async function() {
+          await performTwoRequests(
+            baseUrl,
+            '/testing/123.svg',
+            '/testing/123.svg'
+          )
+          expect(handlerCallCount).to.equal(1)
+        })
+
+        it('should differentiate known query parameters', async function() {
+          await performTwoRequests(
+            baseUrl,
+            '/testing/123.svg?label=foo',
+            '/testing/123.svg?label=bar'
+          )
+          expect(handlerCallCount).to.equal(2)
+        })
+
+        it('should ignore unknown query parameters', async function() {
+          await performTwoRequests(
+            baseUrl,
+            '/testing/123.svg?foo=1',
+            '/testing/123.svg?foo=2'
+          )
+          expect(handlerCallCount).to.equal(1)
+        })
+      })
+
+      it('should set the expires header to current time + defaultCacheLengthSeconds', async function() {
+        register({ cacheHeaderConfig: { defaultCacheLengthSeconds: 900 } })
+        const { headers } = await got(`${baseUrl}/testing/123.json`)
+        const expectedExpiry = new Date(
+          +new Date(headers.date) + 900000
+        ).toGMTString()
+        expect(headers.expires).to.equal(expectedExpiry)
+        expect(headers['cache-control']).to.equal('max-age=900')
+      })
+
+      it('should set the expected cache headers on cached responses', async function() {
+        register({ cacheHeaderConfig: { defaultCacheLengthSeconds: 900 } })
+
+        // Make first request.
+        await got(`${baseUrl}/testing/123.json`)
+
+        const { headers } = await got(`${baseUrl}/testing/123.json`)
+        const expectedExpiry = new Date(
+          +new Date(headers.date) + 900000
+        ).toGMTString()
+        expect(headers.expires).to.equal(expectedExpiry)
+        expect(headers['cache-control']).to.equal('max-age=900')
+      })
+
+      it('should let live service data override the default cache headers with longer value', async function() {
+        camp.route(
+          /^\/testing\/([^/]+)\.(svg|png|gif|jpg|json)$/,
+          handleRequest(
+            { defaultCacheLengthSeconds: 300 },
+            (queryParams, match, sendBadge, request) => {
+              ++handlerCallCount
+              createFakeHandlerWithCacheLength(400)(
+                queryParams,
+                match,
+                sendBadge,
+                request
+              )
+            }
+          )
+        )
+
+        const { headers } = await got(`${baseUrl}/testing/123.json`)
+        expect(headers['cache-control']).to.equal('max-age=400')
+      })
+
+      it('should not let live service data override the default cache headers with shorter value', async function() {
+        camp.route(
+          /^\/testing\/([^/]+)\.(svg|png|gif|jpg|json)$/,
+          handleRequest(
+            { defaultCacheLengthSeconds: 300 },
+            (queryParams, match, sendBadge, request) => {
+              ++handlerCallCount
+              createFakeHandlerWithCacheLength(200)(
+                queryParams,
+                match,
+                sendBadge,
+                request
+              )
+            }
+          )
+        )
+
+        const { headers } = await got(`${baseUrl}/testing/123.json`)
+        expect(headers['cache-control']).to.equal('max-age=300')
+      })
+
+      it('should set the expires header to current time + cacheSeconds', async function() {
+        register({ cacheHeaderConfig: { defaultCacheLengthSeconds: 0 } })
+        const { headers } = await got(
+          `${baseUrl}/testing/123.json?cacheSeconds=3600`
+        )
+        const expectedExpiry = new Date(
+          +new Date(headers.date) + 3600000
+        ).toGMTString()
+        expect(headers.expires).to.equal(expectedExpiry)
+        expect(headers['cache-control']).to.equal('max-age=3600')
+      })
+
+      it('should ignore cacheSeconds when shorter than defaultCacheLengthSeconds', async function() {
+        register({ cacheHeaderConfig: { defaultCacheLengthSeconds: 600 } })
+        const { headers } = await got(
+          `${baseUrl}/testing/123.json?cacheSeconds=300`
+        )
+        const expectedExpiry = new Date(
+          +new Date(headers.date) + 600000
+        ).toGMTString()
+        expect(headers.expires).to.equal(expectedExpiry)
+        expect(headers['cache-control']).to.equal('max-age=600')
+      })
+
+      it('should set Cache-Control: no-cache, no-store, must-revalidate if cache seconds is 0', async function() {
+        register({ cacheHeaderConfig: { defaultCacheLengthSeconds: 0 } })
+        const { headers } = await got(`${baseUrl}/testing/123.json`)
+        expect(headers.expires).to.equal(headers.date)
+        expect(headers['cache-control']).to.equal(
+          'no-cache, no-store, must-revalidate'
+        )
+      })
+
+      describe('the cache key', function() {
+        beforeEach(function() {
+          register({ cacheHeaderConfig: standardCacheHeaders })
+        })
+        const expectedCacheKey = '/testing/123.json?color=123&label=foo'
+        it('should match expected and use canonical order - 1', async function() {
+          await got(`${baseUrl}/testing/123.json?color=123&label=foo`)
+          expect(_requestCache.cache).to.have.keys(expectedCacheKey)
+        })
+        it('should match expected and use canonical order - 2', async function() {
+          await got(`${baseUrl}/testing/123.json?label=foo&color=123`)
+          expect(_requestCache.cache).to.have.keys(expectedCacheKey)
+        })
+      })
+    })
+
+    describe('custom query parameters', function() {
+      let handlerCallCount
+      beforeEach(function() {
+        handlerCallCount = 0
+        camp.route(
+          /^\/testing\/([^/]+)\.(svg|png|gif|jpg|json)$/,
+          handleRequest(standardCacheHeaders, {
+            queryParams: ['foo'],
+            handler: (queryParams, match, sendBadge, request) => {
+              ++handlerCallCount
+              fakeHandler(queryParams, match, sendBadge, request)
+            },
+          })
+        )
+      })
+
+      it('should differentiate them', async function() {
+        await performTwoRequests(
+          baseUrl,
+          '/testing/123.svg?foo=1',
+          '/testing/123.svg?foo=2'
+        )
+        expect(handlerCallCount).to.equal(2)
+      })
+    })
+  })
+})

core/base-service/legacy-result-sender.js

@@ -1,8 +1,15 @@
 'use strict'
 
+const fs = require('fs')
+const path = require('path')
 const stream = require('stream')
-const log = require('./log')
-const svg2img = require('../gh-badges/lib/svg-to-img')
+const svg2img = require('../../gh-badges/lib/svg-to-img')
+const log = require('../server/log')
+
+const internalError = fs.readFileSync(
+  path.resolve(__dirname, '..', 'server', 'error-pages', '500.html'),
+  'utf-8'
+)
 
 function streamFromString(str) {
   const newStream = new stream.Readable()
@@ -13,16 +20,6 @@ function streamFromString(str) {
   return newStream
 }
 
-function makeSend(format, askres, end) {
-  if (format === 'svg') {
-    return res => sendSVG(res, askres, end)
-  } else if (format === 'json') {
-    return res => sendJSON(res, askres, end)
-  } else {
-    return res => sendOther(format, res, askres, end)
-  }
-}
-
 function sendSVG(res, askres, end) {
   askres.setHeader('Content-Type', 'image/svg+xml;charset=utf-8')
   end(null, { template: streamFromString(res) })
@@ -39,7 +36,7 @@ function sendOther(format, res, askres, end) {
     .catch(err => {
       // This emits status code 200, though 500 would be preferable.
       log.error('svg2img error', err)
-      end(null, { template: '500.html' })
+      end(internalError)
     })
 }
 
@@ -49,6 +46,16 @@ function sendJSON(res, askres, end) {
   end(null, { template: streamFromString(res) })
 }
 
+function makeSend(format, askres, end) {
+  if (format === 'svg') {
+    return res => sendSVG(res, askres, end)
+  } else if (format === 'json') {
+    return res => sendJSON(res, askres, end)
+  } else {
+    return res => sendOther(format, res, askres, end)
+  }
+}
+
 module.exports = {
   makeSend,
 }

core/base-service/loader-test-fixtures/invalid-mixed.fixture.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const BaseJsonService = require('../services/base-json')
+const BaseJsonService = require('../base-json')
 
 class BadBaseService {}
 class GoodService extends BaseJsonService {}

core/base-service/loader-test-fixtures/valid-array.fixture.js

@@ -0,0 +1,30 @@
+'use strict'
+
+const BaseJsonService = require('../base-json')
+
+class GoodServiceOne extends BaseJsonService {
+  static get category() {
+    return 'build'
+  }
+
+  static get route() {
+    return {
+      base: 'good',
+      pattern: 'one',
+    }
+  }
+}
+class GoodServiceTwo extends BaseJsonService {
+  static get category() {
+    return 'build'
+  }
+
+  static get route() {
+    return {
+      base: 'good',
+      pattern: 'two',
+    }
+  }
+}
+
+module.exports = [GoodServiceOne, GoodServiceTwo]

core/base-service/loader-test-fixtures/valid-class.fixture.js

@@ -0,0 +1,18 @@
+'use strict'
+
+const BaseJsonService = require('../base-json')
+
+class GoodService extends BaseJsonService {
+  static get category() {
+    return 'build'
+  }
+
+  static get route() {
+    return {
+      base: 'it/is',
+      pattern: 'good',
+    }
+  }
+}
+
+module.exports = GoodService

core/base-service/loader-test-fixtures/valid-object.fixture.js

@@ -0,0 +1,30 @@
+'use strict'
+
+const BaseJsonService = require('../base-json')
+
+class GoodServiceOne extends BaseJsonService {
+  static get category() {
+    return 'build'
+  }
+
+  static get route() {
+    return {
+      base: 'good',
+      pattern: 'one',
+    }
+  }
+}
+class GoodServiceTwo extends BaseJsonService {
+  static get category() {
+    return 'build'
+  }
+
+  static get route() {
+    return {
+      base: 'good',
+      pattern: 'two',
+    }
+  }
+}
+
+module.exports = { GoodServiceOne, GoodServiceTwo }

core/base-service/loader.js

@@ -0,0 +1,115 @@
+'use strict'
+
+const path = require('path')
+const glob = require('glob')
+const countBy = require('lodash.countby')
+const categories = require('../../services/categories')
+const BaseService = require('./base')
+const { assertValidServiceDefinitionExport } = require('./service-definitions')
+
+const serviceDir = path.join(__dirname, '..', '..', 'services')
+
+class InvalidService extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'InvalidService'
+  }
+}
+
+function loadServiceClasses(servicePaths) {
+  if (!servicePaths) {
+    servicePaths = glob.sync(path.join(serviceDir, '**', '*.service.js'))
+  }
+
+  let serviceClasses = []
+  servicePaths.forEach(servicePath => {
+    const module = require(servicePath)
+
+    const theseServiceClasses = []
+    if (
+      !module ||
+      (module.constructor === Array && module.length === 0) ||
+      (module.constructor === Object && Object.keys(module).length === 0)
+    ) {
+      throw new InvalidService(
+        `Expected ${servicePath} to export a service or a collection of services`
+      )
+    } else if (module.prototype instanceof BaseService) {
+      theseServiceClasses.push(module)
+    } else if (module.constructor === Array || module.constructor === Object) {
+      for (const key in module) {
+        const serviceClass = module[key]
+        if (serviceClass.prototype instanceof BaseService) {
+          theseServiceClasses.push(serviceClass)
+        } else {
+          throw new InvalidService(
+            `Expected ${servicePath} to export a service or a collection of services; one of them was ${serviceClass}`
+          )
+        }
+      }
+    } else {
+      throw new InvalidService(
+        `Expected ${servicePath} to export a service or a collection of services; got ${module}`
+      )
+    }
+
+    // Decorate each service class with the directory that contains it.
+    theseServiceClasses.forEach(serviceClass => {
+      serviceClass.serviceFamily = servicePath
+        .replace(serviceDir, '')
+        .split(path.sep)[1]
+    })
+
+    serviceClasses = serviceClasses.concat(theseServiceClasses)
+  })
+
+  serviceClasses.forEach(ServiceClass => ServiceClass.validateDefinition())
+
+  return serviceClasses
+}
+
+function assertNamesUnique(names, { message }) {
+  const duplicates = {}
+  Object.entries(countBy(names))
+    .filter(([name, count]) => count > 1)
+    .forEach(([name, count]) => {
+      duplicates[name] = count
+    })
+  if (Object.keys(duplicates).length) {
+    throw new Error(`${message}: ${JSON.stringify(duplicates, undefined, 2)}`)
+  }
+}
+
+function checkNames() {
+  const services = loadServiceClasses()
+  assertNamesUnique(services.map(({ name }) => name), {
+    message: 'Duplicate service names found',
+  })
+}
+
+function collectDefinitions() {
+  const services = loadServiceClasses()
+    // flatMap.
+    .map(ServiceClass => ServiceClass.getDefinition())
+    .reduce((accum, these) => accum.concat(these), [])
+
+  const result = { schemaVersion: '0', categories, services }
+
+  assertValidServiceDefinitionExport(result)
+
+  return result
+}
+
+function loadTesters() {
+  return glob
+    .sync(path.join(serviceDir, '**', '*.tester.js'))
+    .map(path => require(path))
+}
+
+module.exports = {
+  InvalidService,
+  loadServiceClasses,
+  checkNames,
+  collectDefinitions,
+  loadTesters,
+}

core/base-service/loader.spec.js

@@ -0,0 +1,59 @@
+'use strict'
+
+const { expect } = require('chai')
+const { loadServiceClasses, InvalidService } = require('./loader')
+
+describe('loadServiceClasses function', function() {
+  it('throws if module exports empty', function() {
+    expect(() =>
+      loadServiceClasses(['./loader-test-fixtures/empty-undefined.fixture.js'])
+    ).to.throw(InvalidService)
+    expect(() =>
+      loadServiceClasses(['./loader-test-fixtures/empty-array.fixture.js'])
+    ).to.throw()
+    expect(() =>
+      loadServiceClasses(['./loader-test-fixtures/empty-object.fixture.js'])
+    ).to.throw(InvalidService)
+    expect(() =>
+      loadServiceClasses(['./loader-test-fixtures/empty-no-export.fixture.js'])
+    ).to.throw(InvalidService)
+    expect(() =>
+      loadServiceClasses([
+        './loader-test-fixtures/valid-array.fixture.js',
+        './loader-test-fixtures/valid-class.fixture.js',
+        './loader-test-fixtures/empty-array.fixture.js',
+      ])
+    ).to.throw(InvalidService)
+  })
+
+  it('throws if module exports invalid', function() {
+    expect(() =>
+      loadServiceClasses(['./loader-test-fixtures/invalid-no-base.fixture.js'])
+    ).to.throw(InvalidService)
+    expect(() =>
+      loadServiceClasses([
+        './loader-test-fixtures/invalid-wrong-base.fixture.js',
+      ])
+    ).to.throw(InvalidService)
+    expect(() =>
+      loadServiceClasses(['./loader-test-fixtures/invalid-mixed.fixture.js'])
+    ).to.throw(InvalidService)
+    expect(() =>
+      loadServiceClasses([
+        './loader-test-fixtures/valid-array.fixture.js',
+        './loader-test-fixtures/valid-class.fixture.js',
+        './loader-test-fixtures/invalid-no-base.fixture.js',
+      ])
+    ).to.throw(InvalidService)
+  })
+
+  it('registers services if module exports valid service classes', function() {
+    expect(
+      loadServiceClasses([
+        './loader-test-fixtures/valid-array.fixture.js',
+        './loader-test-fixtures/valid-object.fixture.js',
+        './loader-test-fixtures/valid-class.fixture.js',
+      ])
+    ).to.have.length(5)
+  })
+})

core/base-service/redirector.js

@@ -0,0 +1,123 @@
+'use strict'
+
+const camelcase = require('camelcase')
+const emojic = require('emojic')
+const Joi = require('joi')
+const queryString = require('query-string')
+const BaseService = require('./base')
+const {
+  serverHasBeenUpSinceResourceCached,
+  setCacheHeadersForStaticResource,
+} = require('./cache-headers')
+const { isValidCategory } = require('./categories')
+const { isValidRoute, prepareRoute, namedParamsForMatch } = require('./route')
+const trace = require('./trace')
+
+const attrSchema = Joi.object({
+  name: Joi.string().min(3),
+  category: isValidCategory,
+  route: isValidRoute,
+  transformPath: Joi.func()
+    .maxArity(1)
+    .required()
+    .error(
+      () =>
+        '"transformPath" must be a function that transforms named params to a new path'
+    ),
+  transformQueryParams: Joi.func().arity(1),
+  dateAdded: Joi.date().required(),
+  overrideTransformedQueryParams: Joi.bool().optional(),
+}).required()
+
+module.exports = function redirector(attrs) {
+  const {
+    name,
+    category,
+    route,
+    transformPath,
+    transformQueryParams,
+    overrideTransformedQueryParams,
+  } = Joi.attempt(attrs, attrSchema, `Redirector for ${attrs.route.base}`)
+
+  return class Redirector extends BaseService {
+    static get name() {
+      if (name) {
+        return name
+      } else {
+        return `${camelcase(route.base.replace(/\//g, '_'), {
+          pascalCase: true,
+        })}Redirect`
+      }
+    }
+
+    static get category() {
+      return category
+    }
+
+    static get isDeprecated() {
+      return true
+    }
+
+    static get route() {
+      return route
+    }
+
+    static register({ camp, requestCounter }) {
+      const { regex, captureNames } = prepareRoute(this.route)
+
+      const serviceRequestCounter = this._createServiceRequestCounter({
+        requestCounter,
+      })
+
+      camp.route(regex, async (queryParams, match, end, ask) => {
+        if (serverHasBeenUpSinceResourceCached(ask.req)) {
+          // Send Not Modified.
+          ask.res.statusCode = 304
+          ask.res.end()
+          return
+        }
+
+        const namedParams = namedParamsForMatch(captureNames, match, this)
+        trace.logTrace(
+          'inbound',
+          emojic.arrowHeadingUp,
+          'Redirector',
+          route.base
+        )
+        trace.logTrace('inbound', emojic.ticket, 'Named params', namedParams)
+        trace.logTrace('inbound', emojic.crayon, 'Query params', queryParams)
+
+        const targetPath = transformPath(namedParams)
+        trace.logTrace('validate', emojic.dart, 'Target', targetPath)
+
+        let urlSuffix = ask.uri.search || ''
+
+        if (transformQueryParams) {
+          const specifiedParams = queryString.parse(urlSuffix)
+          const transformedParams = transformQueryParams(namedParams)
+          const redirectParams = overrideTransformedQueryParams
+            ? Object.assign(transformedParams, specifiedParams)
+            : Object.assign(specifiedParams, transformedParams)
+          const outQueryString = queryString.stringify(redirectParams)
+          urlSuffix = `?${outQueryString}`
+        }
+
+        // The final capture group is the extension.
+        const format = match.slice(-1)[0]
+        const redirectUrl = `${targetPath}.${format}${urlSuffix}`
+        trace.logTrace('outbound', emojic.shield, 'Redirect URL', redirectUrl)
+
+        ask.res.statusCode = 301
+        ask.res.setHeader('Location', redirectUrl)
+
+        // To avoid caching mistakes for a long time, and to make this simpler
+        // to reason about, use the same cache semantics as the static badge.
+        setCacheHeadersForStaticResource(ask.res)
+
+        ask.res.end()
+
+        serviceRequestCounter.inc()
+      })
+    }
+  }
+}

core/base-service/redirector.spec.js

@@ -0,0 +1,207 @@
+'use strict'
+
+const Camp = require('camp')
+const got = require('got')
+const portfinder = require('portfinder')
+const { expect } = require('chai')
+const redirector = require('./redirector')
+
+describe('Redirector', function() {
+  const route = {
+    base: 'very/old/service',
+    pattern: ':namedParamA',
+  }
+  const category = 'analysis'
+  const transformPath = () => {}
+  const dateAdded = new Date()
+  const attrs = { category, route, transformPath, dateAdded }
+
+  it('returns true on isDeprecated', function() {
+    expect(redirector(attrs).isDeprecated).to.be.true
+  })
+
+  it('has the expected name', function() {
+    expect(redirector(attrs).name).to.equal('VeryOldServiceRedirect')
+  })
+
+  it('overrides the name', function() {
+    expect(
+      redirector({
+        ...attrs,
+        name: 'ShinyRedirect',
+      }).name
+    ).to.equal('ShinyRedirect')
+  })
+
+  it('sets specified route', function() {
+    expect(redirector(attrs).route).to.deep.equal(route)
+  })
+
+  it('sets specified category', function() {
+    expect(redirector(attrs).category).to.equal(category)
+  })
+
+  it('throws the expected error when dateAdded is missing', function() {
+    expect(() =>
+      redirector({ route, category, transformPath }).validateDefinition()
+    ).to.throw('"dateAdded" is required')
+  })
+
+  describe('ScoutCamp integration', function() {
+    let port, baseUrl
+    beforeEach(async function() {
+      port = await portfinder.getPortPromise()
+      baseUrl = `http://127.0.0.1:${port}`
+    })
+
+    let camp
+    beforeEach(async function() {
+      camp = Camp.start({ port, hostname: '::' })
+      await new Promise(resolve => camp.on('listening', () => resolve()))
+    })
+    afterEach(async function() {
+      if (camp) {
+        await new Promise(resolve => camp.close(resolve))
+        camp = undefined
+      }
+    })
+
+    const transformPath = ({ namedParamA }) => `/new/service/${namedParamA}`
+
+    beforeEach(function() {
+      const ServiceClass = redirector({
+        category,
+        route,
+        transformPath,
+        dateAdded,
+      })
+      ServiceClass.register({ camp }, {})
+    })
+
+    it('should redirect as configured', async function() {
+      const { statusCode, headers } = await got(
+        `${baseUrl}/very/old/service/hello-world.svg`,
+        {
+          followRedirect: false,
+        }
+      )
+
+      expect(statusCode).to.equal(301)
+      expect(headers.location).to.equal('/new/service/hello-world.svg')
+    })
+
+    it('should preserve the extension', async function() {
+      const { statusCode, headers } = await got(
+        `${baseUrl}/very/old/service/hello-world.png`,
+        {
+          followRedirect: false,
+        }
+      )
+
+      expect(statusCode).to.equal(301)
+      expect(headers.location).to.equal('/new/service/hello-world.png')
+    })
+
+    it('should forward the query params', async function() {
+      const { statusCode, headers } = await got(
+        `${baseUrl}/very/old/service/hello-world.svg?color=123&style=flat-square`,
+        {
+          followRedirect: false,
+        }
+      )
+
+      expect(statusCode).to.equal(301)
+      expect(headers.location).to.equal(
+        '/new/service/hello-world.svg?color=123&style=flat-square'
+      )
+    })
+
+    describe('transformQueryParams', function() {
+      const route = {
+        base: 'another/old/service',
+        pattern: 'token/:token/:namedParamA',
+      }
+      const transformQueryParams = ({ token }) => ({ token })
+
+      beforeEach(function() {
+        const ServiceClass = redirector({
+          category,
+          route,
+          transformPath,
+          transformQueryParams,
+          dateAdded,
+        })
+        ServiceClass.register({ camp }, {})
+      })
+
+      it('should forward the transformed query params', async function() {
+        const { statusCode, headers } = await got(
+          `${baseUrl}/another/old/service/token/abc123/hello-world.svg`,
+          {
+            followRedirect: false,
+          }
+        )
+
+        expect(statusCode).to.equal(301)
+        expect(headers.location).to.equal(
+          '/new/service/hello-world.svg?token=abc123'
+        )
+      })
+
+      it('should forward the specified and transformed query params', async function() {
+        const { statusCode, headers } = await got(
+          `${baseUrl}/another/old/service/token/abc123/hello-world.svg?color=123&style=flat-square`,
+          {
+            followRedirect: false,
+          }
+        )
+
+        expect(statusCode).to.equal(301)
+        expect(headers.location).to.equal(
+          '/new/service/hello-world.svg?color=123&style=flat-square&token=abc123'
+        )
+      })
+
+      it('should use transformed query params on param conflicts by default', async function() {
+        const { statusCode, headers } = await got(
+          `${baseUrl}/another/old/service/token/abc123/hello-world.svg?color=123&style=flat-square&token=def456`,
+          {
+            followRedirect: false,
+          }
+        )
+
+        expect(statusCode).to.equal(301)
+        expect(headers.location).to.equal(
+          '/new/service/hello-world.svg?color=123&style=flat-square&token=abc123'
+        )
+      })
+
+      it('should use specified query params on param conflicts when configured', async function() {
+        const route = {
+          base: 'override/service',
+          pattern: 'token/:token/:namedParamA',
+        }
+        const ServiceClass = redirector({
+          category,
+          route,
+          transformPath,
+          transformQueryParams,
+          overrideTransformedQueryParams: true,
+          dateAdded,
+        })
+        ServiceClass.register({ camp }, {})
+        const { statusCode, headers } = await got(
+          `${baseUrl}/override/service/token/abc123/hello-world.svg?style=flat-square&token=def456`,
+          {
+            followRedirect: false,
+          }
+        )
+
+        expect(statusCode).to.equal(301)
+        expect(headers.location).to.equal(
+          '/new/service/hello-world.svg?style=flat-square&token=def456'
+        )
+      })
+    })
+  })
+})

core/base-service/route.js

@@ -0,0 +1,88 @@
+'use strict'
+
+const Joi = require('joi')
+const pathToRegexp = require('path-to-regexp')
+
+function makeFullUrl(base, partialUrl) {
+  return `/${[base, partialUrl].filter(Boolean).join('/')}`
+}
+
+const isValidRoute = Joi.object({
+  base: Joi.string()
+    .allow('')
+    .required(),
+  pattern: Joi.string().allow(''),
+  format: Joi.string(),
+  capture: Joi.alternatives().when('format', {
+    is: Joi.string().required(),
+    then: Joi.array().items(Joi.string().required()),
+  }),
+  queryParamSchema: Joi.object().schema(),
+})
+  .xor('pattern', 'format')
+  .required()
+
+function assertValidRoute(route, message = undefined) {
+  Joi.assert(route, isValidRoute, message)
+}
+
+function prepareRoute({ base, pattern, format, capture }) {
+  let regex, captureNames
+  if (pattern === undefined) {
+    regex = new RegExp(
+      `^${makeFullUrl(base, format)}\\.(svg|png|gif|jpg|json)$`
+    )
+    captureNames = capture || []
+  } else {
+    const fullPattern = `${makeFullUrl(
+      base,
+      pattern
+    )}.:ext(svg|png|gif|jpg|json)`
+    const keys = []
+    regex = pathToRegexp(fullPattern, keys, {
+      strict: true,
+      sensitive: true,
+    })
+    captureNames = keys.map(item => item.name).slice(0, -1)
+  }
+  return { regex, captureNames }
+}
+
+function namedParamsForMatch(captureNames = [], match, ServiceClass) {
+  // Assume the last match is the format, and drop match[0], which is the
+  // entire match.
+  const captures = match.slice(1, -1)
+
+  if (captureNames.length !== captures.length) {
+    throw new Error(
+      `Service ${
+        ServiceClass.name
+      } declares incorrect number of named params ` +
+        `(expected ${captures.length}, got ${captureNames.length})`
+    )
+  }
+
+  const result = {}
+  captureNames.forEach((name, index) => {
+    result[name] = captures[index]
+  })
+  return result
+}
+
+function getQueryParamNames({ queryParamSchema }) {
+  if (queryParamSchema) {
+    const { children, renames = [] } = Joi.describe(queryParamSchema)
+    return Object.keys(children).concat(renames.map(({ from }) => from))
+  } else {
+    return []
+  }
+}
+
+module.exports = {
+  makeFullUrl,
+  isValidRoute,
+  assertValidRoute,
+  prepareRoute,
+  namedParamsForMatch,
+  getQueryParamNames,
+}

core/base-service/route.spec.js

@@ -0,0 +1,124 @@
+'use strict'
+
+const { expect } = require('chai')
+const Joi = require('joi')
+const { test, given, forCases } = require('sazerac')
+const {
+  prepareRoute,
+  namedParamsForMatch,
+  getQueryParamNames,
+} = require('./route')
+
+describe('Route helpers', function() {
+  context('A `pattern` with a named param is declared', function() {
+    const { regex, captureNames } = prepareRoute({
+      base: 'foo',
+      pattern: ':namedParamA',
+      queryParamSchema: Joi.object({ queryParamA: Joi.string() }).required(),
+    })
+
+    const regexExec = str => regex.exec(str)
+    test(regexExec, () => {
+      forCases([
+        given('/foo/bar.bar.bar.zip'),
+        given('/foo/bar/bar.svg'),
+        // This is a valid example with the wrong extension separator, to
+        // test that we only accept a `.`.
+        given('/foo/bar.bar.bar_svg'),
+      ]).expect(null)
+    })
+
+    const namedParams = str =>
+      namedParamsForMatch(captureNames, regex.exec(str))
+    test(namedParams, () => {
+      forCases([
+        given('/foo/bar.bar.bar.svg'),
+        given('/foo/bar.bar.bar.png'),
+        given('/foo/bar.bar.bar.gif'),
+        given('/foo/bar.bar.bar.jpg'),
+        given('/foo/bar.bar.bar.json'),
+      ]).expect({ namedParamA: 'bar.bar.bar' })
+    })
+  })
+
+  context('A `format` with a named param is declared', function() {
+    const { regex, captureNames } = prepareRoute({
+      base: 'foo',
+      format: '([^/]+)',
+      capture: ['namedParamA'],
+    })
+
+    const regexExec = str => regex.exec(str)
+    test(regexExec, () => {
+      forCases([
+        given('/foo/bar.bar.bar.zip'),
+        given('/foo/bar/bar.svg'),
+        // This is a valid example with the wrong extension separator, to
+        // test that we only accept a `.`.
+        given('/foo/bar.bar.bar_svg'),
+      ]).expect(null)
+    })
+
+    const namedParams = str =>
+      namedParamsForMatch(captureNames, regex.exec(str))
+    test(namedParams, () => {
+      forCases([
+        given('/foo/bar.bar.bar.svg'),
+        given('/foo/bar.bar.bar.png'),
+        given('/foo/bar.bar.bar.gif'),
+        given('/foo/bar.bar.bar.jpg'),
+        given('/foo/bar.bar.bar.json'),
+      ]).expect({ namedParamA: 'bar.bar.bar' })
+    })
+  })
+
+  context('No named params are declared', function() {
+    const { regex, captureNames } = prepareRoute({
+      base: 'foo',
+      format: '(?:[^/]+)',
+    })
+
+    const namedParams = str =>
+      namedParamsForMatch(captureNames, regex.exec(str))
+    test(namedParams, () => {
+      forCases([
+        given('/foo/bar.bar.bar.svg'),
+        given('/foo/bar.bar.bar.png'),
+        given('/foo/bar.bar.bar.gif'),
+        given('/foo/bar.bar.bar.jpg'),
+        given('/foo/bar.bar.bar.json'),
+      ]).expect({})
+    })
+  })
+
+  context('The wrong number of params are declared', function() {
+    const { regex, captureNames } = prepareRoute({
+      base: 'foo',
+      format: '([^/]+)/([^/]+)',
+      capture: ['namedParamA'],
+    })
+
+    expect(() =>
+      namedParamsForMatch(captureNames, regex.exec('/foo/bar/baz.svg'), {
+        name: 'MyService',
+      })
+    ).to.throw(
+      'Service MyService declares incorrect number of named params (expected 2, got 1)'
+    )
+  })
+
+  it('getQueryParamNames', function() {
+    expect(
+      getQueryParamNames({
+        queryParamSchema: Joi.object({ foo: Joi.string() }).required(),
+      })
+    ).to.deep.equal(['foo'])
+    expect(
+      getQueryParamNames({
+        queryParamSchema: Joi.object({ foo: Joi.string() })
+          .rename('bar', 'foo', { ignoreUndefined: true, override: true })
+          .required(),
+      })
+    ).to.deep.equal(['foo', 'bar'])
+  })
+})

core/base-service/service-definitions.js

@@ -0,0 +1,86 @@
+'use strict'
+
+const Joi = require('joi')
+
+// This should be kept in sync with the schema in
+// `frontend/lib/service-definitions/service-definition-prop-types.js`.
+
+const arrayOfStrings = Joi.array()
+  .items(Joi.string())
+  .allow([])
+  .required()
+
+const objectOfKeyValues = Joi.object()
+  .pattern(/./, Joi.string().allow(null))
+  .required()
+
+const serviceDefinition = Joi.object({
+  category: Joi.string().required(),
+  name: Joi.string().required(),
+  isDeprecated: Joi.boolean().required(),
+  route: Joi.alternatives().try(
+    Joi.object({
+      pattern: Joi.string().required(),
+      queryParams: arrayOfStrings,
+    }),
+    Joi.object({
+      format: Joi.string().required(),
+      queryParams: arrayOfStrings,
+    })
+  ),
+  examples: Joi.array()
+    .items(
+      Joi.object({
+        title: Joi.string().required(),
+        example: Joi.object({
+          pattern: Joi.string(),
+          namedParams: objectOfKeyValues,
+          queryParams: objectOfKeyValues,
+        }).required(),
+        preview: Joi.object({
+          label: Joi.string(),
+          message: Joi.string()
+            .allow('')
+            .required(),
+          color: Joi.string().required(),
+          style: Joi.string(),
+          namedLogo: Joi.string(),
+        }).required(),
+        keywords: arrayOfStrings,
+        documentation: Joi.object({
+          __html: Joi.string().required(), // Valid HTML.
+        }),
+      })
+    )
+    .default([]),
+}).required()
+
+function assertValidServiceDefinition(example, message = undefined) {
+  Joi.assert(example, serviceDefinition, message)
+}
+
+const serviceDefinitionExport = Joi.object({
+  schemaVersion: Joi.equal('0').required(),
+  categories: Joi.array()
+    .items(
+      Joi.object({
+        id: Joi.string().required(),
+        name: Joi.string().required(),
+      })
+    )
+    .required(),
+  services: Joi.array()
+    .items(serviceDefinition)
+    .required(),
+}).required()
+
+function assertValidServiceDefinitionExport(examples, message = undefined) {
+  Joi.assert(examples, serviceDefinitionExport, message)
+}
+
+module.exports = {
+  serviceDefinition,
+  assertValidServiceDefinition,
+  serviceDefinitionExport,
+  assertValidServiceDefinitionExport,
+}

core/base-service/to-array.js

@@ -0,0 +1,11 @@
+'use strict'
+
+module.exports = function toArray(val) {
+  if (val === undefined) {
+    return []
+  } else if (Object(val) instanceof Array) {
+    return val
+  } else {
+    return [val]
+  }
+}

core/base-service/trace.js

@@ -1,6 +1,7 @@
 'use strict'
 
 const chalk = require('chalk')
+const config = require('config').util.toObject()
 
 // Config is loaded globally but it would be better to inject it. To do that,
 // there needs to be one instance of the service created at registration time,
@@ -9,7 +10,7 @@ const chalk = require('chalk')
 // thereby gaining access to the injected config.
 const {
   services: { trace: enableTraceLogging },
-} = require('../lib/server-config')
+} = config.public
 
 function _formatLabelForStage(stage, label) {
   const colorFn = {

core/base-service/validate.js

@@ -2,14 +2,16 @@
 
 const emojic = require('emojic')
 const Joi = require('joi')
-const trace = require('../services/trace')
+const trace = require('./trace')
 
 function validate(
   {
     ErrorClass,
     prettyErrorMessage = 'data does not match schema',
+    includeKeys = false,
     traceErrorMessage = 'Data did not match schema',
     traceSuccessMessage = 'Data after validation',
+    allowAndStripUnknownKeys = true,
   },
   data,
   schema
@@ -17,10 +19,13 @@ function validate(
   if (!schema || !schema.isJoi) {
     throw Error('A Joi schema is required')
   }
-  const { error, value } = Joi.validate(data, schema, {
-    allowUnknown: true,
-    stripUnknown: true,
-  })
+  const options = allowAndStripUnknownKeys
+    ? {
+        allowUnknown: true,
+        stripUnknown: true,
+      }
+    : undefined
+  const { error, value } = Joi.validate(data, schema, options)
   if (error) {
     trace.logTrace(
       'validate',
@@ -28,10 +33,16 @@ function validate(
       traceErrorMessage,
       error.message
     )
-    throw new ErrorClass({
-      prettyMessage: prettyErrorMessage,
-      underlyingError: error,
-    })
+
+    let prettyMessage = prettyErrorMessage
+    if (includeKeys) {
+      const keys = error.details.map(({ path }) => path)
+      if (keys) {
+        prettyMessage = `${prettyErrorMessage}: ${keys.join(', ')}`
+      }
+    }
+
+    throw new ErrorClass({ prettyMessage, underlyingError: error })
   } else {
     trace.logTrace('validate', emojic.bathtub, traceSuccessMessage, value, {
       deep: true,

core/base-service/validate.spec.js

@@ -3,8 +3,8 @@
 const Joi = require('joi')
 const { expect } = require('chai')
 const sinon = require('sinon')
-const trace = require('../services/trace')
-const { InvalidParameter } = require('../services/errors')
+const trace = require('./trace')
+const { InvalidParameter } = require('./errors')
 const validate = require('./validate')
 
 describe('validate', function() {
@@ -61,7 +61,7 @@ describe('validate', function() {
   })
 
   context('data does not match schema', function() {
-    it('logs the data and throws the expected error', async function() {
+    it('logs the data and throws the expected error', function() {
       try {
         validate(
           options,
@@ -83,5 +83,45 @@ describe('validate', function() {
         'child "requiredString" fails because ["requiredString" must be a string]'
       )
     })
+
+    context('with includeKeys: true', function() {
+      it('includes keys in the error text', function() {
+        try {
+          validate(
+            { ...options, includeKeys: true },
+            {
+              requiredString: ['this', "shouldn't", 'work'],
+            },
+            schema
+          )
+          expect.fail('Expected to throw')
+        } catch (e) {
+          expect(e).to.be.an.instanceof(InvalidParameter)
+          expect(e.message).to.equal(
+            'Invalid Parameter: child "requiredString" fails because ["requiredString" must be a string]'
+          )
+          expect(e.prettyMessage).to.equal(
+            `${prettyErrorMessage}: requiredString`
+          )
+        }
+      })
+    })
+  })
+
+  it('allowAndStripUnknownKeys', function() {
+    try {
+      validate(
+        { ...options, allowAndStripUnknownKeys: false, includeKeys: true },
+        { requiredString: 'bar', extra: 'nonsense', more: 'bogus' },
+        schema
+      )
+      expect.fail('Expected to throw')
+    } catch (e) {
+      expect(e).to.be.an.instanceof(InvalidParameter)
+      expect(e.message).to.equal(
+        'Invalid Parameter: "extra" is not allowed. "more" is not allowed'
+      )
+      expect(e.prettyMessage).to.equal(`${prettyErrorMessage}: extra, more`)
+    }
   })
 })

core/legacy/regular-update.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const { Inaccessible, InvalidResponse } = require('../services/errors')
+const { Inaccessible, InvalidResponse } = require('../base-service/errors')
 
 // Map from URL to { timestamp: last fetch time, data: data }.
 let regularUpdateCache = Object.create(null)
@@ -12,7 +12,7 @@ let regularUpdateCache = Object.create(null)
 // To use this from a service:
 //
 // const { promisify } = require('util')
-// const { regularUpdate } = require('../../lib/regular-update')
+// const { regularUpdate } = require('../../core/legacy/regular-update')
 //
 // function getThing() {
 //   return promisify(regularUpdate)({

core/server/in-process-server-test-helpers.js

@@ -0,0 +1,23 @@
+'use strict'
+
+const config = require('config').util.toObject()
+const Server = require('./server')
+
+function createTestServer({ port }) {
+  const serverConfig = {
+    ...config,
+    public: {
+      ...config.public,
+      bind: {
+        ...config.public.bind,
+        port,
+      },
+    },
+  }
+
+  return new Server(serverConfig)
+}
+
+module.exports = {
+  createTestServer,
+}