Changelog for Release server-2021-06-01 (#6565)

* Update Changelog

Co-authored-by: release[bot] <actions@users.noreply.github.com>
Co-authored-by: chris48s <chris48s@users.noreply.github.com>

.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,280 +1,359 @@
 version: 2
 
+main_steps: &main_steps
+  steps:
+    - checkout
+
+    - run:
+        name: Install dependencies
+        command: npm ci
+        environment:
+          # https://docs.cypress.io/guides/getting-started/installing-cypress.html#Skipping-installation
+          # We don't need to install the Cypress binary in jobs that aren't actually running Cypress.
+          CYPRESS_INSTALL_BINARY: 0
+
+    - 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
+
+    - run:
+        name: Install dependencies
+        command: npm ci
+        environment:
+          CYPRESS_INSTALL_BINARY: 0
+
+    - 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
+
+    - run:
+        name: Install dependencies
+        command: npm ci
+        environment:
+          CYPRESS_INSTALL_BINARY: 0
+
+    - 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: RETRY_COUNT=3 npm run test:services:pr:run
+
+    - store_test_results:
+        path: junit
+
+package_steps: &package_steps
+  steps:
+    - checkout
+
+    - run:
+        name: Install node and npm
+        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
+
+    # Run the package tests on each currently supported node version. See:
+    # https://github.com/badges/shields/blob/master/badge-maker/README.md#node-version-support
+    # https://nodejs.org/en/about/releases/
+
+    - run:
+        environment:
+          mocha_reporter: mocha-junit-reporter
+          MOCHA_FILE: junit/badge-maker/v10/results.xml
+          NODE_VERSION: v10
+          CYPRESS_INSTALL_BINARY: 0
+        name: Run package tests on Node 10
+        command: scripts/run_package_tests.sh
+
+    - run:
+        environment:
+          mocha_reporter: mocha-junit-reporter
+          MOCHA_FILE: junit/badge-maker/v12/results.xml
+          NODE_VERSION: v12
+          CYPRESS_INSTALL_BINARY: 0
+        name: Run package tests on Node 12
+        command: scripts/run_package_tests.sh
+
+    - run:
+        environment:
+          mocha_reporter: mocha-junit-reporter
+          MOCHA_FILE: junit/badge-maker/v14/results.xml
+          NODE_VERSION: v14
+          CYPRESS_INSTALL_BINARY: 0
+        name: Run package tests on Node 14
+        command: scripts/run_package_tests.sh
+
+    - store_test_results:
+        path: junit
+
 jobs:
-  npm-install:
-    docker:
-      - image: shieldsio/shields-ci-node-8:0.0.3
-    working_directory: ~/repo
-    steps:
-      - checkout
-
-      - restore_cache:
-          keys:
-          - v1-dependencies-{{ checksum "package.json" }}
-          # fallback to using the latest cache if no exact match is found
-          - v1-dependencies-
-
-      - run:
-          name: Install dependencies
-          command: npm install
-
-      - save_cache:
-          paths:
-            - node_modules
-          key: v1-dependencies-{{ checksum "package.json" }}
-
   main:
     docker:
-      - image: shieldsio/shields-ci-node-8:0.0.3
-      - image: redis
-    working_directory: ~/repo
-    steps:
-      - checkout
+      - image: circleci/node:12
 
-      - restore_cache:
-          key: v1-dependencies-{{ checksum "package.json" }}
-          # https://github.com/badges/shields/issues/1937
-          key: v1-dependencies-
+    <<: *main_steps
 
-      - 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: 'Prettier check (quick fix: `npm run prettier`)'
-          when: always
-          command: npm run prettier-check
-
-  main@node-latest:
+  main@node-14:
     docker:
-      - image: shieldsio/shields-ci-node-latest:0.0.3
+      - image: circleci/node:14
+
+    <<: *main_steps
+
+  integration:
+    docker:
+      - image: circleci/node:12
       - image: redis
-    working_directory: ~/repo
-    steps:
-      - checkout
 
-      - restore_cache:
-          key: v1-dependencies-{{ checksum "package.json" }}
-          # https://github.com/badges/shields/issues/1937
-          key: v1-dependencies-
+    <<: *integration_steps
 
-      - run:
-          name: Install dependencies
-          command: npm install
+  integration@node-14:
+    docker:
+      - image: circleci/node:14
+      - 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: 'Prettier check (quick fix: `npm run prettier`)'
-          when: always
-          command: npm run prettier-check
+    <<: *integration_steps
 
   danger:
     docker:
-      - image: shieldsio/shields-ci-node-8:0.0.3
-    working_directory: ~/repo
+      - image: circleci/node:12
     steps:
       - checkout
 
-      - restore_cache:
-          key: v1-dependencies-{{ checksum "package.json" }}
-          # https://github.com/badges/shields/issues/1937
-          key: v1-dependencies-
-
       - run:
           name: Install dependencies
-          command: npm install
+          command: npm ci
+          environment:
+            CYPRESS_INSTALL_BINARY: 0
 
       - run:
           name: Danger
           when: always
+          environment:
+            # https://github.com/gatsbyjs/gatsby/pull/11555
+            NODE_ENV: test
           command: npm run danger ci
 
   frontend:
     docker:
-      - image: shieldsio/shields-ci-node-8:0.0.3
-    working_directory: ~/repo
+      - image: circleci/node:12
     steps:
       - checkout
 
-      - restore_cache:
-          key: v1-dependencies-{{ checksum "package.json" }}
-          # https://github.com/badges/shields/issues/1937
-          key: v1-dependencies-
-
       - run:
           name: Install dependencies
-          command: npm install
+          command: npm ci
+          environment:
+            CYPRESS_INSTALL_BINARY: 0
+
+      - run:
+          name: Prepare frontend tests
+          command: npm run defs && npm run features
+
+      - run:
+          name: Check types
+          command: npm run check-types:frontend
 
       - run:
           name: Frontend unit tests
+          environment:
+            mocha_reporter: mocha-junit-reporter
+            MOCHA_FILE: junit/frontend/results.xml
           when: always
-          command: npm run test:js:frontend
+          command: npm run test:frontend
+
+      - store_test_results:
+          path: junit
 
       - run:
           name: Frontend build completes successfully
           when: always
           command: npm run build
 
-  services-pr:
+  package:
+    machine: true
+
+    <<: *package_steps
+
+  services:
     docker:
-      - image: shieldsio/shields-ci-node-8:0.0.3
-    working_directory: ~/repo
+      - image: circleci/node:12
+
+    <<: *services_steps
+
+  services@node-14:
+    docker:
+      - image: circleci/node:14
+
+    <<: *services_steps
+
+  e2e:
+    docker:
+      - image: cypress/base:12
     steps:
       - checkout
 
-      - run:
-          name: Prepare service tests
-          command: |
-            mkdir private
-            echo "{\"gh_token\":\"$GITHUB_TOKEN\"}" > private/secret.json
-
       - restore_cache:
-          key: v1-dependencies-{{ checksum "package.json" }}
-          # https://github.com/badges/shields/issues/1937
-          key: v1-dependencies-
+          name: Restore Cypress binary
+          keys:
+            - v2-cypress-dependencies-{{ checksum "package-lock.json" }}
 
       - 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
 
-  services-pr@node-latest:
-    docker:
-      - image: shieldsio/shields-ci-node-latest:0.0.3
-    working_directory: ~/repo
-    steps:
-      - checkout
+      - store_test_results:
+          path: junit
 
-      - run:
-          name: Prepare service tests
-          command: |
-            mkdir private
-            echo "{\"gh_token\":\"$GITHUB_TOKEN\"}" > private/secret.json
+      - store_artifacts:
+          path: cypress/videos
 
-      - restore_cache:
-          key: v1-dependencies-{{ checksum "package.json" }}
-          # https://github.com/badges/shields/issues/1937
-          key: v1-dependencies-
+      - store_artifacts:
+          path: cypress/screenshots
 
-      - 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-daily:
-    docker:
-      - image: shieldsio/shields-ci-node-8:0.0.3
-    working_directory: ~/repo
-    steps:
-      - checkout
-
-      - restore_cache:
-          key: v1-dependencies-{{ checksum "package.json" }}
-
-      - run:
-          name: Run all service tests
-          command: npm run test:services
+      - save_cache:
+          name: Cache Cypress binary
+          paths:
+            # https://docs.cypress.io/guides/getting-started/installing-cypress.html#Binary-cache
+            - ~/.cache/Cypress
+          key: v2-cypress-dependencies-{{ checksum "package-lock.json" }}
 
 workflows:
   version: 2
 
   on-commit:
     jobs:
-      - npm-install:
+      - main:
+          filters:
+            branches:
+              ignore: gh-pages
+      - main@node-14:
+          filters:
+            branches:
+              ignore: gh-pages
+      - integration@node-14:
           filters:
             branches:
               ignore: gh-pages
-      - main:
-          requires:
-            - npm-install
-      - main@node-latest:
-          requires:
-            - npm-install
       - frontend:
-          requires:
-            - npm-install
-      - services-pr:
-          requires:
-            - npm-install
-      - services-pr@node-latest:
-          requires:
-            - npm-install
+          filters:
+            branches:
+              ignore: gh-pages
+      - package:
+          filters:
+            branches:
+              ignore: gh-pages
+      - services:
+          filters:
+            branches:
+              ignore:
+                - master
+                - gh-pages
+      - services@node-14:
+          filters:
+            branches:
+              ignore:
+                - master
+                - gh-pages
       - danger:
-          requires:
-            - npm-install
           filters:
             branches:
-              ignore: /dependabot\/.*/
-
-  daily:
-    triggers:
-      - schedule:
-          cron: "0 17 * * *"
+              ignore:
+                - master
+                - gh-pages
+                - /dependabot\/.*/
+      - e2e:
           filters:
             branches:
-              only: master
-    jobs:
-      - services-daily
+              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\/.*/

.circleci/images/README.md

@@ -1,35 +0,0 @@
-Updating CircleCI Docker images
-===============================
-
-Prerequisites
--------------
-
-1. Ask @paulmelnikow to be added to the shieldsio organization on DockerHub.
-2. Install Docker. I tested [these instructions on OS X][Install Docker on OS X].
-3. Run `eval $(docker-machine env default)`
-   (In fish: `eval (docker-machine env default)`)
-
-[Install Docker on OS X]: https://pilsniak.com/how-to-install-docker-on-mac-os-using-brew/
-
-Updating the images
--------------------
-
-Note: Increment the patch version on the tag in each change. Check
-[Docker Hub][] to see the current versions.
-
-```console
-IMAGE_TAG=<version> npm run circle-images:build
-docker login
-IMAGE_TAG=<version> npm run circle-images:push
-```
-
-After pushing the images, bump the tag in `.circleci/config.yml`.
-
-[Docker Hub]: https://hub.docker.com/u/shieldsio/
-
-Reference
----------
-
-For more details see the [CircleCI custom image docs][].
-
-[CircleCI custom image docs]: https://circleci.com/docs/2.0/custom-images/

.circleci/images/node-8/Dockerfile

@@ -1,4 +0,0 @@
-FROM node:8
-ADD .circleci/images/prepare-container.sh /root/prepare-container.sh
-RUN /root/prepare-container.sh
-RUN rm /root/prepare-container.sh

.circleci/images/node-latest/Dockerfile

@@ -1,4 +0,0 @@
-FROM node:latest
-ADD .circleci/images/prepare-container.sh /root/prepare-container.sh
-RUN /root/prepare-container.sh
-RUN rm /root/prepare-container.sh

.circleci/images/prepare-container.sh

@@ -1,10 +0,0 @@
-#!/bin/bash
-
-set -eo pipefail
-
-apt-get -y update
-apt-get install -y --no-install-recommends fonts-dejavu-core
-apt-get clean
-rm -rf /var/lib/apt/lists/*
-
-npm install -g greenkeeper-lockfile@1

.dependabot/config.yml

@@ -0,0 +1,38 @@
+version: 1
+update_configs:
+  # shields.io dependencies
+  - package_manager: 'javascript'
+    directory: '/'
+    update_schedule: 'weekly'
+    automerged_updates:
+      - match:
+          dependency_name: 'chai*'
+          update_type: 'semver:minor'
+      - match:
+          dependency_name: 'cypress'
+          update_type: 'semver:minor'
+      - match:
+          dependency_name: 'eslint*'
+          update_type: 'semver:minor'
+      - match:
+          dependency_name: 'mocha*'
+          update_type: 'semver:minor'
+      - match:
+          dependency_name: 'sazerac'
+          update_type: 'semver:minor'
+      - match:
+          dependency_name: 'sinon*'
+          update_type: 'semver:minor'
+      - match:
+          dependency_name: 'snap-shot-it'
+          update_type: 'semver:minor'
+
+  # badge-maker package dependencies
+  - package_manager: 'javascript'
+    directory: '/badge-maker'
+    update_schedule: 'weekly'
+
+  # approve-bot package dependencies
+  - package_manager: 'javascript'
+    directory: '.github/actions/approve-bot'
+    update_schedule: 'weekly'

.dockerignore

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

.eslintignore

@@ -1,3 +1,7 @@
+/api-docs/
 /build
 /coverage
 /__snapshots__
+/public
+badge-maker/node_modules/
+!.github/

.eslintrc-frontend.yml

@@ -1,24 +0,0 @@
-env:
-  browser: true
-
-plugins:
-  - import
-
-parser: "babel-eslint"
-
-parserOptions:
-  sourceType: "module"
-
-extends:
-  - "standard-jsx"
-  - "standard-react"
-  - "./.eslintrc.yml"
-
-settings:
-  react:
-    version: "16.4"
-
-rules:
-  no-console: "error"
-
-  import/extensions: ["error", "never", { "json": "always" }]

.eslintrc.yml

@@ -1,49 +1,199 @@
 extends:
   - standard
+  - standard-jsx
+  - standard-react
+  - plugin:@typescript-eslint/recommended
   - prettier
+  - eslint:recommended
 
-env:
-  node: true
-  mocha: true
+globals:
+  JSX: 'readonly'
 
 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'
+
+settings:
+  react:
+    version: '16.8'
+  jsdoc:
+    mode: jsdoc
 
 plugins:
+  - chai-friendly
+  - jsdoc
   - mocha
   - no-extension-in-require
-  - "chai-friendly"
+  - sort-class-members
+  - import
+  - react-hooks
+  - promise
+
+overrides:
+  # For simplicity's sake, when possible prefer to add rules to the top-level
+  # list of rules, even if they only apply to certain files. That way the
+  # rules listed here are only ones which conflict.
+
+  - files:
+      - '**/*.js'
+      - '!frontend/**/*.js'
+    env:
+      node: true
+      es6: true
+    rules:
+      no-console: 'off'
+      '@typescript-eslint/explicit-module-boundary-types': 'off'
+
+  - files:
+      - '**/*.@(ts|tsx)'
+    parserOptions:
+      sourceType: 'module'
+    parser: '@typescript-eslint/parser'
+    rules:
+      # Argh.
+      '@typescript-eslint/explicit-function-return-type':
+        ['error', { 'allowExpressions': true }]
+      '@typescript-eslint/no-empty-function': 'error'
+      '@typescript-eslint/no-var-requires': 'error'
+      '@typescript-eslint/no-object-literal-type-assertion': 'off'
+      '@typescript-eslint/no-explicit-any': 'error'
+      '@typescript-eslint/ban-ts-ignore': 'off'
+      '@typescript-eslint/explicit-module-boundary-types': 'off'
+
+  - files:
+      - core/**/*.ts
+    parserOptions:
+      sourceType: 'module'
+    parser: '@typescript-eslint/parser'
+  - files:
+      - gatsby-browser.js
+      - 'frontend/**/*.@(js|ts|tsx)'
+    parserOptions:
+      sourceType: 'module'
+    env:
+      browser: true
+    rules:
+      import/extensions:
+        ['error', 'never', { 'json': 'always', 'yml': 'always' }]
+
+  - files:
+      - 'core/base-service/**/*.js'
+      - 'services/**/*.js'
+    rules:
+      sort-class-members/sort-class-members:
+        [
+          'error',
+          {
+            order:
+              [
+                'name',
+                'category',
+                'isDeprecated',
+                'route',
+                'auth',
+                'examples',
+                '_cacheLength',
+                'defaultBadgeData',
+                'render',
+                'constructor',
+                'fetch',
+                'transform',
+                'handle',
+              ],
+          },
+        ]
+
+  - files:
+      - '**/*.spec.@(js|ts|tsx)'
+      - '**/*.integration.js'
+      - '**/test-helpers.js'
+      - 'core/service-test-runner/**/*.js'
+    env:
+      mocha: true
+    rules:
+      mocha/no-exclusive-tests: 'error'
+      mocha/no-mocha-arrows: 'error'
+      mocha/prefer-arrow-callback: 'error'
 
 rules:
   # Disable some rules from eslint:recommended.
-  no-console: "off"
-  no-empty: ["error", { "allowEmptyCatch": true }]
+  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"}]
+  '@typescript-eslint/no-unused-vars': ['error', { 'args': 'none' }]
+  no-unused-vars: 'off'
+
+  '@typescript-eslint/no-var-requires': 'off'
+
+  '@typescript-eslint/no-use-before-define': 'error'
+  no-use-before-define: 'off'
 
   # These should be disabled by eslint-config-prettier, but are not.
-  spaced-comment: "off"
-  standard/object-curly-even-spacing: "off"
-  one-var: "off"
+  no-extra-semi: '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"
+  # Account for destructuring responses from upstream services,
+  # many of which do not follow camelcase
+  # Based on original rule configuration from eslint-config-standard
+  camelcase:
+    [
+      'error',
+      {
+        ignoreDestructuring: true,
+        properties: 'never',
+        ignoreGlobals: true,
+        allow: ['^UNSAFE_'],
+      },
+    ]
 
   # Chai friendly.
-  no-unused-expressions: "off"
-  chai-friendly/no-unused-expressions: "error"
+  no-unused-expressions: 'off'
+  chai-friendly/no-unused-expressions: 'error'
+
+  # jsdoc plugin:
+  # don't require every class/function to have a docblock
+  jsdoc/require-jsdoc: 'off'
+
+  # allow Joi as an undefined type
+  jsdoc/no-undefined-types: ['error', { definedTypes: ['Joi'] }]
+
+  # all the other recommended rules as errors (not warnings)
+  jsdoc/check-alignment: 'error'
+  jsdoc/check-param-names: 'error'
+  jsdoc/check-tag-names: 'error'
+  jsdoc/check-types: 'error'
+  jsdoc/implements-on-classes: 'error'
+  jsdoc/newline-after-description: 'error'
+  jsdoc/require-param: 'error'
+  jsdoc/require-param-description: 'error'
+  jsdoc/require-param-name: 'error'
+  jsdoc/require-param-type: 'error'
+  jsdoc/require-returns: 'error'
+  jsdoc/require-returns-check: 'error'
+  jsdoc/require-returns-description: 'error'
+  jsdoc/require-returns-type: 'error'
+  jsdoc/valid-types: 'error'
+
+  # Disable some from TypeScript.
+  '@typescript-eslint/camelcase': off
+  '@typescript-eslint/explicit-function-return-type': 'off'
+  '@typescript-eslint/no-empty-function': 'off'
+
+  react/jsx-sort-props: 'error'
+  react-hooks/rules-of-hooks: 'error'
+  react-hooks/exhaustive-deps: 'error'
+  jsx-quotes: ['error', 'prefer-double']

.github/FUNDING.yml

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

.github/ISSUE_TEMPLATE/1_Bug_report.md

@@ -1,26 +1,29 @@
 ---
 name: 🐛 Bug Report
 about: Report errors and problems
-
+labels: 'question'
 ---
 
 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
+- [ ] [badge-maker NPM package](https://www.npmjs.com/package/badge-maker)
 
 :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,36 @@
+---
+name: 💚 Failing service test
+about: Note failing service tests
+labels: 'keep-service-tests-green'
+---
+
+: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,11 @@
 ---
 name: 💡 Badge Request
 about: Ideas for new badges
-
+labels: 'service-badge'
 ---
 
 :clipboard: **Description**
+
 <!--
 A clear and concise description of the new badge.
 
@@ -15,6 +16,7 @@ A clear and concise description of the new badge.
 -->
 
 :link: **Data**
+
 <!--
 Where can we get the data from?
 
@@ -23,6 +25,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/4_Support_question.md

@@ -1,17 +0,0 @@
----
-name: ❓ Support Question
-about: Ask a question about shields.io
-
----
-
-:question: **Question**
-<!--
-Ask your question clearly and concisely.
-
-#support on our [Discord](https://discordapp.com/invite/HjJCwm5)
-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 -->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,7 @@
+contact_links:
+  - name: 🎨 Simple Icons
+    url: https://github.com/badges/shields/discussions/5369
+    about: Please read this before posting a question about SimpleIcons
+  - name: ❓ Support Question
+    url: https://github.com/badges/shields/discussions
+    about: Ask a question about Shields.io

.github/actions/approve-bot/action.yml

@@ -0,0 +1,12 @@
+name: 'Auto Approve'
+description: 'Automatically approve/close selected pull requests for shields.io'
+branding:
+  icon: 'check-circle'
+  color: 'green'
+inputs:
+  github-token:
+    description: 'The GITHUB_TOKEN secret'
+    required: true
+runs:
+  using: 'node12'
+  main: 'index.js'

.github/actions/approve-bot/helpers.js

@@ -0,0 +1,68 @@
+'use strict'
+
+function findChangelogStart(lines) {
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (
+      line === '<summary>Changelog</summary>' &&
+      lines[i + 2] === '<blockquote>'
+    ) {
+      return i + 3
+    }
+  }
+  return null
+}
+
+function findChangelogEnd(lines, start) {
+  for (let i = start; i < lines.length; i++) {
+    const line = lines[i]
+    if (line === '</blockquote>') {
+      return i
+    }
+  }
+  return null
+}
+
+function allChangelogLinesAreVersionBump(changelogLines) {
+  return (
+    changelogLines.length > 0 &&
+    changelogLines.length ===
+      changelogLines.filter(line =>
+        line.includes('Version bump only for package')
+      ).length
+  )
+}
+
+function isPointlessVersionBump(body) {
+  const pointlessBumpLinks = [
+    'https://github.com/gatsbyjs/gatsby',
+    'https://github.com/typescript-eslint/typescript-eslint',
+  ]
+
+  const lines = body.split(/\r?\n/)
+  if (!pointlessBumpLinks.some(link => lines[0].includes(link))) {
+    return false
+  }
+  const start = findChangelogStart(lines)
+  const end = findChangelogEnd(lines, start)
+  if (!start || !end) {
+    return false
+  }
+  const changelogLines = lines
+    .slice(start, end)
+    .filter(line => !line.startsWith('<h'))
+    .filter(line => !line.startsWith('<p>All notable changes'))
+    .filter(
+      line => !line.startsWith('See <a href="https://conventionalcommits.org">')
+    )
+    .filter(line => !line.startsWith('<!--'))
+  return allChangelogLinesAreVersionBump(changelogLines)
+}
+
+function shouldAutoMerge(body) {
+  return body.includes(
+    'If all status checks pass Dependabot will automatically merge this pull request'
+  )
+}
+
+module.exports = { isPointlessVersionBump, shouldAutoMerge }

.github/actions/approve-bot/index.js

@@ -0,0 +1,56 @@
+'use strict'
+
+const core = require('@actions/core')
+const github = require('@actions/github')
+const { isPointlessVersionBump, shouldAutoMerge } = require('./helpers')
+
+async function run() {
+  try {
+    const token = core.getInput('github-token', { required: true })
+
+    const { pull_request: pr } = github.context.payload
+    if (!pr) {
+      throw new Error('Event payload missing `pull_request`')
+    }
+
+    const client = github.getOctokit(token)
+
+    if (
+      ['dependabot[bot]', 'dependabot-preview[bot]'].includes(pr.user.login)
+    ) {
+      if (isPointlessVersionBump(pr.body)) {
+        core.debug(`Closing pull request #${pr.number}`)
+        await client.rest.pulls.update({
+          owner: github.context.repo.owner,
+          repo: github.context.repo.repo,
+          pull_number: pr.number,
+          state: 'closed',
+        })
+
+        core.debug(`Done.`)
+      } else if (shouldAutoMerge(pr.body)) {
+        core.debug(`Adding label to pull request #${pr.number}`)
+        await client.rest.issues.addLabels({
+          owner: github.context.repo.owner,
+          repo: github.context.repo.repo,
+          issue_number: pr.number,
+          labels: ['squash when passing'],
+        })
+
+        core.debug(`Creating approving review for pull request #${pr.number}`)
+        await client.rest.pulls.createReview({
+          owner: github.context.repo.owner,
+          repo: github.context.repo.repo,
+          pull_number: pr.number,
+          event: 'APPROVE',
+        })
+
+        core.debug(`Done.`)
+      }
+    }
+  } catch (error) {
+    core.setFailed(error.message)
+  }
+}
+
+run()

.github/actions/approve-bot/package-lock.json

@@ -0,0 +1,170 @@
+{
+  "name": "approve-bot",
+  "version": "0.0.0",
+  "lockfileVersion": 1,
+  "requires": true,
+  "dependencies": {
+    "@actions/core": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/@actions/core/-/core-1.3.0.tgz",
+      "integrity": "sha512-xxtX0Cwdhb8LcgatfJkokqT8KzPvcIbwL9xpLU09nOwBzaStbfm0dNncsP0M4us+EpoPdWy7vbzU5vSOH7K6pg=="
+    },
+    "@actions/github": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/@actions/github/-/github-5.0.0.tgz",
+      "integrity": "sha512-QvE9eAAfEsS+yOOk0cylLBIO/d6WyWIOvsxxzdrPFaud39G6BOkUwScXZn1iBzQzHyu9SBkkLSWlohDWdsasAQ==",
+      "requires": {
+        "@actions/http-client": "^1.0.11",
+        "@octokit/core": "^3.4.0",
+        "@octokit/plugin-paginate-rest": "^2.13.3",
+        "@octokit/plugin-rest-endpoint-methods": "^5.1.1"
+      }
+    },
+    "@actions/http-client": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/@actions/http-client/-/http-client-1.0.11.tgz",
+      "integrity": "sha512-VRYHGQV1rqnROJqdMvGUbY/Kn8vriQe/F9HR2AlYHzmKuM/p3kjNuXhmdBfcVgsvRWTz5C5XW5xvndZrVBuAYg==",
+      "requires": {
+        "tunnel": "0.0.6"
+      }
+    },
+    "@octokit/auth-token": {
+      "version": "2.4.5",
+      "resolved": "https://registry.npmjs.org/@octokit/auth-token/-/auth-token-2.4.5.tgz",
+      "integrity": "sha512-BpGYsPgJt05M7/L/5FoE1PiAbdxXFZkX/3kDYcsvd1v6UhlnE5e96dTDr0ezX/EFwciQxf3cNV0loipsURU+WA==",
+      "requires": {
+        "@octokit/types": "^6.0.3"
+      }
+    },
+    "@octokit/core": {
+      "version": "3.4.0",
+      "resolved": "https://registry.npmjs.org/@octokit/core/-/core-3.4.0.tgz",
+      "integrity": "sha512-6/vlKPP8NF17cgYXqucdshWqmMZGXkuvtcrWCgU5NOI0Pl2GjlmZyWgBMrU8zJ3v2MJlM6++CiB45VKYmhiWWg==",
+      "requires": {
+        "@octokit/auth-token": "^2.4.4",
+        "@octokit/graphql": "^4.5.8",
+        "@octokit/request": "^5.4.12",
+        "@octokit/request-error": "^2.0.5",
+        "@octokit/types": "^6.0.3",
+        "before-after-hook": "^2.2.0",
+        "universal-user-agent": "^6.0.0"
+      }
+    },
+    "@octokit/endpoint": {
+      "version": "6.0.11",
+      "resolved": "https://registry.npmjs.org/@octokit/endpoint/-/endpoint-6.0.11.tgz",
+      "integrity": "sha512-fUIPpx+pZyoLW4GCs3yMnlj2LfoXTWDUVPTC4V3MUEKZm48W+XYpeWSZCv+vYF1ZABUm2CqnDVf1sFtIYrj7KQ==",
+      "requires": {
+        "@octokit/types": "^6.0.3",
+        "is-plain-object": "^5.0.0",
+        "universal-user-agent": "^6.0.0"
+      }
+    },
+    "@octokit/graphql": {
+      "version": "4.6.2",
+      "resolved": "https://registry.npmjs.org/@octokit/graphql/-/graphql-4.6.2.tgz",
+      "integrity": "sha512-WmsIR1OzOr/3IqfG9JIczI8gMJUMzzyx5j0XXQ4YihHtKlQc+u35VpVoOXhlKAlaBntvry1WpAzPl/a+s3n89Q==",
+      "requires": {
+        "@octokit/request": "^5.3.0",
+        "@octokit/types": "^6.0.3",
+        "universal-user-agent": "^6.0.0"
+      }
+    },
+    "@octokit/openapi-types": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-7.0.0.tgz",
+      "integrity": "sha512-gV/8DJhAL/04zjTI95a7FhQwS6jlEE0W/7xeYAzuArD0KVAVWDLP2f3vi98hs3HLTczxXdRK/mF0tRoQPpolEw=="
+    },
+    "@octokit/plugin-paginate-rest": {
+      "version": "2.13.3",
+      "resolved": "https://registry.npmjs.org/@octokit/plugin-paginate-rest/-/plugin-paginate-rest-2.13.3.tgz",
+      "integrity": "sha512-46lptzM9lTeSmIBt/sVP/FLSTPGx6DCzAdSX3PfeJ3mTf4h9sGC26WpaQzMEq/Z44cOcmx8VsOhO+uEgE3cjYg==",
+      "requires": {
+        "@octokit/types": "^6.11.0"
+      }
+    },
+    "@octokit/plugin-rest-endpoint-methods": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/@octokit/plugin-rest-endpoint-methods/-/plugin-rest-endpoint-methods-5.1.1.tgz",
+      "integrity": "sha512-u4zy0rVA8darm/AYsIeWkRalhQR99qPL1D/EXHejV2yaECMdHfxXiTXtba8NMBSajOJe8+C9g+EqMKSvysx0dg==",
+      "requires": {
+        "@octokit/types": "^6.14.1",
+        "deprecation": "^2.3.1"
+      }
+    },
+    "@octokit/request": {
+      "version": "5.4.15",
+      "resolved": "https://registry.npmjs.org/@octokit/request/-/request-5.4.15.tgz",
+      "integrity": "sha512-6UnZfZzLwNhdLRreOtTkT9n57ZwulCve8q3IT/Z477vThu6snfdkBuhxnChpOKNGxcQ71ow561Qoa6uqLdPtag==",
+      "requires": {
+        "@octokit/endpoint": "^6.0.1",
+        "@octokit/request-error": "^2.0.0",
+        "@octokit/types": "^6.7.1",
+        "is-plain-object": "^5.0.0",
+        "node-fetch": "^2.6.1",
+        "universal-user-agent": "^6.0.0"
+      }
+    },
+    "@octokit/request-error": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/@octokit/request-error/-/request-error-2.0.5.tgz",
+      "integrity": "sha512-T/2wcCFyM7SkXzNoyVNWjyVlUwBvW3igM3Btr/eKYiPmucXTtkxt2RBsf6gn3LTzaLSLTQtNmvg+dGsOxQrjZg==",
+      "requires": {
+        "@octokit/types": "^6.0.3",
+        "deprecation": "^2.0.0",
+        "once": "^1.4.0"
+      }
+    },
+    "@octokit/types": {
+      "version": "6.14.2",
+      "resolved": "https://registry.npmjs.org/@octokit/types/-/types-6.14.2.tgz",
+      "integrity": "sha512-wiQtW9ZSy4OvgQ09iQOdyXYNN60GqjCL/UdMsepDr1Gr0QzpW6irIKbH3REuAHXAhxkEk9/F2a3Gcs1P6kW5jA==",
+      "requires": {
+        "@octokit/openapi-types": "^7.0.0"
+      }
+    },
+    "before-after-hook": {
+      "version": "2.2.1",
+      "resolved": "https://registry.npmjs.org/before-after-hook/-/before-after-hook-2.2.1.tgz",
+      "integrity": "sha512-/6FKxSTWoJdbsLDF8tdIjaRiFXiE6UHsEHE3OPI/cwPURCVi1ukP0gmLn7XWEiFk5TcwQjjY5PWsU+j+tgXgmw=="
+    },
+    "deprecation": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/deprecation/-/deprecation-2.3.1.tgz",
+      "integrity": "sha512-xmHIy4F3scKVwMsQ4WnVaS8bHOx0DmVwRywosKhaILI0ywMDWPtBSku2HNxRvF7jtwDRsoEwYQSfbxj8b7RlJQ=="
+    },
+    "is-plain-object": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/is-plain-object/-/is-plain-object-5.0.0.tgz",
+      "integrity": "sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q=="
+    },
+    "node-fetch": {
+      "version": "2.6.1",
+      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.1.tgz",
+      "integrity": "sha512-V4aYg89jEoVRxRb2fJdAg8FHvI7cEyYdVAh94HH0UIK8oJxUfkjlDQN9RbMx+bEjP7+ggMiFRprSti032Oipxw=="
+    },
+    "once": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
+      "integrity": "sha1-WDsap3WWHUsROsF9nFC6753Xa9E=",
+      "requires": {
+        "wrappy": "1"
+      }
+    },
+    "tunnel": {
+      "version": "0.0.6",
+      "resolved": "https://registry.npmjs.org/tunnel/-/tunnel-0.0.6.tgz",
+      "integrity": "sha512-1h/Lnq9yajKY2PEbBadPXj3VxsDDu844OnaAo52UVmIzIvwwtBPIuNvkjuzBlTWpfJyUbG3ez0KSBibQkj4ojg=="
+    },
+    "universal-user-agent": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/universal-user-agent/-/universal-user-agent-6.0.0.tgz",
+      "integrity": "sha512-isyNax3wXoKaulPDZWHQqbmIx1k2tb9fb3GGDBRxCscfYV2Ch7WxPArBsFEG8s/safwXTT7H4QGhaIkTp9447w=="
+    },
+    "wrappy": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
+      "integrity": "sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8="
+    }
+  }
+}

.github/actions/approve-bot/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "approve-bot",
+  "version": "0.0.0",
+  "description": "",
+  "main": "index.js",
+  "private": true,
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "chris48s",
+  "license": "CC0",
+  "dependencies": {
+    "@actions/core": "^1.3.0",
+    "@actions/github": "^5.0.0"
+  }
+}

.github/actions/draft-release/Dockerfile

@@ -0,0 +1,8 @@
+FROM node:12-buster
+
+RUN apt-get update
+RUN apt-get install -y jq
+RUN apt-get install -y uuid-runtime
+COPY entrypoint.sh /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]

.github/actions/draft-release/action.yml

@@ -0,0 +1,5 @@
+name: 'draft-release'
+description: 'Generate a changelog and propose a release PR'
+runs:
+  using: 'docker'
+  image: 'Dockerfile'

.github/actions/draft-release/entrypoint.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+
+set -euxo pipefail
+
+# Set up a git user
+git config user.name "release[bot]"
+git config user.email "actions@users.noreply.github.com"
+
+# Find last server-YYYY-MM-DD tag
+git fetch --unshallow --tags
+LAST_TAG=$(git tag | grep server | tail -n 1)
+
+# Find the marker in CHANGELOG.md
+INSERT_POINT=$(grep -n "^\-\-\-$" CHANGELOG.md | cut -f1 -d:)
+INSERT_POINT=$((INSERT_POINT+1))
+
+# Generate a release name
+RELEASE_NAME="server-$(date --rfc-3339=date)"
+
+# Assemble changelog entry
+rm -f temp-changes.txt
+touch temp-changes.txt
+{
+    echo "## $RELEASE_NAME"
+    echo ""
+    git log "$LAST_TAG"..HEAD --no-merges --oneline --pretty="format:- %s" --perl-regexp --author='^((?!dependabot).*)$'
+    echo $'\n- Dependency updates\n'
+} >> temp-changes.txt
+BASE_URL="https:\/\/github.com\/badges\/shields\/issues\/"
+sed -r -i "s/\((\#)([0-9]+)\)$/\[\1\2\]\($BASE_URL\2\)/g" temp-changes.txt
+
+# Write the changelog
+sed -i "${INSERT_POINT} r temp-changes.txt" CHANGELOG.md
+
+# Cleanup
+rm temp-changes.txt
+
+# Run prettier (to ensure the markdown file doesn't fail CI)
+npx prettier@$(cat package.json | jq -r .devDependencies.prettier) --write "CHANGELOG.md"
+
+# Generate a unique branch name
+BRANCH_NAME="$RELEASE_NAME"-$(uuidgen | head -c 8)
+git checkout -b "$BRANCH_NAME"
+
+# Commit + push changelog
+git add CHANGELOG.md
+git commit -m "Update Changelog"
+git push origin "$BRANCH_NAME"
+
+# Submit a PR
+TITLE="Changelog for Release $RELEASE_NAME"
+PR_RESP=$(curl https://api.github.com/repos/"$REPO_NAME"/pulls \
+    -X POST \
+    -H "Authorization: token $GITHUB_TOKEN" \
+    --data '{"title": "'"$TITLE"'", "body": "'"$TITLE"'", "head": "'"$BRANCH_NAME"'", "base": "master"}')
+
+# Add the 'release' label to the PR
+PR_API_URL=$(echo "$PR_RESP" | jq -r ._links.issue.href)
+curl "$PR_API_URL" \
+    -X POST \
+    -H "Authorization: token $GITHUB_TOKEN" \
+    --data '{"labels":["release"]}'

.github/probot.js

@@ -1,10 +0,0 @@
-on('pull_request.closed')
-  .filter(context => context.payload.pull_request.merged)
-  .filter(
-    context =>
-      context.payload.pull_request.head.ref.slice(0, 11) !== 'dependabot/'
-  )
-  .filter(context => context.payload.pull_request.base.ref === 'master')
-  .comment(`This pull request was merged to [{{ pull_request.base.ref }}]({{ repository.html_url }}/tree/{{ pull_request.base.ref }}) branch. This change is now waiting for deployment, which will usually happen within a few days. Stay tuned by joining our \`#ops\` channel on [Discord](https://discordapp.com/invite/HjJCwm5)!
-  
-After deployment, changes are copied to [gh-pages]({{ repository.html_url }}/tree/gh-pages) branch: ![](https://img.shields.io/github/commit-status/{{ repository.full_name }}/gh-pages/{{ pull_request.merge_commit_sha }}.svg?label=deploy%20status)`)

.github/pull_request_template.md

@@ -0,0 +1,7 @@
+<!--
+    Be sure to review our Contributing guidelines to help streamline the merging of your PR!
+
+    * PR title conventions - https://github.com/badges/shields/blob/master/CONTRIBUTING.md#running-service-tests-in-pull-requests
+    * Code formatting - https://github.com/badges/shields/blob/master/CONTRIBUTING.md#prettier
+    * Merge processes and reminders - https://github.com/badges/shields/blob/master/CONTRIBUTING.md#pull-requests
+-->

.github/workflows/auto-approve.yml

@@ -0,0 +1,16 @@
+name: Auto approve
+on: pull_request
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Install action dependencies
+        run: cd .github/actions/approve-bot && npm ci
+
+      - uses: ./.github/actions/approve-bot
+        with:
+          github-token: '${{ secrets.GITHUB_TOKEN }}'

.github/workflows/deploy-docs.yml

@@ -0,0 +1,26 @@
+name: Deploy Documentation
+on:
+  push:
+    branches:
+      - master
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2.3.1
+        with:
+          persist-credentials: false
+
+      - name: Build
+        run: |
+          npm ci
+          npm run build-docs
+
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@3.7.1
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: gh-pages
+          FOLDER: api-docs
+          CLEAN: true

.github/workflows/draft-release.yml

@@ -0,0 +1,19 @@
+name: Draft Release
+on:
+  schedule:
+    - cron: '0 1 1 * *'
+    # At 01:00 on the first day of every month
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Draft Release
+        uses: ./.github/actions/draft-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO_NAME: ${{ github.repository }}

.github/workflows/tag-release.yml

@@ -0,0 +1,31 @@
+name: Tag Release
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  tag-release:
+    if: |
+      github.event_name == 'pull_request' &&
+      github.event.action == 'closed' &&
+      github.event.pull_request.merged == true &&
+      contains(github.event.pull_request.labels.*.name, 'release')
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Get current date
+        id: date
+        run: echo "::set-output name=date::$(date --rfc-3339=date)"
+
+      - name: Checkout branch "master"
+        uses: actions/checkout@v2
+        with:
+          ref: 'master'
+
+      - name: Tag Release
+        uses: tvdias/github-tagger@v0.0.2
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          tag: server-${{ steps.date.outputs.date }}

.gitignore

@@ -7,6 +7,7 @@
 /private
 /index.html
 /shields.env
+badge-maker/package-lock.json
 
 # Folder view configuration files
 .DS_Store
@@ -16,6 +17,9 @@ Desktop.ini
 ._*
 Thumbs.db
 
+# Visual Studio Code User Settings
+.vscode/settings.json
+
 # eclipse
 .project
 .settings
@@ -91,3 +95,24 @@ 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/
+
+# Rendered API docs
+/api-docs/
+
+# Flamebearer
+flamegraph.html

.gitpod.yml

@@ -0,0 +1,27 @@
+ports:
+  - port: 8080
+    onOpen: open-preview
+tasks:
+  - init: npm ci && npm run build
+    command: node server 8080 0.0.0.0
+github:
+  prebuilds:
+    # enable for the master/default branch (defaults to true)
+    master: true
+    # enable for all branches in this repo (defaults to false)
+    branches: false
+    # enable for pull requests coming from this repo (defaults to true)
+    pullRequests: true
+    # enable for pull requests coming from forks (defaults to false)
+    pullRequestsFromForks: true
+    # add a check to pull requests (defaults to true)
+    addCheck: true
+    # add a "Review in Gitpod" button as a comment to pull requests (defaults to false)
+    addComment: false
+    # add a "Review in Gitpod" button to the pull request's description (defaults to false)
+    addBadge: false
+    # add a label once the prebuild is ready to pull requests (defaults to false)
+    addLabel: false
+vscode:
+  extensions:
+    - esbenp.prettier-vscode@1.7.0:EbyqFvwe32qQBptkOgfQpQ==

.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

.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,13 +1,27 @@
 {
   "reporter": ["lcov"],
   "all": true,
+  "silent": true,
+  "clean": false,
   "exclude": [
     "**/*.spec.js",
     "**/*.integration.js",
+    "**/test-helpers.js",
+    "**/*-test-helpers.js",
+    "**/*-fixtures.js",
+    "**/mocha-*.js",
+    "**/*.test-d.ts",
+    "dangerfile.js",
+    "gatsby-*.js",
+    "core/service-test-runner",
+    "core/got-test-client.js",
     "services/**/*.tester.js",
+    "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
+/api-docs
 /build
+/public
 /coverage
-**/*.md
 private/*.json
+/.nyc_output
+analytics.json
+supported-features.json
+service-definitions.yml

.prettierrc.yml

@@ -1,4 +1,5 @@
 semi: false
 singleQuote: true
-trailingComma: es5
 bracketSpacing: true
+endOfLine: lf
+arrowParens: avoid

.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["esbenp.prettier-vscode", "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"
+    }
+  ]
+}

CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+Note: this changelog is for the shields.io server. The changelog for the badge-maker NPM package is at https://github.com/badges/shields/blob/master/badge-maker/CHANGELOG.md
+
+---
+
+## server-2021-06-01
+
+- Changed creating badges to open a new Window/Tab [#6536](https://github.com/badges/shields/issues/6536)
+- Make for-the-badge letter spacing more predictable, and rewrite layout logic [#5754](https://github.com/badges/shields/issues/5754)
+- deprecate DockerBuild service [#6529](https://github.com/badges/shields/issues/6529)
+- Remove rate limiting functionality [#6513](https://github.com/badges/shields/issues/6513)
+- [GitHub] Move to 'funding' category [#5846](https://github.com/badges/shields/issues/5846)
+- Add GitHub discussions total badge [GithubTotalDiscussions] [#6472](https://github.com/badges/shields/issues/6472)
+- Add optional query parameter (include_prereleases) to [GemVersion] [#6451](https://github.com/badges/shields/issues/6451)
+- Add [PingPong] Service [#6327](https://github.com/badges/shields/issues/6327)
+- Dependency updates
+
+## server-2021-05-01
+
+- Add setting which allows setting a timeout on HTTP requests
+  This is configured with the new `REQUEST_TIMEOUT_SECONDS` setting. If a request takes longer
+  than this number of seconds a `408 Request Timeout` response will be returned.
+- Deprecate [Bintray] service [#6423](https://github.com/badges/shields/issues/6423)
+- Support git hash in [nexus] SNAPSHOT version [#6369](https://github.com/badges/shields/issues/6369)
+- Replace 4183C4 with blue [#6366](https://github.com/badges/shields/issues/6366)
+- [Youtube] Added channel view count and subscriber count badges [#6333](https://github.com/badges/shields/issues/6333)
+- Fix Netlify badge by adding new color schema [#6340](https://github.com/badges/shields/issues/6340)
+- [REUSE] Add service badges [#6330](https://github.com/badges/shields/issues/6330)
+- Dependency updates
+
+## server-2021-04-01
+
+- Use NPM packages to provide fonts instead of Google Fonts [#6274](https://github.com/badges/shields/issues/6274)
+- Prevent duplication of parameters in badge examples [#6272](https://github.com/badges/shields/issues/6272)
+- Add docs for all types of releases [#6210](https://github.com/badges/shields/issues/6210)
+- refresh self-hosting docs [#6273](https://github.com/badges/shields/issues/6273)
+- allow missing 'goal' key in [liberapay] badges [#6258](https://github.com/badges/shields/issues/6258)
+- use got to push influx metrics [#6257](https://github.com/badges/shields/issues/6257)
+- Dependency updates
+
+## server-2021-03-01
+
+- ensure redirect target path is correctly encoded [#6229](https://github.com/badges/shields/issues/6229)
+- [SecurityHeaders] Added a possibility for no follow redirects [#6212](https://github.com/badges/shields/issues/6212)
+- catch URL parse error in [endpoint] badge [#6214](https://github.com/badges/shields/issues/6214)
+- [Homebrew] Add homebrew downloads badge [#6209](https://github.com/badges/shields/issues/6209)
+- update [pkgreview] url [#6189](https://github.com/badges/shields/issues/6189)
+- Make [Twitch] a social badge [#6183](https://github.com/badges/shields/issues/6183)
+- update [flathub] error handling [#6185](https://github.com/badges/shields/issues/6185)
+- Add [Testspace] badges [#6162](https://github.com/badges/shields/issues/6162)
+- Dependency updates
+
+## server-2021-02-01
+
+- Docs.rs badge (#6098)
+- Fix feedz service in case the package page gets paginated (#6101)
+- [Bitbucket] Server Adding Auth Tokens and Resolving Pull Request api … (#6076)
+- Dependency updates
+
+## server-2021-01-18
+
+- Gotta start somewhere

CODE_OF_CONDUCT.md

@@ -0,0 +1,129 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+![](https://img.shields.io/badge/conduct-%40shields.io-blue) or directly to [@calebcartwright](https://github.com/calebcartwright) ![](https://img.shields.io/badge/caleb-%40shields.io-blue) or [@paulmelnikow](https://github.com/paulmelnikow) ![](https://img.shields.io/badge/paul-%40shields.io-blue)
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

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
 
@@ -27,10 +24,20 @@ maybe you'd like to open a pull request to address one of them:
 
 You can help by improving the project's usage and developer instructions.
 
+Tutorials are in [/doc](https://github.com/badges/shields/tree/master/doc):
+
 - When you read the documentation, you can fix mistakes and add your own thoughts.
 - When your pull request follows the documentation but the practice changed,
   consider pointing this out and change the documentation for the next person.
 
+API documentation is at [contributing.shields.io](https://contributing.shields.io/):
+
+- This documentation is generated by annotating the code with
+  [JSDoc](https://jsdoc.app/about-getting-started.html) comments.
+  [Example](https://github.com/badges/shields/blob/b3be4d94d5ef570b8daccfd088c343a958988843/core/base-service/base-json.js#L26-L41)
+- Adding a JSDoc comment to some existing code is a great first contribution
+  and a good way to familiarize yourself with the codebase
+
 ### Helping others
 
 You can help with code review, which reduces bugs, and over time has a
@@ -38,19 +45,21 @@ 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].
 
-You can monitor [issues][] and the [chat room][], and help other people who
-have questions about contributing to Shields, or using it for their projects.
+You can monitor [issues][], [discussions][] and the [chat room][], and help
+other people who 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
+[discussions]: https://github.com/badges/shields/discussions
 [chat room]: https://discordapp.com/invite/HjJCwm5
 [maintainers]: https://github.com/badges/shields#project-leaders
 
@@ -72,53 +81,47 @@ 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:
 
 1. If you're new to the project, a good place to start is the [tutorial][].
-2. If you need help getting started or implementing a change, [open an issue][]
+2. If you need help getting started or implementing a change, [start a discussion][discussions]
    with your question. We promise it's okay to do that. If there is already an
-   issue open for the feature you're working on, you can post there.
+   issue open for the feature you're working on, you can post there directly.
 3. You can also join the [chat room][] and ask your question there.
 
 [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*
+  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_
   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 and links should be _turned off by
+  default_.
+- Badges should not obtain data from undocumented or reverse-engineered API endpoints.
+- Badges should not obtain data by scraping web pages - these are likely to break frequently.
+  Whereas API publishers are incentivised to maintain a stable platform for their users,
+  authors of web pages have no such incentive.
+- Badges may require users to specify a token in the badge URL as long it is scoped only to
+  fetching information and doesn't expose any sensitive information. Generating a token with the
+  correct scope must be clearly documented.
 
+## Badge URLs
 
-Badge URLs
-----------
+- The format of new badges should be of the form `/SERVICE/NOUN/PARAMETERS`.
+- There is further documentation on this in [badge-urls](https://github.com/badges/shields/blob/master/doc/badge-urls.md)
 
-- The format of new badges should be of the form
-  `/SERVICE/NOUN/PARAMETERS/QUALIFIERS.format`. For instance,
-  `/gitter/room/nwjs/nw.js.svg`. The vendor is gitter, the
-  badge is for rooms, the parameter is nwjs/nw.js, and the format is svg.
-- For services which require a hostname, the badge should be of the form
-  `/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
@@ -128,13 +131,7 @@ Prettier before a commit by default.
 
 ### Tests
 
-When adding or changing a service [please write tests][service-tests].
-
-When opening a pull request, include your service name in brackets in the pull
-request title. That way, those service tests will run in CI.
-
-e.g. **[Travis] Fix timeout issues**
-
+When adding or changing a service [please write tests][service-tests], and ensure the [title of your Pull Requests follows the required conventions](#running-service-tests-in-pull-requests) to ensure your tests are executed.
 When changing other code, please add unit tests.
 
 To run the integration tests, you must have redis installed and in your PATH.
@@ -145,21 +142,40 @@ 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 have [documentation for logo usage](doc/logos.md) which includes [contribution guidance](doc/logos.md#contributing-logos)
 
-We support a wide range of logos via [SimpleIcons][] and encourage you to [contribute logos to that project][simple-icons github].
+## Pull Requests
 
-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.
+All code changes are incorporated via pull requests, and pull requests are always squashed into a single commit on merging. Therefore there's no requirement to squash commits within your PR, but feel free to squash or restructure the commits on your PR branch if you think it will be helpful. PRs with well structured commits are always easier to review!
 
-Please minimize checked-in SVG files through [SVGO][]. You can use [svgomg][].
+Because all changes are pulled into the main branch via squash merges from PRs, we do **not** support overwriting any aspects of the git history once it hits our main branch. Notably this means we do not support amending commit messages, nor adjusting commit author information once merged.
 
-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+
+Accordingly, it is the responsibility of contributors to review this type of information and adjust as needed before marking PRs as ready for review and merging.
 
-[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/
+You can review and modify your local [git configuration][git-config] via `git config`, and also find more information about amending your commit messages [here][amending-commits].
+
+[git-config]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration
+[amending-commits]: https://docs.github.com/en/github/committing-changes-to-your-project/changing-a-commit-message#rewriting-the-most-recent-commit-message
+
+### Running service tests in pull requests
+
+The affected service names must be included in square brackets in the pull request title so that the CI engine will run those service tests. When a pull request affects multiple services, they should be separated with spaces. The test runner is case-insensitive, so they should be capitalized for readability.
+
+For example:
+
+- **[Travis] Fix timeout issues**
+- **[Travis Sonar] Support user token authentication**
+- **Add tests for [CRAN] and [CPAN]**
+
+Note that many services are part of a "family" of related services. Depending on the changes in your PR you may need to run the tests for just a single service, or for _all_ the services within a family.
+
+For example, a PR title of **[GitHubForks] Foo** will only run the service tests specifically for the GitHub Forks badge, whereas a title of **[GitHub] Foo** will run the service tests for all of the GitHub badges.
+
+In the rare case when it's necessary to see the output of a full service-test
+run in a PR (all 2,000+ tests), include `[*****]` in the title. Unless all the tests pass, the build
+will fail, so likely it will be necessary to remove it and re-run the tests
+before merging.

Dockerfile

@@ -1,22 +1,24 @@
-FROM node:8.9.4-alpine
-
-RUN apk add --no-cache gettext imagemagick librsvg ttf-dejavu git
-ENV FONT_PATH /usr/share/fonts/ttf-dejavu/DejaVuSans.ttf
+FROM node:12-alpine
 
 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 badge-maker package.json and CLI script in place, `npm ci` will fail.
+COPY badge-maker /usr/src/app/badge-maker/
+
+# We need dev deps to build the front end. We don't need Cypress, though.
+RUN NODE_ENV=development CYPRESS_INSTALL_BINARY=0 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

@@ -1,89 +0,0 @@
-SHELL:=/bin/bash
-
-SERVER_TMP=${TMPDIR}shields-server-deploy
-FRONTEND_TMP=${TMPDIR}shields-frontend-deploy
-
-# This branch is reserved for the deploy process and should not be used for
-# development. The deploy script will clobber it. To avoid accidentally
-# pushing secrets to GitHub, this branch is configured to reject pushes.
-WORKING_BRANCH=server-deploy-working-branch
-
-all: website favicon test
-
-favicon:
-	# This isn't working right now. See https://github.com/badges/shields/issues/1788
-	node lib/badge-cli.js '' '' '#bada55' .png > favicon.png
-
-website:
-	LONG_CACHE=false npm run build
-
-deploy: deploy-s0 deploy-s1 deploy-s2 clean-server-deploy deploy-gh-pages deploy-gh-pages-clean
-
-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
-	# Ship a copy of the front end to each server for debugging.
-	# https://github.com/badges/shields/issues/1220
-	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/
-	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
-	cp Verdana.ttf ${SERVER_TMP}
-	git -C ${SERVER_TMP} add -f private/secret.json Verdana.ttf
-	git -C ${SERVER_TMP} commit --no-verify -m '[DEPLOY] MUST NOT BE ON GITHUB'
-
-clean-server-deploy:
-	rm -rf ${SERVER_TMP}
-	git worktree prune
-
-push-s0:
-	git push -f s0 ${WORKING_BRANCH}:master
-
-push-s1:
-	git push -f s1 ${WORKING_BRANCH}:master
-
-push-s2:
-	git push -f s2 ${WORKING_BRANCH}:master
-
-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 \
-		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}
-	echo shields.io > ${FRONTEND_TMP}/CNAME
-	touch ${FRONTEND_TMP}/.nojekyll
-	git -C ${FRONTEND_TMP} add .
-	git -C ${FRONTEND_TMP} commit --no-verify -m '[DEPLOY] Add built site'
-	git push -f origin gh-pages
-
-deploy-gh-pages-clean:
-	rm -rf ${FRONTEND_TMP}
-	git worktree prune
-
-deploy-heroku:
-	git add -f Verdana.ttf 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 favicon 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

Procfile

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

README.md

@@ -1,26 +1,32 @@
 <p align="center">
-    <img src="https://rawgit.com/badges/shields/master/static/logo.svg"
+    <img src="https://raw.githubusercontent.com/badges/shields/master/readme-logo.svg?sanitize=true"
         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" /></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" /></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" /></a>
+    <a href="https://github.com/badges/shields/pulse" alt="Activity">
+        <img src="https://img.shields.io/github/commit-activity/m/badges/shields" /></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>
-    <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>
+        <img src="https://img.shields.io/circleci/project/github/badges/shields/master" 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?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"
+            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?logo=lgtm&logoWidth=18"
+        <img src="https://img.shields.io/lgtm/alerts/g/badges/shields"
             alt="Total alerts"/></a>
     <a href="https://discord.gg/HjJCwm5">
-        <img src="https://img.shields.io/discord/308323056592486420.svg?logo=discord"
+        <img src="https://img.shields.io/discord/308323056592486420?logo=discord"
             alt="chat on Discord"></a>
     <a href="https://twitter.com/intent/follow?screen_name=shields_io">
-        <img src="https://img.shields.io/twitter/follow/shields_io.svg?style=social&logo=twitter"
+        <img src="https://img.shields.io/twitter/follow/shields_io?style=social&logo=twitter"
             alt="follow on Twitter"></a>
 </p>
 
@@ -29,40 +35,53 @@ and legible badges in SVG and raster format, which can easily be included in
 GitHub readmes or any other web page. The service supports dozens of
 continuous integration services, package registries, distributions, app
 stores, social networks, code coverage services, and code analysis services.
-Every month it serves over 470 million images.
+Every month it serves over 770 million images and is used by some of the
+world's most popular open-source projects, [VS Code][vscode], [Vue.js][vue]
+and [Bootstrap][bootstrap] to name a few.
 
-In addition to hosting the shields.io frontend and server code, this monorepo
-hosts an [NPM library for generating badges][gh-badges], and the badge design
-specification.
+[vscode]: https://github.com/Microsoft/vscode
+[vue]: https://github.com/vuejs/vue
+[bootstrap]: https://github.com/twbs/bootstrap
+
+This repo hosts:
+
+- The [Shields.io][shields.io] frontend and server code
+- An [NPM library for generating badges][badge-maker]
+  - [documentation][badge-maker-docs]
+  - [changelog][badge-maker-changelog]
+- The [badge design specification][badge-spec]
 
 [shields.io]: https://shields.io/
-[gh-badges]: https://www.npmjs.com/package/gh-badges
+[badge-maker]: https://www.npmjs.com/package/badge-maker
+[badge-spec]: https://github.com/badges/shields/tree/master/spec
+[badge-maker-docs]: https://github.com/badges/shields/tree/master/badge-maker/README.md
+[badge-maker-changelog]: https://github.com/badges/shields/tree/master/badge-maker/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)
+- stable release version: ![version](https://img.shields.io/badge/version-1.2.3-blue)
+- package manager release: ![gem](https://img.shields.io/badge/gem-2.2.0-blue)
+- status of third-party dependencies: ![dependencies](https://img.shields.io/badge/dependencies-out%20of%20date-orange)
+- static code analysis grade: ![codacy](https://img.shields.io/badge/codacy-B-green)
+- [SemVer](https://semver.org/) version observance: ![semver](https://img.shields.io/badge/semver-2.0.0-blue)
+- amount of [Liberapay](https://liberapay.com/) donations per week: ![receives](https://img.shields.io/badge/receives-2.00%20USD%2Fweek-yellow)
+- Python package downloads: ![downloads](https://img.shields.io/badge/downloads-13k%2Fmonth-brightgreen)
+- Chrome Web Store extension rating: ![rating](https://img.shields.io/badge/rating-★★★★☆-brightgreen)
+- [Uptime Robot](https://uptimerobot.com) percentage: ![uptime](https://img.shields.io/badge/uptime-100%25-brightgreen)
 
 [Make your own badges!][custom badges]
-(Quick example: `https://img.shields.io/badge/left-right-f39f37.svg`)
-
-Browse a [complete list of badges][shields.io].
+(Quick example: `https://img.shields.io/badge/left-right-f39f37`)
 
 [custom badges]: http://shields.io/#your-badge
 
+### Quickstart
 
-Contributing
-------------
+Browse a [complete list of badges][shields.io] and locate a particular badge by using the search bar or by browsing the categories. Click on the badge to fill in required data elements for that badge type (like your username or repo) and optionally customize (label, colors etc.). And it's ready for use!
+
+Use the button at the bottom to copy your badge url or snippet, which can then be added to places like your GitHub readme files or other web pages.
+
+## Contributing
 
 Shields is a community project. We invite your participation through issues
 and pull requests! You can peruse the [contributing guidelines][contributing].
@@ -70,87 +89,74 @@ and pull requests! You can peruse the [contributing guidelines][contributing].
 When adding or changing a service [please add tests][service-tests].
 
 This project has quite a backlog of suggestions! If you're new to the project,
-maybe you'd like to open a pull request to address one of them:
-
-[![GitHub issues by-label](https://img.shields.io/github/issues/badges/shields/good%20first%20issue.svg)](https://github.com/badges/shields/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+maybe you'd like to open a pull request to address one of them.
 
 You can read a [tutorial on how to add a badge][tutorial].
 
+[![GitHub issues by-label](https://img.shields.io/github/issues/badges/shields/good%20first%20issue)](https://github.com/badges/shields/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+
 [service-tests]: https://github.com/badges/shields/blob/master/doc/service-tests.md
 [tutorial]: doc/TUTORIAL.md
 [contributing]: CONTRIBUTING.md
 
+## Development
 
-Using the badge library
------------------------
-
-```sh
-npm install -g gh-badges
-badge build passed :green .png > mybadge.png
-```
-
-```js
-const { BadgeFactory } = require('gh-badges')
-
-const bf = new BadgeFactory({ fontPath: '/path/to/Verdana.ttf' })
-
-const format = {
-  text: ['build', 'passed'],
-  colorscheme: 'green',
-  template: 'flat',
-}
-
-const svg = bf.create(format)
-```
-
-View the [documentation for gh-badges][gh-badges doc].
-
-[![npm version](http://img.shields.io/npm/v/gh-badges.svg)](https://npmjs.org/package/gh-badges)
-
-[gh-badges doc]: https://github.com/badges/shields/blob/master/doc/gh-badges.md
-
-
-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.
+1. Install Node 12 or later. You can use the [package manager][] of your choice.
+   Tests need to pass in Node 12 and 14.
 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`.
+It also works with full URLs like
+`npm run badge -- https://img.shields.io/npm/v/nock`.
+
+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][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
-`SNAPSHOT_DRY=1 npm run test:js:server` to preview changes to the saved
-snapshots, and `SNAPSHOT_UPDATE=1 npm run test:js:server` to update them.
+`SNAPSHOT_DRY=1 npm run test:package` to preview changes to the saved
+snapshots, and `SNAPSHOT_UPDATE=1 npm run test:package` to update them.
 
 The server can be configured to use [Sentry][] ([configuration][sentry configuration]) and [Prometheus][] ([configuration][prometheus configuration]).
 
-[package manager]: https://nodejs.org/en/download/package-manager/
-[snapshot tests]: https://glebbahmutov.com/blog/snapshot-testing/
-[Prometheus]: https://prometheus.io/
-[prometheus configuration]: doc/self-hosting.md#prometheus
-[Sentry]: https://sentry.io/
-[sentry configuration]: doc/self-hosting.md#sentry
+Daily tests, including a full run of the service tests and overall code coverage, are run via [badges/daily-tests][daily-tests].
 
-Hosting your own server
------------------------
+[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 configuration]: doc/self-hosting.md#prometheus
+[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
 
 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
@@ -177,35 +183,39 @@ 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)
+- [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)
+- [calebcartwright](https://github.com/calebcartwright)
+- [chris48s](https://github.com/chris48s)
+- [paulmelnikow](https://github.com/paulmelnikow)
+- [PyvesB](https://github.com/PyvesB)
 
+Alumni:
 
-Related projects
-----------------
+- [espadrine](https://github.com/espadrine)
+- [olivierlacan](https://github.com/olivierlacan)
 
-- [badgerbadgerbadger gem][gem]
+## Related projects
+
+- [poser PHP library][poser]
 - [pybadges python library][pybadges]
 
-[gem]: https://github.com/badges/badgerbadgerbadger
+[poser]: https://github.com/badges/poser
 [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.
@@ -213,32 +223,6 @@ domain unless specified otherwise.
 The assets in `logo/` are trademarks of their respective companies and are
 under their terms and license.
 
-## Contributors
-
-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)]
-
-<a href="https://opencollective.com/shields/sponsor/0/website" target="_blank"><img src="https://opencollective.com/shields/sponsor/0/avatar.svg"></a>
-<a href="https://opencollective.com/shields/sponsor/1/website" target="_blank"><img src="https://opencollective.com/shields/sponsor/1/avatar.svg"></a>
-<a href="https://opencollective.com/shields/sponsor/2/website" target="_blank"><img src="https://opencollective.com/shields/sponsor/2/avatar.svg"></a>
-<a href="https://opencollective.com/shields/sponsor/3/website" target="_blank"><img src="https://opencollective.com/shields/sponsor/3/avatar.svg"></a>
-<a href="https://opencollective.com/shields/sponsor/4/website" target="_blank"><img src="https://opencollective.com/shields/sponsor/4/avatar.svg"></a>
-<a href="https://opencollective.com/shields/sponsor/5/website" target="_blank"><img src="https://opencollective.com/shields/sponsor/5/avatar.svg"></a>
-<a href="https://opencollective.com/shields/sponsor/6/website" target="_blank"><img src="https://opencollective.com/shields/sponsor/6/avatar.svg"></a>
-<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>
-
+## Community
 
+Thanks to the people and companies who donate money, services or time to keep the project running. [https://shields.io/community](https://shields.io/community)

SECURITY.md

@@ -0,0 +1,25 @@
+# Security Policy
+
+## Supported Projects
+
+Please follow this guidance when reporting security issues affecting:
+
+- [Shields.io](https://shields.io)
+- [Raster.shields.io](https://raster.shields.io)
+- Self-hosted Shields instances
+- The [svg-to-image-proxy](https://www.npmjs.com/package/svg-to-image-proxy) NPM package
+- The [badge-maker](https://www.npmjs.com/package/badge-maker) NPM package
+
+The [gh-badges](https://www.npmjs.com/package/gh-badges) NPM package is now deprecated and will no longer receive fixes for bugs or security issues.
+
+## Reporting a Vulnerability
+
+If you find a security vulnerability affecting any of our supported projects, please email [security@shields.io](mailto:security@shields.io), rather than opening a public issue on GitHub. After receiving the initial report, we will endeavor to keep you informed of the progress towards a fix and full announcement. We may ask you for additional information. You are also welcome to propose a patch or solution.
+
+Report security bugs in third-party modules to the person or team maintaining the module.
+
+## Coordinated Disclosure
+
+We aim to patch confirmed vulnerabilities within 90 days or less, disclosing the details of those vulnerabilities when a patch is published. We ask that you refrain from sharing your report with others while we work on our patch.
+
+We may want to coordinate an advisory with you to be published simultaneously with the patch, but you are also welcome to self-disclose after 90 days if you prefer. We will never publish information about you or our communications with you without your permission.

app.json

@@ -1,19 +1,36 @@
 {
   "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"
+    "CYPRESS_INSTALL_BINARY": {
+      "description": "Disable the cypress binary installation",
+      "value": "0",
+      "required": false
+    },
+    "HUSKY_SKIP_INSTALL": {
+      "description": "Skip the husky git hook setup",
+      "value": "1",
+      "required": 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
+    },
+    "TWITCH_CLIENT_ID": {
+      "description": "Configure the client id to be used for the Twitch service.",
+      "required": false
+    },
+    "TWITCH_CLIENT_SECRET": {
+      "description": "Configure the client secret to be used for the Twitch service.",
+      "required": false
     }
   },
   "formation": {

badge-maker/.npmignore

@@ -0,0 +1,3 @@
+lib/make-badge-test-helpers.js
+lib/**/*.spec.js
+index.test-d.ts

badge-maker/CHANGELOG.md

@@ -0,0 +1,272 @@
+# Changelog
+
+## 3.3.0
+
+- Readability improvements: a dark font color is automatically used when the badge's background is too light. For example: ![](https://img.shields.io/badge/hello-world-white)
+- Better CSS color compliance: thanks to a switch from _is-css-color_ to _[css-color-converter](https://www.npmjs.com/package/css-color-converter)_, you can use a wider range of color formats from the latest CSS specification, for example `rgb(0 255 0)`
+- Less dependencies: _badge-maker_ no longer depends on _camelcase_
+
+## 3.2.0
+
+- Accessibility improvements: Help users of assistive technologies to read the badges when used inline
+
+## 3.1.0
+
+- Add TypeScript definitions
+
+## 3.0.1
+
+- Fix missing dependency
+
+## 3.0.0
+
+### Breaking Changes
+
+- Dropped support for node < 10
+- Package name has changed to `badge-maker` and moved to https://www.npmjs.com/package/badge-maker
+- `BadgeFactory` class is removed and replaced by `makeBadge()` function.
+- Deprecated parameters have been removed. In version 2.2.0 the `colorA`, `colorB` and `colorscheme` params were deprecated. In version 3.0.0 these have been removed.
+- Only SVG output format is now provided. JSON format has been dropped and the `format` key has been removed.
+- The `text` array has been replaced by `label` and `message` keys.
+- The `template` key has been renamed `style`.
+  To upgrade from v2.1.1, change your code from:
+  ```js
+  const { BadgeFactory } = require('gh-badges')
+  const bf = new BadgeFactory()
+  const svg = bf.create({
+    text: ['build', 'passed'],
+    format: 'svg',
+    template: 'flat-square',
+  })
+  ```
+  to:
+  ```js
+  const { makeBadge } = require('badge-maker')
+  const svg = makeBadge({
+    label: 'build',
+    message: 'passed',
+    style: 'flat-square',
+  })
+  ```
+- `ValidationError` had been added and inputs are now validated. In previous releases, invalid inputs would be discarded and replaced with defaults. For example, in 2.2.1
+  ```js
+  const { BadgeFactory } = require('gh-badges')
+  const bf = new BadgeFactory()
+  const svg = bf.create({
+    text: ['build', 'passed'],
+    template: 'some invalid value',
+  })
+  ```
+  would generate an SVG badge. In version >=3
+  ```js
+  const { makeBadge } = require('badge-maker')
+  const svg = makeBadge({
+    label: 'build',
+    message: 'passed',
+    style: 'some invalid value',
+  })
+  ```
+  will throw a `ValidationError`.
+- Raster support has been removed from the CLI. It will now only output SVG. On the console, the output of `badge` can be piped to a utility like [imagemagick](https://imagemagick.org/script/command-line-processing.php). If you were previously using
+  ```sh
+  badge build passed :green .gif
+  ```
+  this could be replaced by
+  ```sh
+  badge build passed :green | magick svg:- gif:-
+  ```
+
+### Security
+
+- Removed dependency on doT library which has known vulnerabilities.
+
+## 2.2.1 - 2019-05-30
+
+### Fixes
+
+- Escape logos to prevent XSS vulnerability
+- Update docblock for BadgeFactory.create()
+
+## 2.2.0 - 2019-05-29
+
+### Deprecations
+
+- `labelColor` and `color` are now the recommended attribute names for label color and message color.
+
+  - `colorA` (now an alias for `labelColor`),
+  - `colorB` (now an alias for `color`) and
+  - `colorscheme` (now an alias for `color`)
+
+  are now deprecated and will be removed in some future release.
+
+### New Features
+
+- Semantic color aliases. Add support for:
+  - ![success](https://img.shields.io/badge/success-success.svg)
+  - ![important](https://img.shields.io/badge/important-important.svg)
+  - ![critical](https://img.shields.io/badge/critical-critical.svg)
+  - ![informational](https://img.shields.io/badge/informational-informational.svg)
+  - ![inactive](https://img.shields.io/badge/inactive-inactive.svg)
+- Add directory field to package.json (to help tools find this package in the repo)
+
+### Bug Fixes
+
+- Prevent bad letter spacing when whitespace surrounds badge text
+
+### Dependencies
+
+- Bump anafanafo
+- Use caret instead of tilde for dependencies
+
+### Internals
+
+- Generate JSON badges without using a template
+- Refactoring
+- Testing improvements
+
+### Node support
+
+- Declare support for all currently maintained Node versions
+- Explicitly test on all supported versions
+
+## 2.1.0 - 2018-11-18
+
+gh-badges v2.1.0 implements a new text width measurer which uses a lookup table, removing the dependency
+on PDFKit. It is no longer necessary to provide a local copy of Verdana for accurate text width computation.
+
+As such, the `fontPath` and `precomputeWidths` parameters are now deprecated. The recommended call to create an instance of `BadgeFactory` is now
+
+```js
+const bf = new BadgeFactory()
+```
+
+For backwards compatibility you can still construct an instance of `BadgeFactory` with a call like
+
+```js
+const bf = new BadgeFactory({
+  fontPath: '/path/to/Verdana.ttf',
+  precomputeWidths: true,
+})
+```
+
+However, the function will issue a warning.
+
+To clear the warning, change the code to:
+
+```js
+const bf = new BadgeFactory()
+```
+
+These arguments will be removed in a future release.
+
+To upgrade from v1.3.0, change your code from:
+
+```js
+const badge = require('gh-badges')
+
+const format = {
+  text: ['build', 'passed'],
+  colorscheme: 'green',
+  template: 'flat',
+}
+
+badge.loadFont('/path/to/Verdana.ttf', err => {
+  badge(format, (svg, err) => {
+    // svg is a string containing your badge
+  })
+})
+```
+
+to:
+
+```js
+const { BadgeFactory } = require('gh-badges')
+
+const bf = new BadgeFactory()
+
+const format = {
+  text: ['build', 'passed'],
+  colorscheme: 'green',
+  template: 'flat',
+}
+
+const svg = bf.create(format)
+```
+
+### Other changes in this release:
+
+- Remove unnecessary dependencies
+- Documentation improvements
+
+## 2.0.0 - 2018-11-09
+
+gh-badges v2.0.0 declares a new public interface which is synchronous.
+If your version 1.3.0 code looked like this:
+
+```js
+const badge = require('gh-badges')
+
+const format = {
+  text: ['build', 'passed'],
+  colorscheme: 'green',
+  template: 'flat',
+}
+
+badge.loadFont('/path/to/Verdana.ttf', err => {
+  badge(format, (svg, err) => {
+    // svg is a string containing your badge
+  })
+})
+```
+
+To upgrade to version 2.0.0, refactor you code to:
+
+```js
+const { BadgeFactory } = require('gh-badges')
+
+const bf = new BadgeFactory({ fontPath: '/path/to/Verdana.ttf' })
+
+const format = {
+  text: ['build', 'passed'],
+  colorscheme: 'green',
+  template: 'flat',
+}
+
+const svg = bf.create(format)
+```
+
+You can generate badges without a copy of Verdana, however font width computation is approximate and badges may be distorted.
+
+```js
+const bf = new BadgeFactory({ fallbackFontPath: 'Helvetica' })
+```
+
+## 1.3.0 - 2016-09-07
+
+Add support for optionally specifying the path to `Verdana.ttf`. In earlier versions, the file needed to be in the directory containing Shields.
+
+Without font path:
+
+```js
+const badge = require('gh-badges')
+
+badge({ text: ['build', 'passed'], colorscheme: 'green' }, (svg, err) => {
+  // svg is a string containing your badge
+})
+```
+
+With font path:
+
+```js
+const badge = require('gh-badges')
+
+// Optional step, to have accurate text width computation.
+badge.loadFont('/path/to/Verdana.ttf', err => {
+  badge(
+    { text: ['build', 'passed'], colorscheme: 'green', template: 'flat' },
+    (svg, err) => {
+      // svg is a string containing your badge
+    }
+  )
+})
+```

badge-maker/LICENSE

@@ -0,0 +1,116 @@
+CC0 1.0 Universal
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator and
+subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for the
+purpose of contributing to a commons of creative, cultural and scientific
+works ("Commons") that the public can reliably and without fear of later
+claims of infringement build upon, modify, incorporate in other works, reuse
+and redistribute as freely as possible in any form whatsoever and for any
+purposes, including without limitation commercial purposes. These owners may
+contribute to the Commons to promote the ideal of a free culture and the
+further production of creative, cultural and scientific works, or to gain
+reputation or greater distribution for their Work in part through the use and
+efforts of others.
+
+For these and/or other purposes and motivations, and without any expectation
+of additional consideration or compensation, the person associating CC0 with a
+Work (the "Affirmer"), to the extent that he or she is an owner of Copyright
+and Related Rights in the Work, voluntarily elects to apply CC0 to the Work
+and publicly distribute the Work under its terms, with knowledge of his or her
+Copyright and Related Rights in the Work and the meaning and intended legal
+effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not limited
+to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display, communicate,
+  and translate a Work;
+
+  ii. moral rights retained by the original author(s) and/or performer(s);
+
+  iii. publicity and privacy rights pertaining to a person's image or likeness
+  depicted in a Work;
+
+  iv. rights protecting against unfair competition in regards to a Work,
+  subject to the limitations in paragraph 4(a), below;
+
+  v. rights protecting the extraction, dissemination, use and reuse of data in
+  a Work;
+
+  vi. database rights (such as those arising under Directive 96/9/EC of the
+  European Parliament and of the Council of 11 March 1996 on the legal
+  protection of databases, and under any national implementation thereof,
+  including any amended or successor version of such directive); and
+
+  vii. other similar, equivalent or corresponding rights throughout the world
+  based on applicable law or treaty, and any national implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention of,
+applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and
+unconditionally waives, abandons, and surrenders all of Affirmer's Copyright
+and Related Rights and associated claims and causes of action, whether now
+known or unknown (including existing as well as future claims and causes of
+action), in the Work (i) in all territories worldwide, (ii) for the maximum
+duration provided by applicable law or treaty (including future time
+extensions), (iii) in any current or future medium and for any number of
+copies, and (iv) for any purpose whatsoever, including without limitation
+commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes
+the Waiver for the benefit of each member of the public at large and to the
+detriment of Affirmer's heirs and successors, fully intending that such Waiver
+shall not be subject to revocation, rescission, cancellation, termination, or
+any other legal or equitable action to disrupt the quiet enjoyment of the Work
+by the public as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason be
+judged legally invalid or ineffective under applicable law, then the Waiver
+shall be preserved to the maximum extent permitted taking into account
+Affirmer's express Statement of Purpose. In addition, to the extent the Waiver
+is so judged Affirmer hereby grants to each affected person a royalty-free,
+non transferable, non sublicensable, non exclusive, irrevocable and
+unconditional license to exercise Affirmer's Copyright and Related Rights in
+the Work (i) in all territories worldwide, (ii) for the maximum duration
+provided by applicable law or treaty (including future time extensions), (iii)
+in any current or future medium and for any number of copies, and (iv) for any
+purpose whatsoever, including without limitation commercial, advertising or
+promotional purposes (the "License"). The License shall be deemed effective as
+of the date CC0 was applied by Affirmer to the Work. Should any part of the
+License for any reason be judged legally invalid or ineffective under
+applicable law, such partial invalidity or ineffectiveness shall not
+invalidate the remainder of the License, and in such case Affirmer hereby
+affirms that he or she will not (i) exercise any of his or her remaining
+Copyright and Related Rights in the Work or (ii) assert any associated claims
+and causes of action with respect to the Work, in either case contrary to
+Affirmer's express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+  a. No trademark or patent rights held by Affirmer are waived, abandoned,
+  surrendered, licensed or otherwise affected by this document.
+
+  b. Affirmer offers the Work as-is and makes no representations or warranties
+  of any kind concerning the Work, express, implied, statutory or otherwise,
+  including without limitation warranties of title, merchantability, fitness
+  for a particular purpose, non infringement, or the absence of latent or
+  other defects, accuracy, or the present or absence of errors, whether or not
+  discoverable, all to the greatest extent permissible under applicable law.
+
+  c. Affirmer disclaims responsibility for clearing rights of other persons
+  that may apply to the Work or any use thereof, including without limitation
+  any person's Copyright and Related Rights in the Work. Further, Affirmer
+  disclaims responsibility for obtaining any necessary consents, permissions
+  or other rights required for any use of the Work.
+
+  d. Affirmer understands and acknowledges that Creative Commons is not a
+  party to this document and has no duty or obligation with respect to this
+  CC0 or use of the Work.
+
+For more information, please see
+<http://creativecommons.org/publicdomain/zero/1.0/>

badge-maker/README.md

@@ -0,0 +1,142 @@
+# badge-maker
+
+[![npm version](https://img.shields.io/npm/v/badge-maker.svg)](https://npmjs.org/package/badge-maker)
+[![npm license](https://img.shields.io/npm/l/badge-maker.svg)](https://npmjs.org/package/badge-maker)
+[![npm type definitions](https://img.shields.io/npm/types/badge-maker)](https://npmjs.org/package/badge-maker)
+
+## Installation
+
+```sh
+npm install badge-maker
+```
+
+## Usage
+
+### On the console
+
+```sh
+npm install -g badge-maker
+badge build passed :green > mybadge.svg
+```
+
+### As a library
+
+With CommonJS in JavaScript,
+
+```js
+const { makeBadge, ValidationError } = require('badge-maker')
+```
+
+With ESM or TypeScript,
+
+```ts
+import { makeBadge, ValidationError } from 'badge-maker'
+```
+
+```js
+const format = {
+  label: 'build',
+  message: 'passed',
+  color: 'green',
+}
+
+const svg = makeBadge(format)
+console.log(svg) // <svg...
+
+try {
+  makeBadge({})
+} catch (e) {
+  console.log(e) // ValidationError: Field `message` is required
+}
+```
+
+### Node version support
+
+The latest version of badge-maker supports all currently maintained Node
+versions. See the [Node Release Schedule][].
+
+[node release schedule]: https://github.com/nodejs/Release#release-schedule
+
+## Format
+
+The format is the following:
+
+```js
+{
+  label: 'build',  // (Optional) Badge label
+  message: 'passed',  // (Required) Badge message
+  labelColor: '#555',  // (Optional) Label color
+  color: '#4c1',  // (Optional) Message color
+
+  // (Optional) One of: 'plastic', 'flat', 'flat-square', 'for-the-badge' or 'social'
+  // Each offers a different visual design.
+  style: 'flat',
+}
+```
+
+## Colors
+
+There are three ways to specify `color` and `labelColor`:
+
+1. One of the [Shields named colors](./lib/color.js):
+
+- ![][brightgreen]
+- ![][green]
+- ![][yellow]
+- ![][yellowgreen]
+- ![][orange]
+- ![][red]
+- ![][blue]
+- ![][grey] ![][gray] – the default `labelColor`
+- ![][lightgrey] ![][lightgray] – the default `color`
+
+- ![][success]
+- ![][important]
+- ![][critical]
+- ![][informational]
+- ![][inactive] – the default `color`
+
+2. A three- or six-character hex color, optionally prefixed with `#`:
+
+- ![][9cf]
+- ![][#007fff]
+- etc.
+
+3. [Any valid CSS color][css color], e.g.
+
+- `rgb(...)`, `rgba(...)`
+- `hsl(...)`, `hsla(...)`
+- ![][aqua] ![][fuchsia] ![][lightslategray] etc.
+
+[brightgreen]: https://img.shields.io/badge/brightgreen-brightgreen.svg
+[success]: https://img.shields.io/badge/success-success.svg
+[green]: https://img.shields.io/badge/green-green.svg
+[yellow]: https://img.shields.io/badge/yellow-yellow.svg
+[yellowgreen]: https://img.shields.io/badge/yellowgreen-yellowgreen.svg
+[orange]: https://img.shields.io/badge/orange-orange.svg
+[important]: https://img.shields.io/badge/important-important.svg
+[red]: https://img.shields.io/badge/red-red.svg
+[critical]: https://img.shields.io/badge/critical-critical.svg
+[blue]: https://img.shields.io/badge/blue-blue.svg
+[informational]: https://img.shields.io/badge/informational-informational.svg
+[grey]: https://img.shields.io/badge/grey-grey.svg
+[gray]: https://img.shields.io/badge/gray-gray.svg
+[lightgrey]: https://img.shields.io/badge/lightgrey-lightgrey.svg
+[lightgray]: https://img.shields.io/badge/lightgray-lightgray.svg
+[inactive]: https://img.shields.io/badge/inactive-inactive.svg
+[9cf]: https://img.shields.io/badge/9cf-9cf.svg
+[#007fff]: https://img.shields.io/badge/%23007fff-007fff.svg
+[aqua]: https://img.shields.io/badge/aqua-aqua.svg
+[fuchsia]: https://img.shields.io/badge/fuchsia-fuchsia.svg
+[lightslategray]: https://img.shields.io/badge/lightslategray-lightslategray.svg
+[css color]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value
+[css/svg color]: http://www.w3.org/TR/SVG/types.html#DataTypeColor
+
+## Raster Formats
+
+Conversion to raster formats is no longer directly supported. In javascript
+code, SVG badges can be converted to raster formats using a library like
+[gm](https://www.npmjs.com/package/gm). On the console, the output of `badge`
+can be piped to a utility like
+[imagemagick](https://imagemagick.org/script/command-line-processing.php)
+e.g: `badge build passed :green | magick svg:- gif:-`.

badge-maker/index.d.ts

@@ -0,0 +1,11 @@
+interface Format {
+  label?: string
+  message: string
+  labelColor?: string
+  color?: string
+  style?: 'plastic' | 'flat' | 'flat-square' | 'for-the-badge' | 'social'
+}
+
+export declare class ValidationError extends Error {}
+
+export declare function makeBadge(format: Format): string

badge-maker/index.test-d.ts

@@ -0,0 +1,35 @@
+import { expectType, expectError, expectAssignable } from 'tsd'
+import { makeBadge, ValidationError } from '.'
+
+expectError(makeBadge('string is invalid'))
+expectError(makeBadge({}))
+expectError(
+  makeBadge({
+    message: 'passed',
+    style: 'invalid style',
+  })
+)
+
+expectType<string>(
+  makeBadge({
+    message: 'passed',
+  })
+)
+expectType<string>(
+  makeBadge({
+    label: 'build',
+    message: 'passed',
+  })
+)
+expectType<string>(
+  makeBadge({
+    label: 'build',
+    message: 'passed',
+    labelColor: 'green',
+    color: 'red',
+    style: 'flat',
+  })
+)
+
+const error = new ValidationError()
+expectAssignable<Error>(error)

badge-maker/lib/badge-cli.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+'use strict'
+
+const { namedColors } = require('./color')
+const { makeBadge } = require('./index')
+
+if (process.argv.length < 4) {
+  console.log('Usage: badge label message [:color] [@style]')
+  console.log('Or:    badge label message color [labelColor] [@style]')
+  console.log()
+  console.log('  color, labelColor:')
+  console.log(`    one of ${Object.keys(namedColors).join(', ')}.`)
+  console.log('    #xxx (three hex digits)')
+  console.log('    #xxxxxx (six hex digits)')
+  console.log('    color (CSS color)')
+  console.log()
+  console.log('Eg: badge cactus grown :green @flat')
+  console.log()
+  process.exit()
+}
+
+// Find a format specifier.
+let style = ''
+for (let i = 4; i < process.argv.length; i++) {
+  if (process.argv[i][0] === '@') {
+    style = process.argv[i].slice(1)
+    process.argv.splice(i, 1)
+    continue
+  }
+}
+
+const label = process.argv[2]
+const message = process.argv[3]
+let color = process.argv[4] || ':green'
+const labelColor = process.argv[5]
+
+const badgeData = { label, message }
+if (style) {
+  badgeData.style = style
+}
+
+if (color[0] === ':') {
+  color = color.slice(1)
+  if (namedColors[color] == null) {
+    // Colorscheme not found.
+    console.error('Invalid color scheme.')
+    process.exit(1)
+  }
+  badgeData.color = color
+} else {
+  badgeData.color = color
+  if (labelColor) {
+    badgeData.labelColor = labelColor
+  }
+}
+
+;(() => {
+  try {
+    console.log(makeBadge(badgeData))
+  } catch (e) {
+    console.error(e)
+    process.exit(1)
+  }
+})()

badge-maker/lib/badge-cli.spec.js

@@ -0,0 +1,39 @@
+'use strict'
+
+const path = require('path')
+const isSvg = require('is-svg')
+const { spawn } = require('child-process-promise')
+const { expect, use } = require('chai')
+use(require('chai-string'))
+use(require('sinon-chai'))
+
+function runCli(args) {
+  return spawn('node', [path.join(__dirname, 'badge-cli.js'), ...args], {
+    capture: ['stdout'],
+  })
+}
+
+describe('The CLI', function () {
+  it('should provide a help message', async function () {
+    const { stdout } = await runCli([])
+    expect(stdout).to.startWith('Usage')
+  })
+
+  it('should produce default badges', async function () {
+    const { stdout } = await runCli(['cactus', 'grown'])
+    expect(stdout)
+      .to.satisfy(isSvg)
+      .and.to.include('cactus')
+      .and.to.include('grown')
+  })
+
+  it('should produce colorschemed badges', async function () {
+    const { stdout } = await runCli(['cactus', 'grown', ':green'])
+    expect(stdout).to.satisfy(isSvg)
+  })
+
+  it('should produce right-color badges', async function () {
+    const { stdout } = await runCli(['cactus', 'grown', '#abcdef'])
+    expect(stdout).to.satisfy(isSvg).and.to.include('#abcdef')
+  })
+})

badge-maker/lib/badge-renderers.js

@@ -0,0 +1,807 @@
+'use strict'
+
+const anafanafo = require('anafanafo')
+const { brightness } = require('./color')
+const { XmlElement, escapeXml } = require('./xml')
+
+// https://github.com/badges/shields/pull/1132
+const FONT_SCALE_UP_FACTOR = 10
+const FONT_SCALE_DOWN_VALUE = 'scale(.1)'
+
+const FONT_FAMILY = 'Verdana,Geneva,DejaVu Sans,sans-serif'
+const fontFamily = `font-family="${FONT_FAMILY}"`
+const socialFontFamily =
+  'font-family="Helvetica Neue,Helvetica,Arial,sans-serif"'
+const brightnessThreshold = 0.69
+
+function capitalize(s) {
+  return `${s.charAt(0).toUpperCase()}${s.slice(1)}`
+}
+
+function colorsForBackground(color) {
+  if (brightness(color) <= brightnessThreshold) {
+    return { textColor: '#fff', shadowColor: '#010101' }
+  } else {
+    return { textColor: '#333', shadowColor: '#ccc' }
+  }
+}
+
+function roundUpToOdd(val) {
+  return val % 2 === 0 ? val + 1 : val
+}
+
+function preferredWidthOf(str, options) {
+  // Increase chances of pixel grid alignment.
+  return roundUpToOdd(anafanafo(str, options) | 0)
+}
+
+function createAccessibleText({ label, message }) {
+  const labelPrefix = label ? `${label}: ` : ''
+  return labelPrefix + message
+}
+
+function hasLinks({ links }) {
+  const [leftLink, rightLink] = links || []
+  const hasLeftLink = leftLink && leftLink.length
+  const hasRightLink = rightLink && rightLink.length
+  const hasLink = hasLeftLink && hasRightLink
+  return { hasLink, hasLeftLink, hasRightLink }
+}
+
+function shouldWrapBodyWithLink({ links }) {
+  const { hasLeftLink, hasRightLink } = hasLinks({ links })
+  return hasLeftLink && !hasRightLink
+}
+
+function renderAriaAttributes({ accessibleText, links }) {
+  const { hasLink } = hasLinks({ links })
+  return hasLink ? '' : `role="img" aria-label="${escapeXml(accessibleText)}"`
+}
+
+function renderTitle({ accessibleText, links }) {
+  const { hasLink } = hasLinks({ links })
+  return hasLink ? '' : `<title>${escapeXml(accessibleText)}</title>`
+}
+
+function renderLogo({
+  logo,
+  badgeHeight,
+  horizPadding,
+  logoWidth = 14,
+  logoPadding = 0,
+}) {
+  if (logo) {
+    const logoHeight = 14
+    const y = (badgeHeight - logoHeight) / 2
+    const x = horizPadding
+    return {
+      hasLogo: true,
+      totalLogoWidth: logoWidth + logoPadding,
+      renderedLogo: `<image x="${x}" y="${y}" width="${logoWidth}" height="${logoHeight}" xlink:href="${escapeXml(
+        logo
+      )}"/>`,
+    }
+  } else {
+    return { hasLogo: false, totalLogoWidth: 0, renderedLogo: '' }
+  }
+}
+
+function renderLink({
+  link,
+  height,
+  textLength,
+  horizPadding,
+  leftMargin,
+  renderedText,
+}) {
+  const rectHeight = height
+  const rectWidth = textLength + horizPadding * 2
+  const rectX = leftMargin > 1 ? leftMargin + 1 : 0
+  return `<a target="_blank" xlink:href="${escapeXml(link)}">
+    <rect width="${rectWidth}" x="${rectX}" height="${rectHeight}" fill="rgba(0,0,0,0)" />
+    ${renderedText}
+  </a>`
+}
+
+function renderText({
+  leftMargin,
+  horizPadding = 0,
+  content,
+  link,
+  height,
+  verticalMargin = 0,
+  shadow = false,
+  color,
+}) {
+  if (!content.length) {
+    return { renderedText: '', width: 0 }
+  }
+
+  const textLength = preferredWidthOf(content, { font: '11px Verdana' })
+  const escapedContent = escapeXml(content)
+
+  const shadowMargin = 150 + verticalMargin
+  const textMargin = 140 + verticalMargin
+
+  const outTextLength = 10 * textLength
+  const x = 10 * (leftMargin + 0.5 * textLength + horizPadding)
+
+  let renderedText = ''
+  const { textColor, shadowColor } = colorsForBackground(color)
+  if (shadow) {
+    renderedText = `<text aria-hidden="true" x="${x}" y="${shadowMargin}" fill="${shadowColor}" fill-opacity=".3" transform="scale(.1)" textLength="${outTextLength}">${escapedContent}</text>`
+  }
+  renderedText += `<text x="${x}" y="${textMargin}" transform="scale(.1)" fill="${textColor}" textLength="${outTextLength}">${escapedContent}</text>`
+
+  return {
+    renderedText: link
+      ? renderLink({
+          link,
+          height,
+          textLength,
+          horizPadding,
+          leftMargin,
+          renderedText,
+        })
+      : renderedText,
+    width: textLength,
+  }
+}
+
+function renderBadge(
+  { links, leftWidth, rightWidth, height, accessibleText },
+  main
+) {
+  const width = leftWidth + rightWidth
+  const leftLink = escapeXml(links[0])
+
+  return `
+    <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="${width}" height="${height}" ${renderAriaAttributes(
+    { links, accessibleText }
+  )}>
+
+    ${renderTitle({ accessibleText, links })}
+    ${
+      shouldWrapBodyWithLink({ links })
+        ? `<a target="_blank" xlink:href="${leftLink}">${main}</a>`
+        : main
+    }
+    </svg>`
+}
+
+class Badge {
+  static get fontFamily() {
+    throw new Error('Not implemented')
+  }
+
+  static get height() {
+    throw new Error('Not implemented')
+  }
+
+  static get verticalMargin() {
+    throw new Error('Not implemented')
+  }
+
+  static get shadow() {
+    throw new Error('Not implemented')
+  }
+
+  constructor({
+    label,
+    message,
+    links,
+    logo,
+    logoWidth,
+    logoPadding,
+    color = '#4c1',
+    labelColor,
+  }) {
+    const horizPadding = 5
+    const { hasLogo, totalLogoWidth, renderedLogo } = renderLogo({
+      logo,
+      badgeHeight: this.constructor.height,
+      horizPadding,
+      logoWidth,
+      logoPadding,
+    })
+    const hasLabel = label.length || labelColor
+    if (labelColor == null) {
+      labelColor = '#555'
+    }
+
+    const [leftLink, rightLink] = links
+
+    labelColor = hasLabel || hasLogo ? labelColor : color
+    labelColor = escapeXml(labelColor)
+    color = escapeXml(color)
+
+    const labelMargin = totalLogoWidth + 1
+
+    const { renderedText: renderedLabel, width: labelWidth } = renderText({
+      leftMargin: labelMargin,
+      horizPadding,
+      content: label,
+      link: !shouldWrapBodyWithLink({ links }) && leftLink,
+      height: this.constructor.height,
+      verticalMargin: this.constructor.verticalMargin,
+      shadow: this.constructor.shadow,
+      color: labelColor,
+    })
+
+    const leftWidth = hasLabel
+      ? labelWidth + 2 * horizPadding + totalLogoWidth
+      : 0
+
+    let messageMargin = leftWidth - (message.length ? 1 : 0)
+    if (!hasLabel) {
+      if (hasLogo) {
+        messageMargin = messageMargin + totalLogoWidth + horizPadding
+      } else {
+        messageMargin = messageMargin + 1
+      }
+    }
+
+    const { renderedText: renderedMessage, width: messageWidth } = renderText({
+      leftMargin: messageMargin,
+      horizPadding,
+      content: message,
+      link: rightLink,
+      height: this.constructor.height,
+      verticalMargin: this.constructor.verticalMargin,
+      shadow: this.constructor.shadow,
+      color,
+    })
+
+    let rightWidth = messageWidth + 2 * horizPadding
+    if (hasLogo && !hasLabel) {
+      rightWidth += totalLogoWidth + horizPadding - 1
+    }
+
+    const width = leftWidth + rightWidth
+
+    const accessibleText = createAccessibleText({ label, message })
+
+    this.links = links
+    this.leftWidth = leftWidth
+    this.rightWidth = rightWidth
+    this.width = width
+    this.labelColor = labelColor
+    this.color = color
+    this.label = label
+    this.message = message
+    this.accessibleText = accessibleText
+    this.renderedLogo = renderedLogo
+    this.renderedLabel = renderedLabel
+    this.renderedMessage = renderedMessage
+  }
+
+  static render(params) {
+    return new this(params).render()
+  }
+
+  render() {
+    throw new Error('Not implemented')
+  }
+}
+
+class Plastic extends Badge {
+  static get fontFamily() {
+    return fontFamily
+  }
+
+  static get height() {
+    return 18
+  }
+
+  static get verticalMargin() {
+    return -10
+  }
+
+  static get shadow() {
+    return true
+  }
+
+  render() {
+    return renderBadge(
+      {
+        links: this.links,
+        leftWidth: this.leftWidth,
+        rightWidth: this.rightWidth,
+        accessibleText: this.accessibleText,
+        height: this.constructor.height,
+      },
+      `
+      <linearGradient id="s" x2="0" y2="100%">
+        <stop offset="0"  stop-color="#fff" stop-opacity=".7"/>
+        <stop offset=".1" stop-color="#aaa" stop-opacity=".1"/>
+        <stop offset=".9" stop-color="#000" stop-opacity=".3"/>
+        <stop offset="1"  stop-color="#000" stop-opacity=".5"/>
+      </linearGradient>
+
+      <clipPath id="r">
+        <rect width="${this.width}" height="${this.constructor.height}" rx="4" fill="#fff"/>
+      </clipPath>
+
+      <g clip-path="url(#r)">
+        <rect width="${this.leftWidth}" height="${this.constructor.height}" fill="${this.labelColor}"/>
+        <rect x="${this.leftWidth}" width="${this.rightWidth}" height="${this.constructor.height}" fill="${this.color}"/>
+        <rect width="${this.width}" height="${this.constructor.height}" fill="url(#s)"/>
+      </g>
+
+      <g fill="#fff" text-anchor="middle" ${this.constructor.fontFamily} text-rendering="geometricPrecision" font-size="110">
+        ${this.renderedLogo}
+        ${this.renderedLabel}
+        ${this.renderedMessage}
+      </g>`
+    )
+  }
+}
+
+class Flat extends Badge {
+  static get fontFamily() {
+    return fontFamily
+  }
+
+  static get height() {
+    return 20
+  }
+
+  static get verticalMargin() {
+    return 0
+  }
+
+  static get shadow() {
+    return true
+  }
+
+  render() {
+    return renderBadge(
+      {
+        links: this.links,
+        leftWidth: this.leftWidth,
+        rightWidth: this.rightWidth,
+        accessibleText: this.accessibleText,
+        height: this.constructor.height,
+      },
+      `
+      <linearGradient id="s" x2="0" y2="100%">
+        <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+        <stop offset="1" stop-opacity=".1"/>
+      </linearGradient>
+
+      <clipPath id="r">
+        <rect width="${this.width}" height="${this.constructor.height}" rx="3" fill="#fff"/>
+      </clipPath>
+
+      <g clip-path="url(#r)">
+        <rect width="${this.leftWidth}" height="${this.constructor.height}" fill="${this.labelColor}"/>
+        <rect x="${this.leftWidth}" width="${this.rightWidth}" height="${this.constructor.height}" fill="${this.color}"/>
+        <rect width="${this.width}" height="${this.constructor.height}" fill="url(#s)"/>
+      </g>
+
+      <g fill="#fff" text-anchor="middle" ${this.constructor.fontFamily} text-rendering="geometricPrecision" font-size="110">
+        ${this.renderedLogo}
+        ${this.renderedLabel}
+        ${this.renderedMessage}
+      </g>`
+    )
+  }
+}
+
+class FlatSquare extends Badge {
+  static get fontFamily() {
+    return fontFamily
+  }
+
+  static get height() {
+    return 20
+  }
+
+  static get verticalMargin() {
+    return 0
+  }
+
+  static get shadow() {
+    return false
+  }
+
+  render() {
+    return renderBadge(
+      {
+        links: this.links,
+        leftWidth: this.leftWidth,
+        rightWidth: this.rightWidth,
+        accessibleText: this.accessibleText,
+        height: this.constructor.height,
+      },
+      `
+      <g shape-rendering="crispEdges">
+        <rect width="${this.leftWidth}" height="${this.constructor.height}" fill="${this.labelColor}"/>
+        <rect x="${this.leftWidth}" width="${this.rightWidth}" height="${this.constructor.height}" fill="${this.color}"/>
+      </g>
+
+      <g fill="#fff" text-anchor="middle" ${this.constructor.fontFamily} text-rendering="geometricPrecision" font-size="110">
+        ${this.renderedLogo}
+        ${this.renderedLabel}
+        ${this.renderedMessage}
+      </g>`
+    )
+  }
+}
+
+function social({
+  label,
+  message,
+  links = [],
+  logo,
+  logoWidth,
+  logoPadding,
+  color = '#4c1',
+  labelColor = '#555',
+}) {
+  // Social label is styled with a leading capital. Convert to caps here so
+  // width can be measured using the correct characters.
+  label = capitalize(label)
+
+  const externalHeight = 20
+  const internalHeight = 19
+  const labelHorizPadding = 5
+  const messageHorizPadding = 4
+  const horizGutter = 6
+  const { totalLogoWidth, renderedLogo } = renderLogo({
+    logo,
+    badgeHeight: externalHeight,
+    horizPadding: labelHorizPadding,
+    logoWidth,
+    logoPadding,
+  })
+  const hasMessage = message.length
+
+  const font = 'bold 11px Helvetica'
+  const labelTextWidth = preferredWidthOf(label, { font })
+  const messageTextWidth = preferredWidthOf(message, { font })
+  const labelRectWidth = labelTextWidth + totalLogoWidth + 2 * labelHorizPadding
+  const messageRectWidth = messageTextWidth + 2 * messageHorizPadding
+
+  let [leftLink, rightLink] = links
+  leftLink = escapeXml(leftLink)
+  rightLink = escapeXml(rightLink)
+  const { hasLeftLink, hasRightLink, hasLink } = hasLinks({ links })
+
+  const accessibleText = createAccessibleText({ label, message })
+
+  function renderMessageBubble() {
+    const messageBubbleMainX = labelRectWidth + horizGutter + 0.5
+    const messageBubbleNotchX = labelRectWidth + horizGutter
+    return `
+      <rect x="${messageBubbleMainX}" y="0.5" width="${messageRectWidth}" height="${internalHeight}" rx="2" fill="#fafafa"/>
+      <rect x="${messageBubbleNotchX}" y="7.5" width="0.5" height="5" stroke="#fafafa"/>
+      <path d="M${messageBubbleMainX} 6.5 l-3 3v1 l3 3" stroke="d5d5d5" fill="#fafafa"/>
+    `
+  }
+
+  function renderLabelText() {
+    const labelTextX =
+      10 * (totalLogoWidth + labelTextWidth / 2 + labelHorizPadding)
+    const labelTextLength = 10 * labelTextWidth
+    const escapedLabel = escapeXml(label)
+    const shouldWrapWithLink = hasLeftLink && !shouldWrapBodyWithLink({ links })
+
+    const rect = `<rect id="llink" stroke="#d5d5d5" fill="url(#a)" x=".5" y=".5" width="${labelRectWidth}" height="${internalHeight}" rx="2" />`
+    const shadow = `<text aria-hidden="true" x="${labelTextX}" y="150" fill="#fff" transform="scale(.1)" textLength="${labelTextLength}">${escapedLabel}</text>`
+    const text = `<text x="${labelTextX}" y="140" transform="scale(.1)" textLength="${labelTextLength}">${escapedLabel}</text>`
+
+    return shouldWrapWithLink
+      ? `
+        <a target="_blank" xlink:href="${leftLink}">
+          ${shadow}
+          ${text}
+          ${rect}
+        </a>
+      `
+      : `
+      ${rect}
+      ${shadow}
+      ${text}
+    `
+  }
+
+  function renderMessageText() {
+    const messageTextX =
+      10 * (labelRectWidth + horizGutter + messageRectWidth / 2)
+    const messageTextLength = 10 * messageTextWidth
+    const escapedMessage = escapeXml(message)
+
+    const rect = `<rect width="${messageRectWidth + 1}" x="${
+      labelRectWidth + horizGutter
+    }" height="${internalHeight + 1}" fill="rgba(0,0,0,0)" />`
+    const shadow = `<text aria-hidden="true" x="${messageTextX}" y="150" fill="#fff" transform="scale(.1)" textLength="${messageTextLength}">${escapedMessage}</text>`
+    const text = `<text id="rlink" x="${messageTextX}" y="140" transform="scale(.1)" textLength="${messageTextLength}">${escapedMessage}</text>`
+
+    return hasRightLink
+      ? `
+        <a target="_blank" xlink:href="${rightLink}">
+          ${rect}
+          ${shadow}
+          ${text}
+        </a>
+      `
+      : `
+      ${shadow}
+      ${text}
+    `
+  }
+
+  return renderBadge(
+    {
+      links,
+      leftWidth: labelRectWidth + 1,
+      rightWidth: hasMessage ? horizGutter + messageRectWidth : 0,
+      accessibleText,
+      height: externalHeight,
+    },
+    `
+    <style>a:hover #llink{fill:url(#b);stroke:#ccc}a:hover #rlink{fill:#4183c4}</style>
+    <linearGradient id="a" x2="0" y2="100%">
+      <stop offset="0" stop-color="#fcfcfc" stop-opacity="0"/>
+      <stop offset="1" stop-opacity=".1"/>
+    </linearGradient>
+    <linearGradient id="b" x2="0" y2="100%">
+      <stop offset="0" stop-color="#ccc" stop-opacity=".1"/>
+      <stop offset="1" stop-opacity=".1"/>
+    </linearGradient>
+    <g stroke="#d5d5d5">
+      <rect stroke="none" fill="#fcfcfc" x="0.5" y="0.5" width="${labelRectWidth}" height="${internalHeight}" rx="2"/>
+      ${hasMessage ? renderMessageBubble() : ''}
+    </g>
+    ${renderedLogo}
+    <g aria-hidden="${!hasLink}" fill="#333" text-anchor="middle" ${socialFontFamily} text-rendering="geometricPrecision" font-weight="700" font-size="110px" line-height="14px">
+      ${renderLabelText()}
+      ${hasMessage ? renderMessageText() : ''}
+    </g>
+    `
+  )
+}
+
+function forTheBadge({
+  label,
+  message,
+  links,
+  logo,
+  logoWidth,
+  color = '#4c1',
+  labelColor,
+}) {
+  const FONT_SIZE = 10
+  const BADGE_HEIGHT = 28
+  const LOGO_HEIGHT = 14
+  const TEXT_MARGIN = 12
+  const LOGO_MARGIN = 9
+  const LOGO_TEXT_GUTTER = 6
+  const LETTER_SPACING = 1.25
+
+  // Prepare content. For the Badge is styled in all caps. It's important to to
+  // convert to uppercase first so the widths can be measured using the correct
+  // symbols.
+  label = label.toUpperCase()
+  message = message.toUpperCase()
+
+  const [leftLink, rightLink] = links
+  const { hasLeftLink, hasRightLink } = hasLinks({ links })
+
+  const outLabelColor = labelColor || '#555'
+
+  // Compute text width.
+  // TODO: This really should count the symbols rather than just using `.length`.
+  // https://mathiasbynens.be/notes/javascript-unicode
+  // This is not using `preferredWidthOf()` as it tends to produce larger
+  // inconsistencies in the letter spacing. The badges look fine, however if you
+  // replace `textLength` with `letterSpacing` in the rendered SVG, you can see
+  // the discrepancy. Ideally, swapping out `textLength` for `letterSpacing`
+  // should not affect the appearance.
+  const labelTextWidth = label.length
+    ? (anafanafo(label, { font: `${FONT_SIZE}px Verdana` }) | 0) +
+      LETTER_SPACING * label.length
+    : 0
+  const messageTextWidth = message.length
+    ? (anafanafo(message, { font: `bold ${FONT_SIZE}px Verdana` }) | 0) +
+      LETTER_SPACING * message.length
+    : 0
+
+  // Compute horizontal layout.
+  // If a `labelColor` is set, the logo is always set against it, even when
+  // there is no label. When `needsLabelRect` is true, render a label rect and a
+  // message rect; when false, only a message rect.
+  const hasLabel = Boolean(label.length)
+  const needsLabelRect = hasLabel || (logo && labelColor)
+  let logoMinX, labelTextMinX
+  if (logo) {
+    logoMinX = LOGO_MARGIN
+    labelTextMinX = logoMinX + logoWidth + LOGO_TEXT_GUTTER
+  } else {
+    labelTextMinX = TEXT_MARGIN
+  }
+  let labelRectWidth, messageTextMinX, messageRectWidth
+  if (needsLabelRect) {
+    if (hasLabel) {
+      labelRectWidth = labelTextMinX + labelTextWidth + TEXT_MARGIN
+    } else {
+      labelRectWidth = 2 * LOGO_MARGIN + logoWidth
+    }
+    messageTextMinX = labelRectWidth + TEXT_MARGIN
+    messageRectWidth = 2 * TEXT_MARGIN + messageTextWidth
+  } else {
+    if (logo) {
+      messageTextMinX = TEXT_MARGIN + logoWidth + LOGO_TEXT_GUTTER
+      messageRectWidth =
+        2 * TEXT_MARGIN + logoWidth + LOGO_TEXT_GUTTER + messageTextWidth
+    } else {
+      messageTextMinX = TEXT_MARGIN
+      messageRectWidth = 2 * TEXT_MARGIN + messageTextWidth
+    }
+  }
+
+  const logoElement = new XmlElement({
+    name: 'image',
+    attrs: {
+      x: logoMinX,
+      y: 0.5 * (BADGE_HEIGHT - LOGO_HEIGHT),
+      width: logoWidth,
+      height: LOGO_HEIGHT,
+      'xlink:href': logo,
+    },
+  })
+
+  function getLabelElement() {
+    const { textColor } = colorsForBackground(outLabelColor)
+    const midX = labelTextMinX + 0.5 * labelTextWidth
+    const text = new XmlElement({
+      name: 'text',
+      content: [label],
+      attrs: {
+        transform: FONT_SCALE_DOWN_VALUE,
+        x: FONT_SCALE_UP_FACTOR * midX,
+        y: 175,
+        textLength: FONT_SCALE_UP_FACTOR * labelTextWidth,
+        fill: textColor,
+      },
+    })
+
+    if (hasLeftLink && !shouldWrapBodyWithLink({ links })) {
+      const rect = new XmlElement({
+        name: 'rect',
+        attrs: {
+          width: labelRectWidth,
+          height: BADGE_HEIGHT,
+          fill: 'rgba(0,0,0,0)',
+        },
+      })
+      return new XmlElement({
+        name: 'a',
+        content: [rect, text],
+        attrs: {
+          target: '_blank',
+          'xlink:href': leftLink,
+        },
+      })
+    } else {
+      return text
+    }
+  }
+
+  function getMessageElement() {
+    const { textColor } = colorsForBackground(color)
+    const midX = messageTextMinX + 0.5 * messageTextWidth
+    const text = new XmlElement({
+      name: 'text',
+      content: [message],
+      attrs: {
+        transform: FONT_SCALE_DOWN_VALUE,
+        x: FONT_SCALE_UP_FACTOR * midX,
+        y: 175,
+        textLength: FONT_SCALE_UP_FACTOR * messageTextWidth,
+        fill: textColor,
+        'font-weight': 'bold',
+      },
+    })
+
+    if (hasRightLink) {
+      const rect = new XmlElement({
+        name: 'rect',
+        attrs: {
+          width: messageRectWidth,
+          height: BADGE_HEIGHT,
+          x: labelRectWidth || 0,
+          fill: 'rgba(0,0,0,0)',
+        },
+      })
+      return new XmlElement({
+        name: 'a',
+        content: [rect, text],
+        attrs: {
+          target: '_blank',
+          'xlink:href': rightLink,
+        },
+      })
+    } else {
+      return text
+    }
+  }
+
+  let backgroundContent
+  if (needsLabelRect) {
+    backgroundContent = [
+      new XmlElement({
+        name: 'rect',
+        attrs: {
+          width: labelRectWidth,
+          height: BADGE_HEIGHT,
+          fill: outLabelColor,
+        },
+      }),
+      new XmlElement({
+        name: 'rect',
+        attrs: {
+          x: labelRectWidth,
+          width: messageRectWidth,
+          height: BADGE_HEIGHT,
+          fill: color,
+        },
+      }),
+    ]
+  } else {
+    backgroundContent = [
+      new XmlElement({
+        name: 'rect',
+        attrs: {
+          width: messageRectWidth,
+          height: BADGE_HEIGHT,
+          fill: color,
+        },
+      }),
+    ]
+  }
+
+  const backgroundGroup = new XmlElement({
+    name: 'g',
+    content: backgroundContent,
+    attrs: {
+      'shape-rendering': 'crispEdges',
+    },
+  })
+  const foregroundGroup = new XmlElement({
+    name: 'g',
+    content: [
+      logo ? logoElement : '',
+      hasLabel ? getLabelElement() : '',
+      getMessageElement(),
+    ],
+    attrs: {
+      fill: '#fff',
+      'text-anchor': 'middle',
+      'font-family': FONT_FAMILY,
+      'text-rendering': 'geometricPrecision',
+      'font-size': FONT_SCALE_UP_FACTOR * FONT_SIZE,
+    },
+  })
+
+  // Render.
+  return renderBadge(
+    {
+      links,
+      leftWidth: labelRectWidth || 0,
+      rightWidth: messageRectWidth,
+      accessibleText: createAccessibleText({ label, message }),
+      height: BADGE_HEIGHT,
+    },
+    [backgroundGroup.render(), foregroundGroup.render()].join('')
+  )
+}
+
+module.exports = {
+  plastic: params => Plastic.render(params),
+  flat: params => Flat.render(params),
+  'flat-square': params => FlatSquare.render(params),
+  social,
+  'for-the-badge': forTheBadge,
+}

badge-maker/lib/color.js

@@ -0,0 +1,88 @@
+'use strict'
+
+const { fromString } = require('css-color-converter')
+
+// When updating these, be sure also to update the list in `badge-maker/README.md`.
+const namedColors = {
+  brightgreen: '#4c1',
+  green: '#97ca00',
+  yellow: '#dfb317',
+  yellowgreen: '#a4a61d',
+  orange: '#fe7d37',
+  red: '#e05d44',
+  blue: '#007ec6',
+  grey: '#555',
+  lightgrey: '#9f9f9f',
+}
+
+const aliases = {
+  gray: 'grey',
+  lightgray: 'lightgrey',
+  critical: 'red',
+  important: 'orange',
+  success: 'brightgreen',
+  informational: 'blue',
+  inactive: 'lightgrey',
+}
+
+const resolvedAliases = {}
+Object.entries(aliases).forEach(([alias, original]) => {
+  resolvedAliases[alias] = namedColors[original]
+})
+
+// This function returns false for `#ccc`. However `isCSSColor('#ccc')` is
+// true.
+const hexColorRegex = /^([\da-f]{3}){1,2}$/i
+function isHexColor(s = '') {
+  return hexColorRegex.test(s)
+}
+
+function isCSSColor(color) {
+  return typeof color === 'string' && fromString(color.trim())
+}
+
+function normalizeColor(color) {
+  if (color === undefined) {
+    return undefined
+  } else if (color in namedColors) {
+    return color
+  } else if (color in aliases) {
+    return aliases[color]
+  } else if (isHexColor(color)) {
+    return `#${color.toLowerCase()}`
+  } else if (isCSSColor(color)) {
+    return color.toLowerCase()
+  } else {
+    return undefined
+  }
+}
+
+function toSvgColor(color) {
+  const normalized = normalizeColor(color)
+  if (normalized in namedColors) {
+    return namedColors[normalized]
+  } else if (normalized in resolvedAliases) {
+    return resolvedAliases[normalized]
+  } else {
+    return normalized
+  }
+}
+
+function brightness(color) {
+  if (color) {
+    const cssColor = fromString(color)
+    if (cssColor) {
+      const rgb = cssColor.toRgbaArray()
+      return +((rgb[0] * 299 + rgb[1] * 587 + rgb[2] * 114) / 255000).toFixed(2)
+    }
+  }
+  return 0
+}
+
+module.exports = {
+  namedColors,
+  isHexColor,
+  normalizeColor,
+  toSvgColor,
+  brightness,
+}

badge-maker/lib/color.spec.js

@@ -0,0 +1,91 @@
+'use strict'
+
+const { test, given, forCases } = require('sazerac')
+const {
+  isHexColor,
+  normalizeColor,
+  toSvgColor,
+  brightness,
+} = require('./color')
+
+test(isHexColor, () => {
+  forCases([given('f00bae'), given('4c1'), given('ABC123')]).expect(true)
+  forCases([
+    given('f00bar'),
+    given(''),
+    given(undefined),
+    given(null),
+    given(true),
+    given([]),
+    given({}),
+    given(() => {}),
+  ]).expect(false)
+})
+
+test(normalizeColor, () => {
+  given('red').expect('red')
+  given('blue').expect('blue')
+  given('4c1').expect('#4c1')
+  given('f00f00').expect('#f00f00')
+  given('ABC123').expect('#abc123')
+  given('#ccc').expect('#ccc')
+  given('#fffe').expect('#fffe')
+  given('#fffeffff').expect('#fffeffff')
+  given('#ABC123').expect('#abc123')
+  given('papayawhip').expect('papayawhip')
+  given('purple').expect('purple')
+  given('  blue ').expect('  blue ')
+  given('rgb(100%, 200%, 222%)').expect('rgb(100%, 200%, 222%)')
+  given('rgb(122, 200, 222)').expect('rgb(122, 200, 222)')
+  given('rgb(122, 200, 222, 1)').expect('rgb(122, 200, 222, 1)')
+  given('rgba(100, 20, 111, 1)').expect('rgba(100, 20, 111, 1)')
+  given('hsl(122, 200%, 222%)').expect('hsl(122, 200%, 222%)')
+  given('hsla(122, 200%, 222%, 1)').expect('hsla(122, 200%, 222%, 1)')
+  forCases([
+    given(),
+    given(''),
+    given('not-a-color'),
+    given('#ABCFGH'),
+    given('rgb(-100, 20, 111)'),
+    given('rgb(100%, 200, 222)'),
+    given('rgba(-100, 20, 111, 1.1)'),
+    given('hsl(122, 200, 222, 1)'),
+    given('hsl(122, 200, 222)'),
+    given('hsl(122, 200, 222%)'),
+    given(undefined),
+    given(null),
+    given(true),
+    given(1),
+    given(Math),
+    given([]),
+    given({}),
+    given(() => {}),
+  ]).expect(undefined)
+  given('lightgray').expect('lightgrey')
+  given('informational').expect('blue')
+})
+
+test(toSvgColor, () => {
+  given('red').expect('#e05d44')
+  given('blue').expect('#007ec6')
+  given('4c1').expect('#4c1')
+  given('f00f00').expect('#f00f00')
+  given('ABC123').expect('#abc123')
+  given('#ABC123').expect('#abc123')
+  given('papayawhip').expect('papayawhip')
+  given('purple').expect('purple')
+  forCases([given(''), given(undefined), given('not-a-color')]).expect(
+    undefined
+  )
+  given('lightgray').expect('#9f9f9f')
+  given('informational').expect('#007ec6')
+})
+
+test(brightness, () => {
+  given('white').expect(1)
+  given('black').expect(0)
+  given('#abc123').expect(0.66)
+  given('rgb(10, 5, 128)').expect(0.08)
+  given(undefined).expect(0)
+  given('not-a-color').expect(0)
+})

badge-maker/lib/index.js

@@ -0,0 +1,81 @@
+'use strict'
+/**
+ * @module badge-maker
+ */
+
+const _makeBadge = require('./make-badge')
+
+class ValidationError extends Error {}
+
+function _validate(format) {
+  if (format !== Object(format)) {
+    throw new ValidationError('makeBadge takes an argument of type object')
+  }
+
+  if (!('message' in format)) {
+    throw new ValidationError('Field `message` is required')
+  }
+
+  const stringFields = ['labelColor', 'color', 'message', 'label']
+  stringFields.forEach(function (field) {
+    if (field in format && typeof format[field] !== 'string') {
+      throw new ValidationError(`Field \`${field}\` must be of type string`)
+    }
+  })
+
+  const styleValues = [
+    'plastic',
+    'flat',
+    'flat-square',
+    'for-the-badge',
+    'social',
+  ]
+  if ('style' in format && !styleValues.includes(format.style)) {
+    throw new ValidationError(
+      `Field \`style\` must be one of (${styleValues.toString()})`
+    )
+  }
+}
+
+function _clean(format) {
+  const expectedKeys = ['label', 'message', 'labelColor', 'color', 'style']
+
+  const cleaned = {}
+  Object.keys(format).forEach(key => {
+    if (format[key] != null && expectedKeys.includes(key)) {
+      cleaned[key] = format[key]
+    } else {
+      throw new ValidationError(
+        `Unexpected field '${key}'. Allowed values are (${expectedKeys.toString()})`
+      )
+    }
+  })
+
+  // Legacy.
+  cleaned.label = cleaned.label || ''
+
+  return cleaned
+}
+
+/**
+ * Create a badge
+ *
+ * @param {object} format Object specifying badge data
+ * @param {string} format.label (Optional) Badge label (e.g: 'build')
+ * @param {string} format.message (Required) Badge message (e.g: 'passing')
+ * @param {string} format.labelColor (Optional) Label color
+ * @param {string} format.color (Optional) Message color
+ * @param {string} format.style (Optional) Visual style e.g: 'flat'
+ * @returns {string} Badge in SVG format
+ * @see https://github.com/badges/shields/tree/master/badge-maker/README.md
+ */
+function makeBadge(format) {
+  _validate(format)
+  const cleanedFormat = _clean(format)
+  return _makeBadge(cleanedFormat)
+}
+
+module.exports = {
+  makeBadge,
+  ValidationError,
+}

badge-maker/lib/index.spec.js

@@ -0,0 +1,75 @@
+'use strict'
+
+const { expect } = require('chai')
+const isSvg = require('is-svg')
+const { makeBadge, ValidationError } = require('.')
+
+describe('makeBadge function', function () {
+  it('should produce badge with valid input', function () {
+    expect(
+      makeBadge({
+        label: 'build',
+        message: 'passed',
+      })
+    ).to.satisfy(isSvg)
+    expect(
+      makeBadge({
+        message: 'passed',
+      })
+    ).to.satisfy(isSvg)
+    expect(
+      makeBadge({
+        label: 'build',
+        message: 'passed',
+        color: 'green',
+        style: 'flat',
+      })
+    ).to.satisfy(isSvg)
+  })
+
+  it('should throw a ValidationError with invalid inputs', function () {
+    ;[null, undefined, 7, 'foo', 4.25].forEach(x => {
+      console.log(x)
+      expect(() => makeBadge(x)).to.throw(
+        ValidationError,
+        'makeBadge takes an argument of type object'
+      )
+    })
+    expect(() => makeBadge({})).to.throw(
+      ValidationError,
+      'Field `message` is required'
+    )
+    expect(() => makeBadge({ label: 'build' })).to.throw(
+      ValidationError,
+      'Field `message` is required'
+    )
+    expect(() =>
+      makeBadge({ label: 'build', message: 'passed', labelColor: 7 })
+    ).to.throw(ValidationError, 'Field `labelColor` must be of type string')
+    expect(() =>
+      makeBadge({ label: 'build', message: 'passed', format: 'png' })
+    ).to.throw(ValidationError, "Unexpected field 'format'")
+    expect(() =>
+      makeBadge({ label: 'build', message: 'passed', template: 'flat' })
+    ).to.throw(ValidationError, "Unexpected field 'template'")
+    expect(() =>
+      makeBadge({ label: 'build', message: 'passed', foo: 'bar' })
+    ).to.throw(ValidationError, "Unexpected field 'foo'")
+    expect(() =>
+      makeBadge({
+        label: 'build',
+        message: 'passed',
+        style: 'something else',
+      })
+    ).to.throw(
+      ValidationError,
+      'Field `style` must be one of (plastic,flat,flat-square,for-the-badge,social)'
+    )
+    expect(() =>
+      makeBadge({ label: 'build', message: 'passed', style: 'popout' })
+    ).to.throw(
+      ValidationError,
+      'Field `style` must be one of (plastic,flat,flat-square,for-the-badge,social)'
+    )
+  })
+})

badge-maker/lib/make-badge.js

@@ -0,0 +1,63 @@
+'use strict'
+
+const { normalizeColor, toSvgColor } = require('./color')
+const badgeRenderers = require('./badge-renderers')
+const { stripXmlWhitespace } = require('./xml')
+
+/*
+note: makeBadge() is fairly thinly wrapped so if we are making changes here
+it is likely this will impact on the package's public interface in index.js
+*/
+module.exports = function makeBadge({
+  format,
+  style = 'flat',
+  label,
+  message,
+  color,
+  labelColor,
+  logo,
+  logoPosition,
+  logoWidth,
+  links = ['', ''],
+}) {
+  // String coercion and whitespace removal.
+  label = `${label}`.trim()
+  message = `${message}`.trim()
+
+  // This ought to be the responsibility of the server, not `makeBadge`.
+  if (format === 'json') {
+    return JSON.stringify({
+      label,
+      message,
+      logoWidth,
+      // Only call normalizeColor for the JSON case: this is handled
+      // internally by toSvgColor in the SVG case.
+      color: normalizeColor(color),
+      labelColor: normalizeColor(labelColor),
+      link: links,
+      name: label,
+      value: message,
+    })
+  }
+
+  const render = badgeRenderers[style]
+  if (!render) {
+    throw new Error(`Unknown badge style: '${style}'`)
+  }
+
+  logoWidth = +logoWidth || (logo ? 14 : 0)
+
+  return stripXmlWhitespace(
+    render({
+      label,
+      message,
+      links,
+      logo,
+      logoPosition,
+      logoWidth,
+      logoPadding: logo && label.length ? 3 : 0,
+      color: toSvgColor(color),
+      labelColor: toSvgColor(labelColor),
+    })
+  )
+}

badge-maker/lib/make-badge.spec.js

@@ -0,0 +1,583 @@
+'use strict'
+
+const { test, given, forCases } = require('sazerac')
+const { expect } = require('chai')
+const snapshot = require('snap-shot-it')
+const isSvg = require('is-svg')
+const prettier = require('prettier')
+const makeBadge = require('./make-badge')
+
+function expectBadgeToMatchSnapshot(format) {
+  snapshot(prettier.format(makeBadge(format), { parser: 'html' }))
+}
+
+function testColor(color = '', colorAttr = 'color') {
+  return JSON.parse(
+    makeBadge({
+      label: 'name',
+      message: 'Bob',
+      [colorAttr]: color,
+      format: 'json',
+    })
+  ).color
+}
+
+describe('The badge generator', function () {
+  describe('color test', function () {
+    test(testColor, () => {
+      // valid hex
+      forCases([
+        given('#4c1'),
+        given('#4C1'),
+        given('4C1'),
+        given('4c1'),
+      ]).expect('#4c1')
+      forCases([
+        given('#abc123'),
+        given('#ABC123'),
+        given('abc123'),
+        given('ABC123'),
+      ]).expect('#abc123')
+      // valid rgb(a)
+      given('rgb(0,128,255)').expect('rgb(0,128,255)')
+      given('rgb(220,128,255,0.5)').expect('rgb(220,128,255,0.5)')
+      given('rgba(0,0,255)').expect('rgba(0,0,255)')
+      given('rgba(0,128,255,0)').expect('rgba(0,128,255,0)')
+      // valid hsl(a)
+      given('hsl(100, 56%, 10%)').expect('hsl(100, 56%, 10%)')
+      given('hsl(360,50%,50%,0.5)').expect('hsl(360,50%,50%,0.5)')
+      given('hsla(25,20%,0%,0.1)').expect('hsla(25,20%,0%,0.1)')
+      given('hsla(0,50%,101%)').expect('hsla(0,50%,101%)')
+      // CSS named color.
+      given('papayawhip').expect('papayawhip')
+      // Shields named color.
+      given('red').expect('red')
+      given('green').expect('green')
+      given('blue').expect('blue')
+      given('yellow').expect('yellow')
+      // Semantic color alias
+      given('success').expect('brightgreen')
+      given('informational').expect('blue')
+
+      forCases(
+        // invalid hex
+        given('#123red'), // contains letter above F
+        given('#red'), // contains letter above F
+        // neither a css named color nor colorscheme
+        given('notacolor'),
+        given('bluish'),
+        given('almostred'),
+        given('brightmaroon'),
+        given('cactus')
+      ).expect(undefined)
+    })
+  })
+
+  describe('color aliases', function () {
+    test(testColor, () => {
+      forCases([given('#4c1', 'color')]).expect('#4c1')
+    })
+  })
+
+  describe('SVG', function () {
+    it('should produce SVG', function () {
+      expect(makeBadge({ label: 'cactus', message: 'grown', format: 'svg' }))
+        .to.satisfy(isSvg)
+        .and.to.include('cactus')
+        .and.to.include('grown')
+    })
+
+    it('should match snapshot', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+      })
+    })
+  })
+
+  describe('JSON', function () {
+    it('should produce the expected JSON', function () {
+      const json = makeBadge({
+        label: 'cactus',
+        message: 'grown',
+        format: 'json',
+        links: ['https://example.com/', 'https://other.example.com/'],
+      })
+      expect(JSON.parse(json)).to.deep.equal({
+        name: 'cactus',
+        label: 'cactus',
+        value: 'grown',
+        message: 'grown',
+        link: ['https://example.com/', 'https://other.example.com/'],
+      })
+    })
+
+    it('should replace undefined svg badge style with "flat"', function () {
+      const jsonBadgeWithUnknownStyle = makeBadge({
+        label: 'name',
+        message: 'Bob',
+        format: 'svg',
+      })
+      const jsonBadgeWithDefaultStyle = makeBadge({
+        label: 'name',
+        message: 'Bob',
+        format: 'svg',
+        style: 'flat',
+      })
+      expect(jsonBadgeWithUnknownStyle)
+        .to.equal(jsonBadgeWithDefaultStyle)
+        .and.to.satisfy(isSvg)
+    })
+
+    it('should fail with unknown svg badge style', function () {
+      expect(() =>
+        makeBadge({
+          label: 'name',
+          message: 'Bob',
+          format: 'svg',
+          style: 'unknown_style',
+        })
+      ).to.throw(Error, "Unknown badge style: 'unknown_style'")
+    })
+  })
+
+  describe('"flat" template badge generation', function () {
+    it('should match snapshots: message/label, no logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+        style: 'flat',
+        color: '#b3e',
+        labelColor: '#0f0',
+      })
+    })
+
+    it('should match snapshots: message/label, with logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+        style: 'flat',
+        color: '#b3e',
+        labelColor: '#0f0',
+        logo: 'data:image/svg+xml;base64,PHN2ZyB4bWxu',
+      })
+    })
+
+    it('should match snapshots: message only, no logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: '',
+        message: 'grown',
+        format: 'svg',
+        style: 'flat',
+        color: '#b3e',
+      })
+    })
+
+    it('should match snapshots: message only, with logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: '',
+        message: 'grown',
+        format: 'svg',
+        style: 'flat',
+        color: '#b3e',
+        logo: 'data:image/svg+xml;base64,PHN2ZyB4bWxu',
+      })
+    })
+
+    it('should match snapshots: message only, with logo and labelColor', function () {
+      expectBadgeToMatchSnapshot({
+        label: '',
+        message: 'grown',
+        format: 'svg',
+        style: 'flat',
+        color: '#b3e',
+        labelColor: '#0f0',
+        logo: 'data:image/svg+xml;base64,PHN2ZyB4bWxu',
+      })
+    })
+
+    it('should match snapshots: message/label, with links', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+        style: 'flat',
+        color: '#b3e',
+        labelColor: '#0f0',
+        links: ['https://shields.io/', 'https://www.google.co.uk/'],
+      })
+    })
+  })
+
+  describe('"flat-square" template badge generation', function () {
+    it('should match snapshots: message/label, no logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+        style: 'flat-square',
+        color: '#b3e',
+        labelColor: '#0f0',
+      })
+    })
+
+    it('should match snapshots: message/label, with logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+        style: 'flat-square',
+        color: '#b3e',
+        labelColor: '#0f0',
+        logo: 'data:image/svg+xml;base64,PHN2ZyB4bWxu',
+      })
+    })
+
+    it('should match snapshots: message only, no logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: '',
+        message: 'grown',
+        format: 'svg',
+        style: 'flat-square',
+        color: '#b3e',
+      })
+    })
+
+    it('should match snapshots: message only, with logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: '',
+        message: 'grown',
+        format: 'svg',
+        style: 'flat-square',
+        color: '#b3e',
+        logo: 'data:image/svg+xml;base64,PHN2ZyB4bWxu',
+      })
+    })
+
+    it('should match snapshots: message only, with logo and labelColor', function () {
+      expectBadgeToMatchSnapshot({
+        label: '',
+        message: 'grown',
+        format: 'svg',
+        style: 'flat-square',
+        color: '#b3e',
+        labelColor: '#0f0',
+        logo: 'data:image/svg+xml;base64,PHN2ZyB4bWxu',
+      })
+    })
+
+    it('should match snapshots: message/label, with links', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+        style: 'flat-square',
+        color: '#b3e',
+        labelColor: '#0f0',
+        links: ['https://shields.io/', 'https://www.google.co.uk/'],
+      })
+    })
+  })
+
+  describe('"plastic" template badge generation', function () {
+    it('should match snapshots: message/label, no logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+        style: 'plastic',
+        color: '#b3e',
+        labelColor: '#0f0',
+      })
+    })
+
+    it('should match snapshots: message/label, with logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+        style: 'plastic',
+        color: '#b3e',
+        labelColor: '#0f0',
+        logo: 'data:image/svg+xml;base64,PHN2ZyB4bWxu',
+      })
+    })
+
+    it('should match snapshots: message only, no logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: '',
+        message: 'grown',
+        format: 'svg',
+        style: 'plastic',
+        color: '#b3e',
+      })
+    })
+
+    it('should match snapshots: message only, with logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: '',
+        message: 'grown',
+        format: 'svg',
+        style: 'plastic',
+        color: '#b3e',
+        logo: 'data:image/svg+xml;base64,PHN2ZyB4bWxu',
+      })
+    })
+
+    it('should match snapshots: message only, with logo and labelColor', function () {
+      expectBadgeToMatchSnapshot({
+        label: '',
+        message: 'grown',
+        format: 'svg',
+        style: 'plastic',
+        color: '#b3e',
+        labelColor: '#0f0',
+        logo: 'data:image/svg+xml;base64,PHN2ZyB4bWxu',
+      })
+    })
+
+    it('should match snapshots: message/label, with links', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+        style: 'plastic',
+        color: '#b3e',
+        labelColor: '#0f0',
+        links: ['https://shields.io/', 'https://www.google.co.uk/'],
+      })
+    })
+  })
+
+  describe('"for-the-badge" template badge generation', function () {
+    // https://github.com/badges/shields/issues/1280
+    it('numbers should produce a string', function () {
+      expect(
+        makeBadge({
+          label: 1998,
+          message: 1999,
+          format: 'svg',
+          style: 'for-the-badge',
+        })
+      )
+        .to.include('1998')
+        .and.to.include('1999')
+    })
+
+    it('lowercase/mixedcase string should produce uppercase string', function () {
+      expect(
+        makeBadge({
+          label: 'Label',
+          message: '1 string',
+          format: 'svg',
+          style: 'for-the-badge',
+        })
+      )
+        .to.include('LABEL')
+        .and.to.include('1 STRING')
+    })
+
+    it('should match snapshots: message/label, no logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+        style: 'for-the-badge',
+        color: '#b3e',
+        labelColor: '#0f0',
+      })
+    })
+
+    it('should match snapshots: message/label, with logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+        style: 'for-the-badge',
+        color: '#b3e',
+        labelColor: '#0f0',
+        logo: 'data:image/svg+xml;base64,PHN2ZyB4bWxu',
+      })
+    })
+
+    it('should match snapshots: message only, no logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: '',
+        message: 'grown',
+        format: 'svg',
+        style: 'for-the-badge',
+        color: '#b3e',
+      })
+    })
+
+    it('should match snapshots: message only, with logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: '',
+        message: 'grown',
+        format: 'svg',
+        style: 'for-the-badge',
+        color: '#b3e',
+        logo: 'data:image/svg+xml;base64,PHN2ZyB4bWxu',
+      })
+    })
+
+    it('should match snapshots: message only, with logo and labelColor', function () {
+      expectBadgeToMatchSnapshot({
+        label: '',
+        message: 'grown',
+        format: 'svg',
+        style: 'for-the-badge',
+        color: '#b3e',
+        labelColor: '#0f0',
+        logo: 'data:image/svg+xml;base64,PHN2ZyB4bWxu',
+      })
+    })
+
+    it('should match snapshots: message/label, with links', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+        style: 'for-the-badge',
+        color: '#b3e',
+        labelColor: '#0f0',
+        links: ['https://shields.io/', 'https://www.google.co.uk/'],
+      })
+    })
+  })
+
+  describe('"social" template badge generation', function () {
+    it('should produce capitalized string for badge key', function () {
+      expect(
+        makeBadge({
+          label: 'some-key',
+          message: 'some-value',
+          format: 'svg',
+          style: 'social',
+        })
+      )
+        .to.include('Some-key')
+        .and.to.include('some-value')
+    })
+
+    // https://github.com/badges/shields/issues/1606
+    it('should handle empty strings used as badge keys', function () {
+      expect(
+        makeBadge({
+          label: '',
+          message: 'some-value',
+          format: 'json',
+          style: 'social',
+        })
+      )
+        .to.include('""')
+        .and.to.include('some-value')
+    })
+
+    it('should match snapshots: message/label, no logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+        style: 'social',
+        color: '#b3e',
+        labelColor: '#0f0',
+      })
+    })
+
+    it('should match snapshots: message/label, with logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+        style: 'social',
+        color: '#b3e',
+        labelColor: '#0f0',
+        logo: 'data:image/svg+xml;base64,PHN2ZyB4bWxu',
+      })
+    })
+
+    it('should match snapshots: message only, no logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: '',
+        message: 'grown',
+        format: 'svg',
+        style: 'social',
+        color: '#b3e',
+      })
+    })
+
+    it('should match snapshots: message only, with logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: '',
+        message: 'grown',
+        format: 'svg',
+        style: 'social',
+        color: '#b3e',
+        logo: 'data:image/svg+xml;base64,PHN2ZyB4bWxu',
+      })
+    })
+
+    it('should match snapshots: message only, with logo and labelColor', function () {
+      expectBadgeToMatchSnapshot({
+        label: '',
+        message: 'grown',
+        format: 'svg',
+        style: 'social',
+        color: '#b3e',
+        labelColor: '#0f0',
+        logo: 'data:image/svg+xml;base64,PHN2ZyB4bWxu',
+      })
+    })
+
+    it('should match snapshots: message/label, with links', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+        style: 'social',
+        color: '#b3e',
+        labelColor: '#0f0',
+        links: ['https://shields.io/', 'https://www.google.co.uk/'],
+      })
+    })
+  })
+
+  describe('badges with logos should always produce the same badge', function () {
+    it('badge with logo', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'label',
+        message: 'message',
+        format: 'svg',
+        logo: 'data:image/svg+xml;base64,PHN2ZyB4bWxu',
+      })
+    })
+  })
+
+  describe('text colors', function () {
+    it('should use black text when the label color is light', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+        style: 'flat',
+        color: '#000',
+        labelColor: '#f3f3f3',
+      })
+    })
+
+    it('should use black text when the message color is light', function () {
+      expectBadgeToMatchSnapshot({
+        label: 'cactus',
+        message: 'grown',
+        format: 'svg',
+        style: 'for-the-badge',
+        color: '#e2ffe1',
+        labelColor: '#000',
+      })
+    })
+  })
+})

badge-maker/lib/xml.js

@@ -0,0 +1,76 @@
+/**
+ * @module
+ */
+
+'use strict'
+
+function stripXmlWhitespace(xml) {
+  return xml.replace(/>\s+/g, '>').replace(/<\s+/g, '<').trim()
+}
+
+function escapeXml(s) {
+  if (typeof s === 'number') {
+    return s
+  } else if (s === undefined || typeof s !== 'string') {
+    return undefined
+  } else {
+    return s
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&apos;')
+  }
+}
+
+/**
+ * Representation of an XML element
+ */
+class XmlElement {
+  /**
+   * Xml Element Constructor
+   *
+   * @param {object} attrs Refer to individual attrs
+   * @param {string} attrs.name
+   *    Name of the XML tag
+   * @param {Array.<string|module:badge-maker/lib/xml-element~XmlElement>} [attrs.content=[]]
+   *    Array of objects to render inside the tag. content may contain a mix of
+   *    string and XmlElement objects. If content is `[]` or ommitted the
+   *    element will be rendered as a self-closing element.
+   * @param {object} [attrs.attrs={}]
+   *    Object representing the tag's attributes as name/value pairs
+   */
+  constructor({ name, content = [], attrs = {} }) {
+    this.name = name
+    this.content = content
+    this.attrs = attrs
+  }
+
+  /**
+   * Render the XML element to a string, applying appropriate escaping
+   *
+   * @returns {string} String representation of the XML element
+   */
+  render() {
+    const attrsStr = Object.entries(this.attrs)
+      .map(([k, v]) => ` ${k}="${escapeXml(v)}"`)
+      .join('')
+    if (this.content.length > 0) {
+      const content = this.content
+        .map(function (el) {
+          if (el instanceof XmlElement) {
+            return el.render()
+          } else {
+            return escapeXml(el)
+          }
+        })
+        .join(' ')
+      return stripXmlWhitespace(
+        `<${this.name}${attrsStr}>${content}</${this.name}>`
+      )
+    }
+    return stripXmlWhitespace(`<${this.name}${attrsStr}/>`)
+  }
+}
+
+module.exports = { escapeXml, stripXmlWhitespace, XmlElement }

badge-maker/lib/xml.spec.js

@@ -0,0 +1,50 @@
+'use strict'
+
+const { test, given } = require('sazerac')
+const { XmlElement } = require('./xml')
+
+function testRender(params) {
+  return new XmlElement(params).render()
+}
+
+describe('XmlElement class', function () {
+  test(testRender, () => {
+    given({ name: 'tag' }).expect('<tag/>')
+
+    given({ name: 'tag', content: ['text'] }).expect('<tag>text</tag>')
+
+    given({
+      name: 'tag',
+      content: ['not xml>>>', 'text', new XmlElement({ name: 'xml' })],
+    }).expect('<tag>not xml&gt;&gt;&gt; text <xml/></tag>')
+
+    given({
+      name: 'nested1',
+      content: [
+        new XmlElement({
+          name: 'nested2',
+          content: [new XmlElement({ name: 'nested3' })],
+        }),
+      ],
+    }).expect('<nested1><nested2><nested3/></nested2></nested1>')
+
+    given({
+      name: 'tag',
+      attrs: {
+        int: 47,
+        text: 'text',
+        escape: '<escape me>',
+      },
+    }).expect('<tag int="47" text="text" escape="&lt;escape me&gt;"/>')
+
+    given({
+      name: 'tag',
+      content: ['text'],
+      attrs: {
+        int: 47,
+        text: 'text',
+        escape: '<escape me>',
+      },
+    }).expect('<tag int="47" text="text" escape="&lt;escape me&gt;">text</tag>')
+  })
+})

badge-maker/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "badge-maker",
+  "version": "3.3.0",
+  "description": "Shields.io badge library",
+  "keywords": [
+    "GitHub",
+    "badge",
+    "SVG",
+    "image",
+    "shields.io"
+  ],
+  "types": "index.d.ts",
+  "main": "lib/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/badges/shields.git",
+    "directory": "badge-maker"
+  },
+  "author": "Thaddée Tyl <thaddee.tyl@gmail.com>",
+  "license": "CC0-1.0",
+  "bugs": {
+    "url": "https://github.com/badges/shields/issues"
+  },
+  "homepage": "http://shields.io",
+  "bin": {
+    "badge": "lib/badge-cli.js"
+  },
+  "engines": {
+    "node": ">= 10",
+    "npm": ">= 5"
+  },
+  "collective": {
+    "type": "opencollective",
+    "url": "https://opencollective.com/shields",
+    "logo": "https://opencollective.com/opencollective/logo.txt"
+  },
+  "dependencies": {
+    "anafanafo": "2.0.0",
+    "css-color-converter": "^2.0.0"
+  },
+  "scripts": {
+    "test": "echo 'Run tests from parent dir'; false"
+  }
+}

benchmark-performance.sh

@@ -1,11 +0,0 @@
-#!/bin/sh
-
-PROFILE_MAKE_BADGE=1 node server 1111 >perftest.log &
-sleep 2
-for ((i=0;i<10000;i++)); do
-  curl -s http://localhost:1111/badge/coverage-"$i"%-green.svg >/dev/null
-done
-kill $(jobs -p)
-<perftest.log grep 'makeBadge total' | \
-  grep -Eo '[0-9\.]+' | \
-  awk '{s+=$1;n++} END {print s/n}'

config/custom-environment-variables.yml

@@ -0,0 +1,98 @@
+public:
+  bind:
+    address: 'BIND_ADDRESS'
+    port: 'PORT'
+
+  metrics:
+    prometheus:
+      enabled: 'METRICS_PROMETHEUS_ENABLED'
+      endpointEnabled: 'METRICS_PROMETHEUS_ENDPOINT_ENABLED'
+    influx:
+      enabled: 'METRICS_INFLUX_ENABLED'
+      url: 'METRICS_INFLUX_URL'
+      timeoutMilliseconds: 'METRICS_INFLUX_TIMEOUT_MILLISECONDS'
+      intervalSeconds: 'METRICS_INFLUX_INTERVAL_SECONDS'
+      instanceIdFrom: 'METRICS_INFLUX_INSTANCE_ID_FROM'
+      instanceIdEnvVarName: 'METRICS_INFLUX_INSTANCE_ID_ENV_VAR_NAME'
+      envLabel: 'METRICS_INFLUX_ENV_LABEL'
+
+  ssl:
+    isSecure: 'HTTPS'
+    key: 'HTTPS_KEY'
+    cert: 'HTTPS_CRT'
+
+  redirectUrl: 'REDIRECT_URI'
+
+  rasterUrl: 'RASTER_URL'
+
+  cors:
+    allowedOrigin:
+      __name: 'ALLOWED_ORIGIN'
+      __format: 'json'
+
+  services:
+    bitbucketServer:
+      authorizedOrigins: 'BITBUCKET_SERVER_ORIGINS'
+    drone:
+      authorizedOrigins: 'DRONE_ORIGINS'
+    github:
+      baseUri: 'GITHUB_URL'
+      debug:
+        enabled: 'GITHUB_DEBUG_ENABLED'
+        intervalSeconds: 'GITHUB_DEBUG_INTERVAL_SECONDS'
+    jenkins:
+      authorizedOrigins: 'JENKINS_ORIGINS'
+    jira:
+      authorizedOrigins: 'JIRA_ORIGINS'
+    nexus:
+      authorizedOrigins: 'NEXUS_ORIGINS'
+    npm:
+      authorizedOrigins: 'NPM_ORIGINS'
+    sonar:
+      authorizedOrigins: 'SONAR_ORIGINS'
+    teamcity:
+      authorizedOrigins: 'TEAMCITY_ORIGINS'
+    trace: 'TRACE_SERVICES'
+
+  cacheHeaders:
+    defaultCacheLengthSeconds: 'BADGE_MAX_AGE_SECONDS'
+
+  fetchLimit: 'FETCH_LIMIT'
+
+  requestTimeoutSeconds: 'REQUEST_TIMEOUT_SECONDS'
+  requestTimeoutMaxAgeSeconds: 'REQUEST_TIMEOUT_MAX_AGE_SECONDS'
+
+  requireCloudflare: 'REQUIRE_CLOUDFLARE'
+
+private:
+  azure_devops_token: 'AZURE_DEVOPS_TOKEN'
+  bitbucket_username: 'BITBUCKET_USER'
+  bitbucket_password: 'BITBUCKET_PASS'
+  bitbucket_server_username: 'BITBUCKET_SERVER_USER'
+  bitbucket_server_password: 'BITBUCKET_SERVER_PASS'
+  discord_bot_token: 'DISCORD_BOT_TOKEN'
+  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'
+  redis_url: 'REDIS_URL'
+  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'
+  teamcity_user: 'TEAMCITY_USER'
+  teamcity_pass: 'TEAMCITY_PASS'
+  twitch_client_id: 'TWITCH_CLIENT_ID'
+  twitch_client_secret: 'TWITCH_CLIENT_SECRET'
+  wheelmap_token: 'WHEELMAP_TOKEN'
+  influx_username: 'INFLUX_USERNAME'
+  influx_password: 'INFLUX_PASSWORD'
+  youtube_api_key: 'YOUTUBE_API_KEY'

config/default.yml

@@ -0,0 +1,39 @@
+public:
+  bind:
+    address: '::'
+
+  metrics:
+    prometheus:
+      enabled: false
+      endpointEnabled: false
+    influx:
+      enabled: false
+      timeoutMilliseconds: 1000
+      intervalSeconds: 15
+  ssl:
+    isSecure: false
+
+  cors:
+    allowedOrigin: []
+
+  services:
+    github:
+      baseUri: 'https://api.github.com/'
+      debug:
+        enabled: false
+        intervalSeconds: 200
+    trace: false
+
+  cacheHeaders:
+    defaultCacheLengthSeconds: 120
+
+  handleInternalErrors: true
+
+  fetchLimit: '10MB'
+
+  requestTimeoutSeconds: 120
+  requestTimeoutMaxAgeSeconds: 30
+
+  requireCloudflare: false
+
+private: {}

config/development.yml

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

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

@@ -0,0 +1,14 @@
+private:
+  # These are the keys which are set on the production servers.
+  discord_bot_token: ...
+  gh_client_id: ...
+  gh_client_secret: ...
+  redis_url: ...
+  sentry_dsn: ...
+  shields_secret: ...
+  sl_insight_userUuid: ...
+  sl_insight_apiToken: ...
+  twitch_client_id: ...
+  twitch_client_secret: ...
+  wheelmap_token: ...
+  youtube_api_key: ...

config/local.template.yml

@@ -0,0 +1,11 @@
+# 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: '...'
+  twitch_client_id: '...'
+  twitch_client_secret: '...'
+  wheelmap_token: '...'
+  youtube_api_key: '...'

config/production.yml

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

config/shields-io-production.yml

@@ -0,0 +1,18 @@
+public:
+  metrics:
+    prometheus:
+      enabled: true
+    influx:
+      enabled: true
+      url: https://metrics.shields.io/telegraf
+      instanceIdFrom: env-var
+      instanceIdEnvVarName: HEROKU_DYNO_ID
+      envLabel: shields-production
+
+  ssl:
+    isSecure: true
+
+  cors:
+    allowedOrigin: ['http://shields.io', 'https://shields.io']
+
+  rasterUrl: 'https://raster.shields.io'

config/test.yml

@@ -0,0 +1,10 @@
+public:
+  bind:
+    address: 'localhost'
+    port: 1111
+
+  redirectUrl: 'http://frontend.example.test'
+
+  rasterUrl: 'http://raster.example.test'
+
+  handleInternalErrors: false

core/badge-urls/make-badge-url.d.ts

@@ -0,0 +1,112 @@
+export function badgeUrlFromPath({
+  baseUrl,
+  path,
+  queryParams,
+  style,
+  format,
+  longCache,
+}: {
+  baseUrl?: string
+  path: string
+  queryParams: { [k: string]: string | number | boolean }
+  style?: string
+  format?: string
+  longCache?: boolean
+}): string
+
+export function badgeUrlFromPattern({
+  baseUrl,
+  pattern,
+  namedParams,
+  queryParams,
+  style,
+  format,
+  longCache,
+}: {
+  baseUrl?: string
+  pattern: string
+  namedParams: { [k: string]: string }
+  queryParams: { [k: string]: string | number | boolean }
+  style?: string
+  format?: string
+  longCache?: boolean
+}): string
+
+export function encodeField(s: string): string
+
+export function staticBadgeUrl({
+  baseUrl,
+  label,
+  message,
+  labelColor,
+  color,
+  style,
+  namedLogo,
+  format,
+  links,
+}: {
+  baseUrl?: string
+  label: string
+  message: string
+  labelColor?: string
+  color?: string
+  style?: string
+  namedLogo?: string
+  format?: string
+  links?: string[]
+}): string
+
+export function queryStringStaticBadgeUrl({
+  baseUrl,
+  label,
+  message,
+  color,
+  labelColor,
+  style,
+  namedLogo,
+  logoColor,
+  logoWidth,
+  logoPosition,
+  format,
+}: {
+  baseUrl?: string
+  label: string
+  message: string
+  color?: string
+  labelColor?: string
+  style?: string
+  namedLogo?: string
+  logoColor?: string
+  logoWidth?: number
+  logoPosition?: number
+  format?: string
+}): string
+
+export function dynamicBadgeUrl({
+  baseUrl,
+  datatype,
+  label,
+  dataUrl,
+  query,
+  prefix,
+  suffix,
+  color,
+  style,
+  format,
+}: {
+  baseUrl?: string
+  datatype: string
+  label: string
+  dataUrl: string
+  query: string
+  prefix: string
+  suffix: string
+  color?: string
+  style?: string
+  format?: string
+}): string
+
+export function rasterRedirectUrl(
+  { rasterUrl }: { rasterUrl: string },
+  badgeUrl: string
+): string

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

@@ -0,0 +1,164 @@
+'use strict'
+
+const { URL } = require('url')
+const queryString = require('query-string')
+const { compile } = require('path-to-regexp')
+
+function badgeUrlFromPath({
+  baseUrl = '',
+  path,
+  queryParams,
+  style,
+  format = '',
+  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 = '',
+  longCache = false,
+}) {
+  const toPath = compile(pattern, {
+    strict: true,
+    sensitive: true,
+    encode: encodeURIComponent,
+  })
+
+  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,
+  labelColor,
+  color = 'lightgray',
+  style,
+  namedLogo,
+  format = '',
+  links = [],
+}) {
+  const path = [label, message, color].map(encodeField).join('-')
+  const outQueryString = queryString.stringify({
+    labelColor,
+    style,
+    logo: namedLogo,
+    link: links,
+  })
+  const outExt = format.length ? `.${format}` : ''
+  const suffix = outQueryString ? `?${outQueryString}` : ''
+  return `${baseUrl}/badge/${path}${outExt}${suffix}`
+}
+
+function queryStringStaticBadgeUrl({
+  baseUrl = '',
+  label,
+  message,
+  color,
+  labelColor,
+  style,
+  namedLogo,
+  logoColor,
+  logoWidth,
+  logoPosition,
+  format = '',
+}) {
+  // 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,
+  })}`
+  const outExt = format.length ? `.${format}` : ''
+  return `${baseUrl}/static/v${schemaVersion}${outExt}${suffix}`
+}
+
+function dynamicBadgeUrl({
+  baseUrl,
+  datatype,
+  label,
+  dataUrl,
+  query,
+  prefix,
+  suffix,
+  color,
+  style,
+  format = '',
+}) {
+  const outExt = format.length ? `.${format}` : ''
+
+  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}${outExt}?${outQueryString}`
+}
+
+function rasterRedirectUrl({ rasterUrl }, badgeUrl) {
+  // Ensure we're always using the `rasterUrl` by using just the path from
+  // the request URL.
+  const { pathname, search } = new URL(badgeUrl, 'https://bogus.test')
+  const result = new URL(pathname, rasterUrl)
+  result.search = search
+  return result
+}
+
+module.exports = {
+  badgeUrlFromPath,
+  badgeUrlFromPattern,
+  encodeField,
+  staticBadgeUrl,
+  queryStringStaticBadgeUrl,
+  dynamicBadgeUrl,
+  rasterRedirectUrl,
+}

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

@@ -0,0 +1,157 @@
+'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?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?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?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'
+    )
+    given({
+      label: '123-123',
+      message: 'abc-abc',
+      color: 'blue',
+    }).expect('/badge/123--123-abc--abc-blue')
+    given({
+      label: '123-123',
+      message: '',
+      color: 'blue',
+      style: 'social',
+    }).expect('/badge/123--123--blue?style=social')
+    given({
+      label: '',
+      message: 'blue',
+      color: 'blue',
+    }).expect('/badge/-blue-blue')
+  })
+
+  test(queryStringStaticBadgeUrl, () => {
+    // the query-string library sorts parameters by name
+    given({
+      label: 'foo',
+      message: 'bar',
+      color: 'blue',
+      style: 'flat-square',
+    }).expect('/static/v1?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?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',
+        '?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',
+        '?color=blue',
+        '&label=foo',
+        `&query=${encodeURIComponent(query)}`,
+        '&style=plastic',
+        `&suffix=${encodeURIComponent(suffix)}`,
+        `&url=${encodeURIComponent(dataUrl)}`,
+      ].join('')
+    )
+  })
+})

core/badge-urls/path-helpers.js

@@ -0,0 +1,18 @@
+'use strict'
+
+// Escapes `t` using the format specified in
+// <https://github.com/espadrine/gh-badges/issues/12#issuecomment-31518129>
+function escapeFormat(t) {
+  return (
+    t
+      // Single underscore.
+      .replace(/(^|[^_])((?:__)*)_(?!_)/g, '$1$2 ')
+      // Double underscore and double dash.
+      .replace(/__/g, '_')
+      .replace(/--/g, '-')
+  )
+}
+
+module.exports = {
+  escapeFormat,
+}

core/badge-urls/path-helpers.spec.js

@@ -0,0 +1,21 @@
+'use strict'
+
+const { test, given } = require('sazerac')
+const { escapeFormat } = require('./path-helpers')
+
+describe('Badge URL helper functions', function () {
+  test(escapeFormat, () => {
+    given('_single leading underscore').expect(' single leading underscore')
+    given('single trailing underscore_').expect('single trailing underscore ')
+    given('__double leading underscores').expect('_double leading underscores')
+    given('double trailing underscores__').expect(
+      'double trailing underscores_'
+    )
+    given('treble___underscores').expect('treble_ underscores')
+    given('fourfold____underscores').expect('fourfold__underscores')
+    given('double--dashes').expect('double-dashes')
+    given('treble---dashes').expect('treble--dashes')
+    given('fourfold----dashes').expect('fourfold--dashes')
+    given('once_in_a_blue--moon').expect('once in a blue-moon')
+  })
+})

core/base-service/auth-helper.js

@@ -0,0 +1,210 @@
+'use strict'
+
+const { URL } = require('url')
+const { InvalidParameter } = require('./errors')
+
+class AuthHelper {
+  constructor(
+    {
+      userKey,
+      passKey,
+      authorizedOrigins,
+      serviceKey,
+      isRequired = false,
+      defaultToEmptyStringForUser = false,
+    },
+    config
+  ) {
+    if (!userKey && !passKey) {
+      throw Error('Expected userKey or passKey to be set')
+    }
+
+    if (!authorizedOrigins && !serviceKey) {
+      throw Error('Expected authorizedOrigins or serviceKey to be set')
+    }
+
+    this._userKey = userKey
+    this._passKey = passKey
+    if (userKey) {
+      this._user = config.private[userKey]
+    } else {
+      this._user = defaultToEmptyStringForUser ? '' : undefined
+    }
+    this._pass = passKey ? config.private[passKey] : undefined
+    this.isRequired = isRequired
+
+    if (serviceKey !== undefined && !(serviceKey in config.public.services)) {
+      // Keep this as its own error, as it's useful to the programmer as they're
+      // getting auth set up.
+      throw Error(`Service key ${serviceKey} was missing from config schema`)
+    }
+
+    let requireStrictSsl, requireStrictSslToAuthenticate
+    if (serviceKey === undefined) {
+      requireStrictSsl = true
+      requireStrictSslToAuthenticate = true
+    } else {
+      ;({
+        authorizedOrigins,
+        requireStrictSsl = true,
+        requireStrictSslToAuthenticate = true,
+      } = config.public.services[serviceKey])
+    }
+    if (!Array.isArray(authorizedOrigins)) {
+      throw Error('Expected authorizedOrigins to be an array of origins')
+    }
+    this._authorizedOrigins = authorizedOrigins
+    this._requireStrictSsl = requireStrictSsl
+    this._requireStrictSslToAuthenticate = requireStrictSslToAuthenticate
+  }
+
+  get isConfigured() {
+    return (
+      this._authorizedOrigins.length > 0 &&
+      (this._userKey ? Boolean(this._user) : true) &&
+      (this._passKey ? Boolean(this._pass) : true)
+    )
+  }
+
+  get isValid() {
+    if (this.isRequired) {
+      return this.isConfigured
+    } else {
+      const configIsEmpty = !this._user && !this._pass
+      return this.isConfigured || configIsEmpty
+    }
+  }
+
+  static _isInsecureSslRequest({ options = {} }) {
+    const { strictSSL = true } = options
+    return strictSSL !== true
+  }
+
+  enforceStrictSsl({ options = {} }) {
+    if (
+      this._requireStrictSsl &&
+      this.constructor._isInsecureSslRequest({ options })
+    ) {
+      throw new InvalidParameter({ prettyMessage: 'strict ssl is required' })
+    }
+  }
+
+  shouldAuthenticateRequest({ url, options = {} }) {
+    let parsed
+    try {
+      parsed = new URL(url)
+    } catch (e) {
+      throw new InvalidParameter({ prettyMessage: 'invalid url parameter' })
+    }
+
+    const { protocol, host } = parsed
+    const origin = `${protocol}//${host}`
+    const originViolation = !this._authorizedOrigins.includes(origin)
+
+    const strictSslCheckViolation =
+      this._requireStrictSslToAuthenticate &&
+      this.constructor._isInsecureSslRequest({ options })
+
+    return this.isConfigured && !originViolation && !strictSslCheckViolation
+  }
+
+  get _basicAuth() {
+    const { _user: user, _pass: pass } = this
+    return this.isConfigured ? { user, pass } : undefined
+  }
+
+  /*
+   * Helper function for `withBasicAuth()` and friends.
+   */
+  _withAnyAuth(requestParams, mergeAuthFn) {
+    this.enforceStrictSsl(requestParams)
+
+    const shouldAuthenticate = this.shouldAuthenticateRequest(requestParams)
+    if (this.isRequired && !shouldAuthenticate) {
+      throw new InvalidParameter({
+        prettyMessage: 'requested origin not authorized',
+      })
+    }
+
+    return shouldAuthenticate ? mergeAuthFn(requestParams) : requestParams
+  }
+
+  static _mergeAuth(requestParams, auth) {
+    const { options, ...rest } = requestParams
+    return {
+      options: {
+        auth,
+        ...options,
+      },
+      ...rest,
+    }
+  }
+
+  withBasicAuth(requestParams) {
+    return this._withAnyAuth(requestParams, requestParams =>
+      this.constructor._mergeAuth(requestParams, this._basicAuth)
+    )
+  }
+
+  _bearerAuthHeader(bearerKey) {
+    const { _pass: pass } = this
+    return this.isConfigured
+      ? { Authorization: `${bearerKey} ${pass}` }
+      : undefined
+  }
+
+  static _mergeHeaders(requestParams, headers) {
+    const {
+      options: { headers: existingHeaders, ...restOptions } = {},
+      ...rest
+    } = requestParams
+    return {
+      options: {
+        headers: {
+          ...existingHeaders,
+          ...headers,
+        },
+        ...restOptions,
+      },
+      ...rest,
+    }
+  }
+
+  withBearerAuthHeader(
+    requestParams,
+    bearerKey = 'Bearer' // lgtm [js/hardcoded-credentials]
+  ) {
+    return this._withAnyAuth(requestParams, requestParams =>
+      this.constructor._mergeHeaders(
+        requestParams,
+        this._bearerAuthHeader(bearerKey)
+      )
+    )
+  }
+
+  static _mergeQueryParams(requestParams, query) {
+    const { options: { qs: existingQuery, ...restOptions } = {}, ...rest } =
+      requestParams
+    return {
+      options: {
+        qs: {
+          ...existingQuery,
+          ...query,
+        },
+        ...restOptions,
+      },
+      ...rest,
+    }
+  }
+
+  withQueryStringAuth({ userKey, passKey }, requestParams) {
+    return this._withAnyAuth(requestParams, requestParams =>
+      this.constructor._mergeQueryParams(requestParams, {
+        ...(userKey ? { [userKey]: this._user } : undefined),
+        ...(passKey ? { [passKey]: this._pass } : undefined),
+      })
+    )
+  }
+}
+
+module.exports = { AuthHelper }

core/base-service/auth-helper.spec.js

@@ -0,0 +1,376 @@
+'use strict'
+
+const { expect } = require('chai')
+const { test, given, forCases } = require('sazerac')
+const { AuthHelper } = require('./auth-helper')
+const { InvalidParameter } = require('./errors')
+
+describe('AuthHelper', function () {
+  describe('constructor checks', function () {
+    it('throws without userKey or passKey', function () {
+      expect(() => new AuthHelper({}, {})).to.throw(
+        Error,
+        'Expected userKey or passKey to be set'
+      )
+    })
+    it('throws without serviceKey or authorizedOrigins', function () {
+      expect(
+        () => new AuthHelper({ userKey: 'myci_user', passKey: 'myci_pass' }, {})
+      ).to.throw(Error, 'Expected authorizedOrigins or serviceKey to be set')
+    })
+    it('throws when authorizedOrigins is not an array', function () {
+      expect(
+        () =>
+          new AuthHelper(
+            {
+              userKey: 'myci_user',
+              passKey: 'myci_pass',
+              authorizedOrigins: true,
+            },
+            { private: {} }
+          )
+      ).to.throw(Error, 'Expected authorizedOrigins to be an array of origins')
+    })
+  })
+
+  describe('isValid', function () {
+    function validate(config, privateConfig) {
+      return new AuthHelper(
+        { authorizedOrigins: ['https://example.test'], ...config },
+        { private: privateConfig }
+      ).isValid
+    }
+    test(validate, () => {
+      forCases([
+        // Fully configured user + pass.
+        given(
+          { userKey: 'myci_user', passKey: 'myci_pass', isRequired: true },
+          { myci_user: 'admin', myci_pass: 'abc123' }
+        ),
+        given(
+          { userKey: 'myci_user', passKey: 'myci_pass' },
+          { myci_user: 'admin', myci_pass: 'abc123' }
+        ),
+        // Fully configured user or pass.
+        given(
+          { userKey: 'myci_user', isRequired: true },
+          { myci_user: 'admin' }
+        ),
+        given(
+          { passKey: 'myci_pass', isRequired: true },
+          { myci_pass: 'abc123' }
+        ),
+        given({ userKey: 'myci_user' }, { myci_user: 'admin' }),
+        given({ passKey: 'myci_pass' }, { myci_pass: 'abc123' }),
+        // Empty config.
+        given({ userKey: 'myci_user', passKey: 'myci_pass' }, {}),
+        given({ userKey: 'myci_user' }, {}),
+        given({ passKey: 'myci_pass' }, {}),
+      ]).expect(true)
+
+      forCases([
+        // Partly configured.
+        given(
+          { userKey: 'myci_user', passKey: 'myci_pass', isRequired: true },
+          { myci_user: 'admin' }
+        ),
+        given(
+          { userKey: 'myci_user', passKey: 'myci_pass' },
+          { myci_user: 'admin' }
+        ),
+        // Missing required config.
+        given(
+          { userKey: 'myci_user', passKey: 'myci_pass', isRequired: true },
+          {}
+        ),
+        given({ userKey: 'myci_user', isRequired: true }, {}),
+        given({ passKey: 'myci_pass', isRequired: true }, {}),
+      ]).expect(false)
+    })
+  })
+
+  describe('_basicAuth', function () {
+    function validate(config, privateConfig) {
+      return new AuthHelper(
+        { authorizedOrigins: ['https://example.test'], ...config },
+        { private: privateConfig }
+      )._basicAuth
+    }
+    test(validate, () => {
+      forCases([
+        given(
+          { userKey: 'myci_user', passKey: 'myci_pass', isRequired: true },
+          { myci_user: 'admin', myci_pass: 'abc123' }
+        ),
+        given(
+          { userKey: 'myci_user', passKey: 'myci_pass' },
+          { myci_user: 'admin', myci_pass: 'abc123' }
+        ),
+      ]).expect({ user: 'admin', pass: 'abc123' })
+      given({ userKey: 'myci_user' }, { myci_user: 'admin' }).expect({
+        user: 'admin',
+        pass: undefined,
+      })
+      given({ passKey: 'myci_pass' }, { myci_pass: 'abc123' }).expect({
+        user: undefined,
+        pass: 'abc123',
+      })
+      given({ userKey: 'myci_user', passKey: 'myci_pass' }, {}).expect(
+        undefined
+      )
+      given(
+        { passKey: 'myci_pass', defaultToEmptyStringForUser: true },
+        { myci_pass: 'abc123' }
+      ).expect({
+        user: '',
+        pass: 'abc123',
+      })
+    })
+  })
+
+  describe('_isInsecureSslRequest', function () {
+    test(AuthHelper._isInsecureSslRequest, () => {
+      forCases([
+        given({ url: 'http://example.test' }),
+        given({ url: 'http://example.test', options: {} }),
+        given({ url: 'http://example.test', options: { strictSSL: true } }),
+        given({
+          url: 'http://example.test',
+          options: { strictSSL: undefined },
+        }),
+      ]).expect(false)
+      given({
+        url: 'http://example.test',
+        options: { strictSSL: false },
+      }).expect(true)
+    })
+  })
+
+  describe('enforceStrictSsl', function () {
+    const authConfig = {
+      userKey: 'myci_user',
+      passKey: 'myci_pass',
+      serviceKey: 'myci',
+    }
+
+    context('by default', function () {
+      const authHelper = new AuthHelper(authConfig, {
+        public: {
+          services: { myci: { authorizedOrigins: ['http://myci.test'] } },
+        },
+        private: { myci_user: 'admin', myci_pass: 'abc123' },
+      })
+      it('does not throw for secure requests', function () {
+        expect(() => authHelper.enforceStrictSsl({})).not.to.throw()
+      })
+      it('throws for insecure requests', function () {
+        expect(() =>
+          authHelper.enforceStrictSsl({ options: { strictSSL: false } })
+        ).to.throw(InvalidParameter)
+      })
+    })
+
+    context("when strict SSL isn't required", function () {
+      const authHelper = new AuthHelper(authConfig, {
+        public: {
+          services: {
+            myci: {
+              authorizedOrigins: ['http://myci.test'],
+              requireStrictSsl: false,
+            },
+          },
+        },
+        private: { myci_user: 'admin', myci_pass: 'abc123' },
+      })
+      it('does not throw for secure requests', function () {
+        expect(() => authHelper.enforceStrictSsl({})).not.to.throw()
+      })
+      it('does not throw for insecure requests', function () {
+        expect(() =>
+          authHelper.enforceStrictSsl({ options: { strictSSL: false } })
+        ).not.to.throw()
+      })
+    })
+  })
+
+  describe('shouldAuthenticateRequest', function () {
+    const authConfig = {
+      userKey: 'myci_user',
+      passKey: 'myci_pass',
+      serviceKey: 'myci',
+    }
+
+    context('by default', function () {
+      const authHelper = new AuthHelper(authConfig, {
+        public: {
+          services: {
+            myci: {
+              authorizedOrigins: ['https://myci.test'],
+            },
+          },
+        },
+        private: { myci_user: 'admin', myci_pass: 'abc123' },
+      })
+      const shouldAuthenticateRequest = requestOptions =>
+        authHelper.shouldAuthenticateRequest(requestOptions)
+      describe('a secure request to an authorized origin', function () {
+        test(shouldAuthenticateRequest, () => {
+          given({ url: 'https://myci.test/api' }).expect(true)
+        })
+      })
+      describe('an insecure request', function () {
+        test(shouldAuthenticateRequest, () => {
+          given({
+            url: 'https://myci.test/api',
+            options: { strictSSL: false },
+          }).expect(false)
+        })
+      })
+      describe('a request to an unauthorized origin', function () {
+        test(shouldAuthenticateRequest, () => {
+          forCases([
+            given({ url: 'http://myci.test/api' }),
+            given({ url: 'https://myci.test:12345/api' }),
+            given({ url: 'https://other.test/api' }),
+          ]).expect(false)
+        })
+      })
+    })
+
+    context('when auth over insecure SSL is allowed', function () {
+      const authHelper = new AuthHelper(authConfig, {
+        public: {
+          services: {
+            myci: {
+              authorizedOrigins: ['https://myci.test'],
+              requireStrictSslToAuthenticate: false,
+            },
+          },
+        },
+        private: { myci_user: 'admin', myci_pass: 'abc123' },
+      })
+      const shouldAuthenticateRequest = requestOptions =>
+        authHelper.shouldAuthenticateRequest(requestOptions)
+      describe('a secure request to an authorized origin', function () {
+        test(shouldAuthenticateRequest, () => {
+          given({ url: 'https://myci.test' }).expect(true)
+        })
+      })
+      describe('an insecure request', function () {
+        test(shouldAuthenticateRequest, () => {
+          given({
+            url: 'https://myci.test',
+            options: { strictSSL: false },
+          }).expect(true)
+        })
+      })
+      describe('a request to an unauthorized origin', function () {
+        test(shouldAuthenticateRequest, () => {
+          forCases([
+            given({ url: 'http://myci.test' }),
+            given({ url: 'https://myci.test:12345/' }),
+            given({ url: 'https://other.test' }),
+          ]).expect(false)
+        })
+      })
+    })
+
+    context('when the service is partly configured', function () {
+      const authHelper = new AuthHelper(authConfig, {
+        public: {
+          services: {
+            myci: {
+              authorizedOrigins: ['https://myci.test'],
+              requireStrictSslToAuthenticate: false,
+            },
+          },
+        },
+        private: { myci_user: 'admin' },
+      })
+      const shouldAuthenticateRequest = requestOptions =>
+        authHelper.shouldAuthenticateRequest(requestOptions)
+      describe('a secure request to an authorized origin', function () {
+        test(shouldAuthenticateRequest, () => {
+          given({ url: 'https://myci.test' }).expect(false)
+        })
+      })
+    })
+  })
+
+  describe('withBasicAuth', function () {
+    const authHelper = new AuthHelper(
+      {
+        userKey: 'myci_user',
+        passKey: 'myci_pass',
+        serviceKey: 'myci',
+      },
+      {
+        public: {
+          services: {
+            myci: {
+              authorizedOrigins: ['https://myci.test'],
+            },
+          },
+        },
+        private: { myci_user: 'admin', myci_pass: 'abc123' },
+      }
+    )
+    const withBasicAuth = requestOptions =>
+      authHelper.withBasicAuth(requestOptions)
+
+    describe('authenticates a secure request to an authorized origin', function () {
+      test(withBasicAuth, () => {
+        given({
+          url: 'https://myci.test/api',
+        }).expect({
+          url: 'https://myci.test/api',
+          options: {
+            auth: { user: 'admin', pass: 'abc123' },
+          },
+        })
+        given({
+          url: 'https://myci.test/api',
+          options: {
+            headers: { Accept: 'application/json' },
+          },
+        }).expect({
+          url: 'https://myci.test/api',
+          options: {
+            headers: { Accept: 'application/json' },
+            auth: { user: 'admin', pass: 'abc123' },
+          },
+        })
+      })
+    })
+
+    describe('does not authenticate a request to an unauthorized origin', function () {
+      test(withBasicAuth, () => {
+        given({
+          url: 'https://other.test/api',
+        }).expect({
+          url: 'https://other.test/api',
+        })
+        given({
+          url: 'https://other.test/api',
+          options: {
+            headers: { Accept: 'application/json' },
+          },
+        }).expect({
+          url: 'https://other.test/api',
+          options: {
+            headers: { Accept: 'application/json' },
+          },
+        })
+      })
+    })
+
+    describe('throws on an insecure SSL request', function () {
+      expect(() =>
+        withBasicAuth({
+          url: 'https://myci.test/api',
+          options: { strictSSL: false },
+        })
+      ).to.throw(InvalidParameter)
+    })
+  })
+})

core/base-service/base-graphql.js

@@ -0,0 +1,96 @@
+/**
+ * @module
+ */
+
+'use strict'
+
+const { print } = require('graphql/language/printer')
+const BaseService = require('./base')
+const { InvalidResponse, ShieldsRuntimeError } = require('./errors')
+const { parseJson } = require('./json')
+
+function defaultTransformErrors(errors) {
+  return new InvalidResponse({ prettyMessage: errors[0].message })
+}
+
+/**
+ * Services which query a GraphQL endpoint should extend BaseGraphqlService
+ *
+ * @abstract
+ */
+class BaseGraphqlService extends BaseService {
+  /**
+   * Parse data from JSON endpoint
+   *
+   * @param {string} buffer JSON repsonse from upstream API
+   * @returns {object} Parsed response
+   */
+  _parseJson(buffer) {
+    return parseJson(buffer)
+  }
+
+  /**
+   * Request data from an upstream GraphQL API,
+   * parse it and validate against a schema
+   *
+   * @param {object} attrs Refer to individual attrs
+   * @param {Joi} attrs.schema Joi schema to validate the response against
+   * @param {string} attrs.url URL to request
+   * @param {object} attrs.query Parsed GraphQL object
+   *    representing the query clause of GraphQL POST body
+   *    e.g. gql`{ query { ... } }`
+   * @param {object} attrs.variables Variables clause of GraphQL POST body
+   * @param {object} [attrs.options={}] Options to pass to request. See
+   *    [documentation](https://github.com/request/request#requestoptions-callback)
+   * @param {object} [attrs.httpErrorMessages={}] Key-value map of HTTP status codes
+   *    and custom error messages e.g: `{ 404: 'package not found' }`.
+   *    This can be used to extend or override the
+   *    [default](https://github.com/badges/shields/blob/master/core/base-service/check-error-response.js#L5)
+   * @param {Function} [attrs.transformJson=data => data] Function which takes the raw json and transforms it before
+   * further procesing. In case of multiple query in a single graphql call and few of them
+   * throw error, partial data might be used ignoring the error.
+   * @param {Function} [attrs.transformErrors=defaultTransformErrors]
+   *    Function which takes an errors object from a GraphQL
+   *    response and returns an instance of ShieldsRuntimeError.
+   *    The default is to return the first entry of the `errors` array as
+   *    an InvalidResponse.
+   * @returns {object} Parsed response
+   * @see https://github.com/request/request#requestoptions-callback
+   */
+  async _requestGraphql({
+    schema,
+    url,
+    query,
+    variables = {},
+    options = {},
+    httpErrorMessages = {},
+    transformJson = data => data,
+    transformErrors = defaultTransformErrors,
+  }) {
+    const mergedOptions = {
+      ...{ headers: { Accept: 'application/json' } },
+      ...options,
+    }
+    mergedOptions.method = 'POST'
+    mergedOptions.body = JSON.stringify({ query: print(query), variables })
+    const { buffer } = await this._request({
+      url,
+      options: mergedOptions,
+      errorMessages: httpErrorMessages,
+    })
+    const json = transformJson(this._parseJson(buffer))
+    if (json.errors) {
+      const exception = transformErrors(json.errors)
+      if (exception instanceof ShieldsRuntimeError) {
+        throw exception
+      } else {
+        throw Error(
+          `transformErrors() must return a ShieldsRuntimeError; got ${exception}`
+        )
+      }
+    }
+    return this.constructor._validate(json, schema)
+  }
+}
+
+module.exports = BaseGraphqlService

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

@@ -0,0 +1,202 @@
+'use strict'
+
+const Joi = require('joi')
+const { expect } = require('chai')
+const gql = require('graphql-tag')
+const sinon = require('sinon')
+const BaseGraphqlService = require('./base-graphql')
+const { InvalidResponse } = require('./errors')
+
+const dummySchema = Joi.object({
+  requiredString: Joi.string().required(),
+}).required()
+
+class DummyGraphqlService extends BaseGraphqlService {
+  static category = 'cat'
+  static route = { base: 'foo' }
+
+  async handle() {
+    const { requiredString } = await this._requestGraphql({
+      schema: dummySchema,
+      url: 'http://example.com/graphql',
+      query: gql`
+        query {
+          requiredString
+        }
+      `,
+    })
+    return { message: requiredString }
+  }
+}
+
+describe('BaseGraphqlService', function () {
+  describe('Making requests', function () {
+    let sendAndCacheRequest
+    beforeEach(function () {
+      sendAndCacheRequest = sinon.stub().returns(
+        Promise.resolve({
+          buffer: '{"some": "json"}',
+          res: { statusCode: 200 },
+        })
+      )
+    })
+
+    it('invokes _sendAndCacheRequest', async function () {
+      await DummyGraphqlService.invoke(
+        { sendAndCacheRequest },
+        { handleInternalErrors: false }
+      )
+
+      expect(sendAndCacheRequest).to.have.been.calledOnceWith(
+        'http://example.com/graphql',
+        {
+          body: '{"query":"{\\n  requiredString\\n}\\n","variables":{}}',
+          headers: { Accept: 'application/json' },
+          method: 'POST',
+        }
+      )
+    })
+
+    it('forwards options to _sendAndCacheRequest', async function () {
+      class WithOptions extends DummyGraphqlService {
+        async handle() {
+          const { value } = await this._requestGraphql({
+            schema: dummySchema,
+            url: 'http://example.com/graphql',
+            query: gql`
+              query {
+                requiredString
+              }
+            `,
+            options: { qs: { queryParam: 123 } },
+          })
+          return { message: value }
+        }
+      }
+
+      await WithOptions.invoke(
+        { sendAndCacheRequest },
+        { handleInternalErrors: false }
+      )
+
+      expect(sendAndCacheRequest).to.have.been.calledOnceWith(
+        'http://example.com/graphql',
+        {
+          body: '{"query":"{\\n  requiredString\\n}\\n","variables":{}}',
+          headers: { Accept: 'application/json' },
+          method: 'POST',
+          qs: { queryParam: 123 },
+        }
+      )
+    })
+  })
+
+  describe('Making badges', function () {
+    it('handles valid json responses', async function () {
+      const sendAndCacheRequest = async () => ({
+        buffer: '{"requiredString": "some-string"}',
+        res: { statusCode: 200 },
+      })
+      expect(
+        await DummyGraphqlService.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
+        message: 'some-string',
+      })
+    })
+
+    it('handles json responses which do not match the schema', async function () {
+      const sendAndCacheRequest = async () => ({
+        buffer: '{"unexpectedKey": "some-string"}',
+        res: { statusCode: 200 },
+      })
+      expect(
+        await DummyGraphqlService.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
+        isError: true,
+        color: 'lightgray',
+        message: 'invalid response data',
+      })
+    })
+
+    it('handles unparseable json responses', async function () {
+      const sendAndCacheRequest = async () => ({
+        buffer: 'not json',
+        res: { statusCode: 200 },
+      })
+      expect(
+        await DummyGraphqlService.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
+        isError: true,
+        color: 'lightgray',
+        message: 'unparseable json response',
+      })
+    })
+  })
+
+  describe('Error handling', function () {
+    it('handles generic error', async function () {
+      const sendAndCacheRequest = async () => ({
+        buffer: '{ "errors": [ { "message": "oh noes!!" } ] }',
+        res: { statusCode: 200 },
+      })
+      expect(
+        await DummyGraphqlService.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
+        isError: true,
+        color: 'lightgray',
+        message: 'oh noes!!',
+      })
+    })
+
+    it('handles custom error', async function () {
+      class WithErrorHandler extends DummyGraphqlService {
+        async handle() {
+          const { requiredString } = await this._requestGraphql({
+            schema: dummySchema,
+            url: 'http://example.com/graphql',
+            query: gql`
+              query {
+                requiredString
+              }
+            `,
+            transformErrors: function (errors) {
+              if (errors[0].message === 'oh noes!!') {
+                return new InvalidResponse({
+                  prettyMessage: 'a terrible thing has happened',
+                })
+              }
+            },
+          })
+          return { message: requiredString }
+        }
+      }
+
+      const sendAndCacheRequest = async () => ({
+        buffer: '{ "errors": [ { "message": "oh noes!!" } ] }',
+        res: { statusCode: 200 },
+      })
+      expect(
+        await WithErrorHandler.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
+        isError: true,
+        color: 'lightgray',
+        message: 'a terrible thing has happened',
+      })
+    })
+  })
+})

core/base-service/base-json.js

@@ -0,0 +1,57 @@
+/**
+ * @module
+ */
+
+'use strict'
+
+const BaseService = require('./base')
+const { parseJson } = require('./json')
+
+/**
+ * Services which query a JSON endpoint should extend BaseJsonService
+ *
+ * @abstract
+ */
+class BaseJsonService extends BaseService {
+  /**
+   * Parse data from JSON endpoint
+   *
+   * @param {string} buffer JSON repsonse from upstream API
+   * @returns {object} Parsed response
+   */
+  _parseJson(buffer) {
+    return parseJson(buffer)
+  }
+
+  /**
+   * Request data from an upstream API serving JSON,
+   * parse it and validate against a schema
+   *
+   * @param {object} attrs Refer to individual attrs
+   * @param {Joi} attrs.schema Joi schema to validate the response against
+   * @param {string} attrs.url URL to request
+   * @param {object} [attrs.options={}] Options to pass to request. See
+   *    [documentation](https://github.com/request/request#requestoptions-callback)
+   * @param {object} [attrs.errorMessages={}] Key-value map of status codes
+   *    and custom error messages e.g: `{ 404: 'package not found' }`.
+   *    This can be used to extend or override the
+   *    [default](https://github.com/badges/shields/blob/master/core/base-service/check-error-response.js#L5)
+   * @returns {object} Parsed response
+   * @see https://github.com/request/request#requestoptions-callback
+   */
+  async _requestJson({ schema, url, options = {}, errorMessages = {} }) {
+    const mergedOptions = {
+      ...{ headers: { Accept: 'application/json' } },
+      ...options,
+    }
+    const { buffer } = await this._request({
+      url,
+      options: mergedOptions,
+      errorMessages,
+    })
+    const json = this._parseJson(buffer)
+    return this.constructor._validate(json, schema)
+  }
+}
+
+module.exports = BaseJsonService

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

@@ -1,28 +1,17 @@
 '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()
 
 class DummyJsonService extends BaseJsonService {
-  static get category() {
-    return 'cat'
-  }
-
-  static get route() {
-    return {
-      base: 'foo',
-    }
-  }
+  static category = 'cat'
+  static route = { base: 'foo' }
 
   async handle() {
     const { requiredString } = await this._requestJson({
@@ -33,24 +22,23 @@ class DummyJsonService extends BaseJsonService {
   }
 }
 
-describe('BaseJsonService', function() {
-  describe('Making requests', function() {
-    let sendAndCacheRequest, serviceInstance
-    beforeEach(function() {
+describe('BaseJsonService', function () {
+  describe('Making requests', function () {
+    let sendAndCacheRequest
+    beforeEach(function () {
       sendAndCacheRequest = sinon.stub().returns(
         Promise.resolve({
           buffer: '{"some": "json"}',
           res: { statusCode: 200 },
         })
       )
-      serviceInstance = new DummyJsonService(
+    })
+
+    it('invokes _sendAndCacheRequest', async function () {
+      await DummyJsonService.invoke(
         { sendAndCacheRequest },
         { handleInternalErrors: false }
       )
-    })
-
-    it('invokes _sendAndCacheRequest', async function() {
-      await serviceInstance.invokeHandler({}, {})
 
       expect(sendAndCacheRequest).to.have.been.calledOnceWith(
         'http://example.com/foo.json',
@@ -60,8 +48,8 @@ describe('BaseJsonService', function() {
       )
     })
 
-    it('forwards options to _sendAndCacheRequest', async function() {
-      Object.assign(serviceInstance, {
+    it('forwards options to _sendAndCacheRequest', async function () {
+      class WithOptions extends DummyJsonService {
         async handle() {
           const { value } = await this._requestJson({
             schema: dummySchema,
@@ -69,10 +57,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',
@@ -85,49 +76,51 @@ describe('BaseJsonService', function() {
     })
   })
 
-  describe('Making badges', function() {
-    it('handles valid json responses', async function() {
+  describe('Making badges', function () {
+    it('handles valid json responses', async function () {
       const sendAndCacheRequest = async () => ({
         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',
       })
     })
 
-    it('handles json responses which do not match the schema', async function() {
+    it('handles json responses which do not match the schema', async function () {
       const sendAndCacheRequest = async () => ({
         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',
       })
     })
 
-    it('handles unparseable json responses', async function() {
+    it('handles unparseable json responses', async function () {
       const sendAndCacheRequest = async () => ({
         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-static.js

@@ -0,0 +1,60 @@
+'use strict'
+
+const makeBadge = require('../../badge-maker/lib/make-badge')
+const BaseService = require('./base')
+const {
+  serverHasBeenUpSinceResourceCached,
+  setCacheHeadersForStaticResource,
+} = require('./cache-headers')
+const { makeSend } = require('./legacy-result-sender')
+const { MetricHelper } = require('./metric-helper')
+const coalesceBadge = require('./coalesce-badge')
+const { prepareRoute, namedParamsForMatch } = require('./route')
+
+module.exports = class BaseStaticService extends BaseService {
+  static register({ camp, metricInstance }, serviceConfig) {
+    const { regex, captureNames } = prepareRoute(this.route)
+
+    const metricHelper = MetricHelper.create({
+      metricInstance,
+      ServiceClass: this,
+    })
+
+    camp.route(regex, async (queryParams, match, end, ask) => {
+      if (serverHasBeenUpSinceResourceCached(ask.req)) {
+        // Send Not Modified.
+        ask.res.statusCode = 304
+        ask.res.end()
+        return
+      }
+
+      const metricHandle = metricHelper.startRequest()
+
+      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] || '.svg').replace(/^\./, '')
+      badgeData.format = format
+
+      setCacheHeadersForStaticResource(ask.res)
+
+      const svg = makeBadge(badgeData)
+      makeSend(format, ask.res, end)(svg)
+
+      metricHandle.noteResponseSent()
+    })
+  }
+}

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

@@ -1,3 +1,7 @@
+/**
+ * @module
+ */
+
 'use strict'
 
 // See available emoji at http://emoji.muan.co/
@@ -9,10 +13,24 @@ const { InvalidResponse } = require('./errors')
 const defaultValueMatcher = />([^<>]+)<\/text><\/g>/
 const leadingWhitespace = /(?:\r\n\s*|\r\s*|\n\s*)/g
 
+/**
+ * Services which scrape data from another SVG badge
+ * should extend BaseSvgScrapingService
+ *
+ * @abstract
+ */
 class BaseSvgScrapingService extends BaseService {
+  /**
+   * Extract a value from SVG
+   *
+   * @param {string} svg SVG to parse
+   * @param {RegExp} [valueMatcher=defaultValueMatcher]
+   *    RegExp to match the value we want to parse from the SVG
+   * @returns {string} Matched value
+   */
   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)
@@ -26,6 +44,24 @@ class BaseSvgScrapingService extends BaseService {
     }
   }
 
+  /**
+   * Request data from an endpoint serving SVG,
+   * parse a value from it and validate against a schema
+   *
+   * @param {object} attrs Refer to individual attrs
+   * @param {Joi} attrs.schema Joi schema to validate the response against
+   * @param {RegExp} attrs.valueMatcher
+   *    RegExp to match the value we want to parse from the SVG
+   * @param {string} attrs.url URL to request
+   * @param {object} [attrs.options={}] Options to pass to request. See
+   *    [documentation](https://github.com/request/request#requestoptions-callback)
+   * @param {object} [attrs.errorMessages={}] Key-value map of status codes
+   *    and custom error messages e.g: `{ 404: 'package not found' }`.
+   *    This can be used to extend or override the
+   *    [default](https://github.com/badges/shields/blob/master/core/base-service/check-error-response.js#L5)
+   * @returns {object} Parsed response
+   * @see https://github.com/request/request#requestoptions-callback
+   */
   async _requestSvg({
     schema,
     valueMatcher,

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

@@ -1,35 +1,18 @@
 '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 testHelpers = require('../lib/make-badge-test-helpers')
+const makeBadge = require('../../badge-maker/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 testHelpers.makeBadge()(badgeData)
-}
-
 const schema = Joi.object({
   message: Joi.string().required(),
 }).required()
 
 class DummySvgScrapingService extends BaseSvgScrapingService {
-  static get category() {
-    return 'cat'
-  }
-
-  static get route() {
-    return {
-      base: 'foo',
-    }
-  }
+  static category = 'cat'
+  static route = { base: 'foo' }
 
   async handle() {
     return this._requestSvg({
@@ -39,39 +22,35 @@ class DummySvgScrapingService extends BaseSvgScrapingService {
   }
 }
 
-describe('BaseSvgScrapingService', function() {
+describe('BaseSvgScrapingService', function () {
   const exampleLabel = 'this is the label'
   const exampleMessage = 'this is the result!'
-  const exampleSvg = makeExampleSvg({
-    label: exampleLabel,
-    message: exampleMessage,
-  })
+  const exampleSvg = makeBadge({ label: exampleLabel, message: exampleMessage })
 
-  describe('valueFromSvgBadge', function() {
-    it('should find the correct value', function() {
+  describe('valueFromSvgBadge', function () {
+    it('should find the correct value', function () {
       expect(BaseSvgScrapingService.valueFromSvgBadge(exampleSvg)).to.equal(
         exampleMessage
       )
     })
   })
 
-  describe('Making requests', function() {
-    let sendAndCacheRequest, serviceInstance
-    beforeEach(function() {
+  describe('Making requests', function () {
+    let sendAndCacheRequest
+    beforeEach(function () {
       sendAndCacheRequest = sinon.stub().returns(
         Promise.resolve({
           buffer: exampleSvg,
           res: { statusCode: 200 },
         })
       )
-      serviceInstance = new DummySvgScrapingService(
+    })
+
+    it('invokes _sendAndCacheRequest with the expected header', async function () {
+      await DummySvgScrapingService.invoke(
         { sendAndCacheRequest },
         { handleInternalErrors: false }
       )
-    })
-
-    it('invokes _sendAndCacheRequest with the expected header', async function() {
-      await serviceInstance.invokeHandler({}, {})
 
       expect(sendAndCacheRequest).to.have.been.calledOnceWith(
         'http://example.com/foo.svg',
@@ -81,10 +60,10 @@ describe('BaseSvgScrapingService', function() {
       )
     })
 
-    it('forwards options to _sendAndCacheRequest', async function() {
-      Object.assign(serviceInstance, {
+    it('forwards options to _sendAndCacheRequest', async function () {
+      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 +71,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',
@@ -109,57 +91,60 @@ describe('BaseSvgScrapingService', function() {
     })
   })
 
-  describe('Making badges', function() {
-    it('handles valid svg responses', async function() {
+  describe('Making badges', function () {
+    it('handles valid svg responses', async function () {
       const sendAndCacheRequest = async () => ({
         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, {
+    it('allows overriding the valueMatcher', async function () {
+      class WithValueMatcher extends BaseSvgScrapingService {
+        static route = {}
+
         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',
       })
     })
 
-    it('handles unparseable svg responses', async function() {
+    it('handles unparseable svg responses', async function () {
       const sendAndCacheRequest = async () => ({
         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.js

@@ -0,0 +1,71 @@
+/**
+ * @module
+ */
+
+'use strict'
+
+// See available emoji at http://emoji.muan.co/
+const emojic = require('emojic')
+const fastXmlParser = require('fast-xml-parser')
+const BaseService = require('./base')
+const trace = require('./trace')
+const { InvalidResponse } = require('./errors')
+
+/**
+ * Services which query a XML endpoint should extend BaseXmlService
+ *
+ * @abstract
+ */
+class BaseXmlService extends BaseService {
+  /**
+   * Request data from an upstream API serving XML,
+   * parse it and validate against a schema
+   *
+   * @param {object} attrs Refer to individual attrs
+   * @param {Joi} attrs.schema Joi schema to validate the response against
+   * @param {string} attrs.url URL to request
+   * @param {object} [attrs.options={}] Options to pass to request. See
+   *    [documentation](https://github.com/request/request#requestoptions-callback)
+   * @param {object} [attrs.errorMessages={}] Key-value map of status codes
+   *    and custom error messages e.g: `{ 404: 'package not found' }`.
+   *    This can be used to extend or override the
+   *    [default](https://github.com/badges/shields/blob/master/core/base-service/check-error-response.js#L5)
+   * @param {object} [attrs.parserOptions={}] Options to pass to fast-xml-parser. See
+   *    [documentation](https://github.com/NaturalIntelligence/fast-xml-parser#xml-to-json)
+   * @returns {object} Parsed response
+   * @see https://github.com/request/request#requestoptions-callback
+   * @see https://github.com/NaturalIntelligence/fast-xml-parser#xml-to-json
+   */
+  async _requestXml({
+    schema,
+    url,
+    options = {},
+    errorMessages = {},
+    parserOptions = {},
+  }) {
+    const logTrace = (...args) => trace.logTrace('fetch', ...args)
+    const mergedOptions = {
+      ...{ headers: { Accept: 'application/xml, text/xml' } },
+      ...options,
+    }
+    const { buffer } = await this._request({
+      url,
+      options: mergedOptions,
+      errorMessages,
+    })
+    const validateResult = fastXmlParser.validate(buffer)
+    if (validateResult !== true) {
+      throw new InvalidResponse({
+        prettyMessage: 'unparseable xml response',
+        underlyingError: validateResult.err,
+      })
+    }
+    const xml = fastXmlParser.parse(buffer, parserOptions)
+    logTrace(emojic.dart, 'Response XML (before validation)', xml, {
+      deep: true,
+    })
+    return this.constructor._validate(xml, schema)
+  }
+}
+
+module.exports = BaseXmlService

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

@@ -1,28 +1,17 @@
 '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()
 
 class DummyXmlService extends BaseXmlService {
-  static get category() {
-    return 'cat'
-  }
-
-  static get route() {
-    return {
-      base: 'foo',
-    }
-  }
+  static category = 'cat'
+  static route = { base: 'foo' }
 
   async handle() {
     const { requiredString } = await this._requestXml({
@@ -33,24 +22,23 @@ class DummyXmlService extends BaseXmlService {
   }
 }
 
-describe('BaseXmlService', function() {
-  describe('Making requests', function() {
-    let sendAndCacheRequest, serviceInstance
-    beforeEach(function() {
+describe('BaseXmlService', function () {
+  describe('Making requests', function () {
+    let sendAndCacheRequest
+    beforeEach(function () {
       sendAndCacheRequest = sinon.stub().returns(
         Promise.resolve({
           buffer: '<requiredString>some-string</requiredString>',
           res: { statusCode: 200 },
         })
       )
-      serviceInstance = new DummyXmlService(
+    })
+
+    it('invokes _sendAndCacheRequest', async function () {
+      await DummyXmlService.invoke(
         { sendAndCacheRequest },
         { handleInternalErrors: false }
       )
-    })
-
-    it('invokes _sendAndCacheRequest', async function() {
-      await serviceInstance.invokeHandler({}, {})
 
       expect(sendAndCacheRequest).to.have.been.calledOnceWith(
         'http://example.com/foo.xml',
@@ -60,19 +48,24 @@ describe('BaseXmlService', function() {
       )
     })
 
-    it('forwards options to _sendAndCacheRequest', async function() {
-      Object.assign(serviceInstance, {
+    it('forwards options to _sendAndCacheRequest', async function () {
+      class WithCustomOptions extends BaseXmlService {
+        static route = {}
+
         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',
@@ -85,49 +78,78 @@ describe('BaseXmlService', function() {
     })
   })
 
-  describe('Making badges', function() {
-    it('handles valid xml responses', async function() {
+  describe('Making badges', function () {
+    it('handles valid xml responses', async function () {
       const sendAndCacheRequest = async () => ({
         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',
       })
     })
 
-    it('handles xml responses which do not match the schema', async function() {
+    it('parses XML response with custom parser options', async function () {
+      const customParserOption = { trimValues: false }
+      class DummyXmlServiceWithParserOption extends DummyXmlService {
+        async handle() {
+          const { requiredString } = await this._requestXml({
+            schema: dummySchema,
+            url: 'http://example.com/foo.xml',
+            parserOptions: customParserOption,
+          })
+          return { message: requiredString }
+        }
+      }
+      const sendAndCacheRequest = async () => ({
+        buffer:
+          '<requiredString>some-string with trailing whitespace   </requiredString>',
+        res: { statusCode: 200 },
+      })
+      expect(
+        await DummyXmlServiceWithParserOption.invoke(
+          { sendAndCacheRequest },
+          { handleInternalErrors: false }
+        )
+      ).to.deep.equal({
+        message: 'some-string with trailing whitespace   ',
+      })
+    })
+
+    it('handles xml responses which do not match the schema', async function () {
       const sendAndCacheRequest = async () => ({
         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',
       })
     })
 
-    it('handles unparseable xml responses', async function() {
+    it('handles unparseable xml responses', async function () {
       const sendAndCacheRequest = async () => ({
         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,75 @@
+/**
+ * @module
+ */
+
+'use strict'
+
+const emojic = require('emojic')
+const yaml = require('js-yaml')
+const BaseService = require('./base')
+const { InvalidResponse } = require('./errors')
+const trace = require('./trace')
+
+/**
+ * Services which query a YAML endpoint should extend BaseYamlService
+ *
+ * @abstract
+ */
+class BaseYamlService extends BaseService {
+  /**
+   * Request data from an upstream API serving YAML,
+   * parse it and validate against a schema
+   *
+   * @param {object} attrs Refer to individual attrs
+   * @param {Joi} attrs.schema Joi schema to validate the response against
+   * @param {string} attrs.url URL to request
+   * @param {object} [attrs.options={}] Options to pass to request. See
+   *    [documentation](https://github.com/request/request#requestoptions-callback)
+   * @param {object} [attrs.errorMessages={}] Key-value map of status codes
+   *    and custom error messages e.g: `{ 404: 'package not found' }`.
+   *    This can be used to extend or override the
+   *    [default](https://github.com/badges/shields/blob/master/core/base-service/check-error-response.js#L5)
+   * @param {object} [attrs.encoding='utf8'] Character encoding
+   * @returns {object} Parsed response
+   * @see https://github.com/request/request#requestoptions-callback
+   */
+  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.load(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,151 @@
+'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 category = 'cat'
+  static route = { 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,566 @@
+'use strict'
+/**
+ * @module
+ */
+
+// See available emoji at http://emoji.muan.co/
+const emojic = require('emojic')
+const Joi = require('joi')
+const log = require('../server/log')
+const { AuthHelper } = require('./auth-helper')
+const { MetricHelper, MetricNames } = require('./metric-helper')
+const { assertValidCategory } = require('./categories')
+const checkErrorResponse = require('./check-error-response')
+const coalesceBadge = require('./coalesce-badge')
+const {
+  NotFound,
+  InvalidResponse,
+  Inaccessible,
+  ImproperlyConfigured,
+  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 optionalStringWhenNamedLogoPresent = Joi.alternatives().conditional(
+  'namedLogo',
+  {
+    is: Joi.string().required(),
+    then: Joi.string(),
+  }
+)
+
+const optionalNumberWhenAnyLogoPresent = Joi.alternatives()
+  .conditional('namedLogo', { is: Joi.string().required(), then: Joi.number() })
+  .conditional('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: optionalStringWhenNamedLogoPresent,
+  logoWidth: optionalNumberWhenAnyLogoPresent,
+  logoPosition: optionalNumberWhenAnyLogoPresent,
+  cacheSeconds: Joi.number().integer().min(0),
+  style: Joi.string(),
+})
+  .oxor('namedLogo', 'logoSvg')
+  .required()
+
+/**
+ * Abstract base class which all service classes inherit from.
+ * Concrete implementations of BaseService must implement the methods
+ * category(), route() and handle(namedParams, queryParams)
+ */
+class BaseService {
+  /**
+   * Name of the category to sort this badge into (eg. "build"). Used to sort
+   * the badges on the main shields.io website.
+   *
+   * @abstract
+   * @type {string}
+   */
+  static get category() {
+    throw new Error(`Category not set for ${this.name}`)
+  }
+
+  static isDeprecated = false
+
+  /**
+   * Route to mount this service on
+   *
+   * @abstract
+   * @type {module:core/base-service/base~Route}
+   */
+  static get route() {
+    throw new Error(`Route not defined for ${this.name}`)
+  }
+
+  /**
+   * Configuration for the authentication helper that prepares credentials
+   * for upstream requests.
+   *
+   * See also the config schema in `./server.js` and `doc/server-secrets.md`.
+   *
+   * To use the configured auth in the handler or fetch method, pass the
+   * credentials to the request. For example:
+   * - `{ options: { auth: this.authHelper.basicAuth } }`
+   * - `{ options: { headers: this.authHelper.bearerAuthHeader } }`
+   * - `{ options: { qs: { token: this.authHelper._pass } } }`
+   *
+   * @abstract
+   * @type {module:core/base-service/base~Auth}
+   */
+  static auth = undefined
+
+  /**
+   * Array of Example objects describing 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.
+   *
+   * @see {@link module:core/base-service/base~Example}
+   * @abstract
+   * @type {module:core/base-service/base~Example[]}
+   */
+  static examples = []
+
+  static get _cacheLength() {
+    const cacheLengths = {
+      build: 30,
+      license: 3600,
+      version: 300,
+      debug: 60,
+    }
+    return cacheLengths[this.category]
+  }
+
+  /**
+   * Default data for the badge.
+   * 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.
+   *
+   * @type {module:core/base-service/base~DefaultBadgeData}
+   */
+  static defaultBadgeData = {}
+
+  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, authHelper, metricHelper },
+    { handleInternalErrors }
+  ) {
+    this._requestFetcher = sendAndCacheRequest
+    this.authHelper = authHelper
+    this._handleInternalErrors = handleInternalErrors
+    this._metricHelper = metricHelper
+  }
+
+  async _request({ url, options = {}, errorMessages = {} }) {
+    const logTrace = (...args) => trace.logTrace('fetch', ...args)
+    let logUrl = url
+    const logOptions = Object.assign({}, options)
+    if ('qs' in options) {
+      const params = new URLSearchParams(options.qs)
+      logUrl = `${url}?${params.toString()}`
+      delete logOptions.qs
+    }
+    logTrace(
+      emojic.bowAndArrow,
+      'Request',
+      `${logUrl}\n${JSON.stringify(logOptions, null, 2)}`
+    )
+    const { res, buffer } = await this._requestFetcher(url, options)
+    await this._meterResponse(res, buffer)
+    logTrace(emojic.dart, 'Response status code', res.statusCode)
+    return checkErrorResponse(errorMessages)({ buffer, res })
+  }
+
+  static enabledMetrics = []
+
+  static isMetricEnabled(metricName) {
+    return this.enabledMetrics.includes(metricName)
+  }
+
+  async _meterResponse(res, buffer) {
+    if (
+      this._metricHelper &&
+      this.constructor.isMetricEnabled(MetricNames.SERVICE_RESPONSE_SIZE) &&
+      res.statusCode === 200
+    ) {
+      this._metricHelper.noteServiceResponseSize(buffer.length)
+    }
+  }
+
+  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.
+   *
+   * @abstract
+   * @param {object} namedParams Params parsed from route pattern
+   *    defined in this.route.pattern or this.route.capture
+   * @param {object} queryParams Params parsed from the query string
+   * @returns {module:core/base-service/base~Badge}
+   *    badge Object validated against serviceDataSchema
+   */
+  async handle(namedParams, queryParams) {
+    throw new Error(`Handler not implemented for ${this.constructor.name}`)
+  }
+
+  // Making this an instance method ensures debuggability.
+  // https://github.com/badges/shields/issues/3784
+  _validateServiceData(serviceData) {
+    Joi.assert(serviceData, serviceDataSchema)
+  }
+
+  _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 ImproperlyConfigured ||
+      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 Sentry and the logs.
+        log.error(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)
+
+    // Like the service instance, the auth helper could be reused for each request.
+    // However, moving its instantiation to `register()` makes `invoke()` harder
+    // to test.
+    const authHelper = this.auth ? new AuthHelper(this.auth, config) : undefined
+
+    const serviceInstance = new this({ ...context, authHelper }, config)
+
+    let serviceError
+    if (authHelper && !authHelper.isValid) {
+      const prettyMessage = authHelper.isRequired
+        ? 'credentials have not been configured'
+        : 'credentials are misconfigured'
+      serviceError = new ImproperlyConfigured({ prettyMessage })
+    }
+
+    const { queryParamSchema } = this.route
+    let transformedQueryParams
+    if (!serviceError && 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
+        )
+        serviceInstance._validateServiceData(serviceData)
+      } catch (error) {
+        serviceError = error
+      }
+    }
+
+    if (serviceError) {
+      serviceData = serviceInstance._handleError(serviceError)
+    }
+
+    trace.logTrace('outbound', emojic.shield, 'Service data', serviceData)
+
+    return serviceData
+  }
+
+  static register(
+    { camp, handleRequest, githubApiProvider, metricInstance },
+    serviceConfig
+  ) {
+    const { cacheHeaders: cacheHeaderConfig, fetchLimitBytes } = serviceConfig
+    const { regex, captureNames } = prepareRoute(this.route)
+    const queryParams = getQueryParamNames(this.route)
+
+    const metricHelper = MetricHelper.create({
+      metricInstance,
+      ServiceClass: this,
+    })
+
+    camp.route(
+      regex,
+      handleRequest(cacheHeaderConfig, {
+        queryParams,
+        handler: async (queryParams, match, sendBadge, request) => {
+          const metricHandle = metricHelper.startRequest()
+
+          const namedParams = namedParamsForMatch(captureNames, match, this)
+          const serviceData = await this.invoke(
+            {
+              sendAndCacheRequest: request.asPromise,
+              sendAndCacheRequestWithCallbacks: request,
+              githubApiProvider,
+              metricHelper,
+            },
+            serviceConfig,
+            namedParams,
+            queryParams
+          )
+
+          const badgeData = coalesceBadge(
+            queryParams,
+            serviceData,
+            this.defaultBadgeData,
+            this
+          )
+          // The final capture group is the extension.
+          const format = (match.slice(-1)[0] || '.svg').replace(/^\./, '')
+          sendBadge(format, badgeData)
+
+          metricHandle.noteResponseSent()
+        },
+        cacheLength: this._cacheLength,
+        fetchLimitBytes,
+      })
+    )
+  }
+}
+
+/**
+ * Default badge properties, validated against defaultBadgeDataSchema
+ *
+ * @typedef {object} DefaultBadgeData
+ * @property {string} label (Optional)
+ * @property {string} color (Optional)
+ * @property {string} labelColor (Optional)
+ * @property {string} namedLogo (Optional)
+ */
+
+/**
+ * Badge Object, validated against serviceDataSchema
+ *
+ * @typedef {object} Badge
+ * @property {boolean} isError (Optional)
+ * @property {string} label (Optional)
+ * @property {(string|number)} message
+ * @property {string} color (Optional)
+ * @property {string[]} link (Optional)
+ */
+
+/**
+ * @typedef {object} Route
+ * @property {string} base
+ *    (Optional) The base path of the routes for this service.
+ *    This is used as a prefix.
+ * @property {string} pattern
+ *    A path-to-regexp pattern defining the route pattern and param names
+ *    See {@link https://www.npmjs.com/package/path-to-regexp}
+ * @property {RegExp} format
+ *    Deprecated: Regular expression to use for routes for this service's badges
+ *    Use `pattern` instead
+ * @property {string[]} capture
+ *    Deprecated: Array of names for the capture groups in the regular
+ *    expression. The handler will be passed an object containing
+ *    the matches.
+ *    Use `pattern` instead
+ * @property {Joi.object} 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.)
+ */
+
+/**
+ * @typedef {object} Auth
+ * @property {string} userKey
+ *    (Optional) The key from `privateConfig` to use as the username.
+ * @property {string} passKey
+ *    (Optional) The key from `privateConfig` to use as the password.
+ *    If auth is configured, either `userKey` or `passKey` is required.
+ * @property {string} isRequired
+ *    (Optional) If `true`, the service will return `NotFound` unless the
+ *    configured credentials are present.
+ */
+
+/**
+ * @typedef {object} Example
+ * @property {string} 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.
+ * @property {object} namedParams
+ *    An object containing the values of named parameters to
+ *    substitute into the compiled route pattern.
+ * @property {object} 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`.
+ * @property {string} pattern
+ *    The route pattern to compile. Defaults to `this.route.pattern`.
+ * @property {object} 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.
+ * @property {string[]} keywords
+ *    Additional keywords, other than words in the title. This helps
+ *    users locate relevant badges.
+ * @property {string} documentation
+ *    An HTML string that is included in the badge popup.
+ */
+
+module.exports = BaseService

core/base-service/base.spec.js

@@ -0,0 +1,597 @@
+'use strict'
+
+const Joi = require('joi')
+const chai = require('chai')
+const { expect } = chai
+const sinon = require('sinon')
+const prometheus = require('prom-client')
+const PrometheusMetrics = require('../server/prometheus-metrics')
+const trace = require('./trace')
+const {
+  NotFound,
+  Inaccessible,
+  InvalidResponse,
+  InvalidParameter,
+  Deprecated,
+} = require('./errors')
+const BaseService = require('./base')
+const { MetricHelper, MetricNames } = require('./metric-helper')
+require('../register-chai-plugins.spec')
+chai.use(require('chai-as-promised'))
+
+const queryParamSchema = Joi.object({
+  queryParamA: Joi.string(),
+})
+  .rename('legacyQueryParamA', 'queryParamA', {
+    ignoreUndefined: true,
+    override: true,
+  })
+  .required()
+
+class DummyService extends BaseService {
+  static category = 'other'
+  static route = { base: 'foo', pattern: ':namedParamA', queryParamSchema }
+
+  static examples = [
+    {
+      pattern: ':world',
+      namedParams: { world: 'World' },
+      staticPreview: this.render({ namedParamA: 'foo', queryParamA: 'bar' }),
+      keywords: ['hello'],
+    },
+  ]
+
+  static defaultBadgeData = { 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 })
+  }
+}
+
+class DummyServiceWithServiceResponseSizeMetricEnabled extends DummyService {
+  static enabledMetrics = [MetricNames.SERVICE_RESPONSE_SIZE]
+}
+
+describe('BaseService', function () {
+  const defaultConfig = {
+    public: {
+      handleInternalErrors: false,
+      services: {},
+    },
+    private: {},
+  }
+
+  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', function () {
+      return expect(BaseService.invoke({}, {}, {})).to.be.rejectedWith(
+        /^Route not defined for BaseService$/
+      )
+    })
+
+    class WithRoute extends BaseService {
+      static route = {}
+    }
+    it('Should throw if handle() is not overridden', function () {
+      return expect(WithRoute.invoke({}, {}, {})).to.be.rejectedWith(
+        /^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,
+      })
+    })
+
+    context('On invalid data', function () {
+      class ThrowingService extends DummyService {
+        async handle() {
+          return {
+            some: 'nonsense',
+          }
+        }
+      }
+
+      it('Throws a validation error on invalid data', async function () {
+        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',
+          ])
+        }
+      })
+
+      // Ensure debuggabillity.
+      // https://github.com/badges/shields/issues/3784
+      it('Includes the service class in the stack trace', async function () {
+        try {
+          await ThrowingService.invoke(
+            {},
+            { handleInternalErrors: false },
+            { namedParamA: 'bar.bar.bar' }
+          )
+          expect.fail('Expected to throw')
+        } catch (e) {
+          expect(e.stack).to.include('ThrowingService._validateServiceData')
+        }
+      })
+    })
+  })
+
+  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 () {
+    // TODO Strangly, without the useless escape the regexes do not match in Node 12.
+    // eslint-disable-next-line no-useless-escape
+    const expectedRouteRegex = /^\/foo(?:\/([^\/#\?]+?))(|\.svg|\.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, {
+        label: 'cat',
+        message: 'Hello namedParamA: bar with queryParamA: ?',
+        color: 'lightgrey',
+        style: 'flat',
+        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', function () {
+      expect(() =>
+        DummyService._validate(
+          { requiredString: ['this', "shouldn't", 'work'] },
+          dummySchema
+        )
+      )
+        .to.throw()
+        .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${JSON.stringify(options, null, 2)}`
+      )
+      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')
+      }
+    })
+  })
+
+  describe('Metrics', function () {
+    let register
+    beforeEach(function () {
+      register = new prometheus.Registry()
+    })
+    const url = 'some-url'
+
+    it('service response size metric is optional', async function () {
+      const metricHelper = MetricHelper.create({
+        metricInstance: new PrometheusMetrics({ register }),
+        ServiceClass: DummyServiceWithServiceResponseSizeMetricEnabled,
+      })
+      const sendAndCacheRequest = async () => ({
+        buffer: 'x'.repeat(65536 + 1),
+        res: { statusCode: 200 },
+      })
+      const serviceInstance =
+        new DummyServiceWithServiceResponseSizeMetricEnabled(
+          { sendAndCacheRequest, metricHelper },
+          defaultConfig
+        )
+
+      await serviceInstance._request({ url })
+
+      expect(await register.getSingleMetricAsString('service_response_bytes'))
+        .to.contain(
+          'service_response_bytes_bucket{le="65536",category="other",family="undefined",service="dummy_service_with_service_response_size_metric_enabled"} 0\n'
+        )
+        .and.to.contain(
+          'service_response_bytes_bucket{le="131072",category="other",family="undefined",service="dummy_service_with_service_response_size_metric_enabled"} 1\n'
+        )
+    })
+
+    it('service response size metric is disabled by default', async function () {
+      const metricHelper = MetricHelper.create({
+        metricInstance: new PrometheusMetrics({ register }),
+        ServiceClass: DummyService,
+      })
+      const sendAndCacheRequest = async () => ({
+        buffer: 'x',
+        res: { statusCode: 200 },
+      })
+      const serviceInstance = new DummyService(
+        { sendAndCacheRequest, metricHelper },
+        defaultConfig
+      )
+
+      await serviceInstance._request({ url })
+
+      expect(
+        await register.getSingleMetricAsString('service_response_bytes')
+      ).to.not.contain('service_response_bytes_bucket')
+    })
+  })
+  describe('auth', function () {
+    class AuthService extends DummyService {
+      static auth = {
+        passKey: 'myci_pass',
+        serviceKey: 'myci',
+        isRequired: true,
+      }
+
+      async handle() {
+        return {
+          message: `The CI password is ${this.authHelper._pass}`,
+        }
+      }
+    }
+
+    it('when auth is configured properly, invoke() sets authHelper', async function () {
+      expect(
+        await AuthService.invoke(
+          {},
+          {
+            public: {
+              ...defaultConfig.public,
+              services: { myci: { authorizedOrigins: ['https://myci.test'] } },
+            },
+            private: { myci_pass: 'abc123' },
+          },
+          { namedParamA: 'bar.bar.bar' }
+        )
+      ).to.deep.equal({ message: 'The CI password is abc123' })
+    })
+
+    it('when auth is not configured properly, invoke() returns inacessible', async function () {
+      expect(
+        await AuthService.invoke(
+          {},
+          {
+            public: {
+              ...defaultConfig.public,
+              services: { myci: { authorizedOrigins: ['https://myci.test'] } },
+            },
+            private: {},
+          },
+          {
+            namedParamA: 'bar.bar.bar',
+          }
+        )
+      ).to.deep.equal({
+        color: 'lightgray',
+        isError: true,
+        message: 'credentials have not been configured',
+      })
+    })
+  })
+})

core/base-service/cache-headers.js

@@ -0,0 +1,113 @@
+'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}, s-maxage=${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}, s-maxage=${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,
+}