Redirect to a static badge instead of returning status code 500

* Add GitLab pipline suggestion

Added a suggestion for a pipeline badge when a GitLab URL is entered.

* Add tests

Added tests for the GitLab badge suggestion.

* Fix tests

Fixed the tests.

.circleci/config.yml

@@ -13,6 +13,10 @@ main_steps: &main_steps
     - 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
 
     - save_cache:
         paths:
@@ -61,6 +65,8 @@ integration_steps: &integration_steps
     - run:
         name: Install dependencies
         command: npm ci
+        environment:
+          CYPRESS_INSTALL_BINARY: 0
 
     - run:
         name: Integration tests
@@ -86,6 +92,8 @@ services_steps: &services_steps
     - run:
         name: Install dependencies
         command: npm ci
+        environment:
+          CYPRESS_INSTALL_BINARY: 0
 
     - run:
         name: Identify services tagged in the PR title
@@ -96,7 +104,7 @@ services_steps: &services_steps
         environment:
           mocha_reporter: mocha-junit-reporter
           MOCHA_FILE: junit/services/results.xml
-        command: npm run test:services:pr:run
+        command: RETRY_COUNT=3 npm run test:services:pr:run
 
     - store_test_results:
         path: junit
@@ -133,6 +141,8 @@ package_steps: &package_steps
           nvm use v12
           npm install -g npm
           npm ci
+        environment:
+          CYPRESS_INSTALL_BINARY: 0
 
     # Run the package tests on each currently supported node version. See:
     # https://github.com/badges/shields/blob/master/gh-badges/README.md#node-version-support
@@ -153,14 +163,6 @@ package_steps: &package_steps
           NODE_VERSION: v10
         name: Run package tests on Node 10
 
-    - run:
-        <<: *run_package_tests
-        environment:
-          mocha_reporter: mocha-junit-reporter
-          MOCHA_FILE: junit/gh-badges/v11/results.xml
-          NODE_VERSION: v11
-        name: Run package tests on Node 11
-
     - run:
         <<: *run_package_tests
         environment:
@@ -188,6 +190,8 @@ jobs:
       - run:
           name: Install dependencies
           command: npm ci
+          environment:
+            CYPRESS_INSTALL_BINARY: 0
 
       - save_cache:
           paths:
@@ -235,6 +239,8 @@ jobs:
       - run:
           name: Install dependencies
           command: npm ci
+          environment:
+            CYPRESS_INSTALL_BINARY: 0
 
       - run:
           name: Danger
@@ -259,16 +265,23 @@ jobs:
       - run:
           name: Install dependencies
           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:frontend
 
       - store_test_results:
@@ -303,11 +316,17 @@ jobs:
       - checkout
 
       - restore_cache:
+          name: Restore node_modules
           keys:
             - v2-dependencies-{{ checksum "package-lock.json" }}
             # https://github.com/badges/shields/issues/1937
             - v2-dependencies-
 
+      - restore_cache:
+          name: Restore Cypress binary
+          keys:
+            - v2-cypress-dependencies-{{ checksum "package-lock.json" }}
+
       - run:
           name: Install dependencies
           command: npm ci
@@ -332,6 +351,13 @@ jobs:
       - store_artifacts:
           path: cypress/screenshots
 
+      - 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
 

.eslintignore

@@ -1,3 +1,4 @@
+/api-docs/
 /build
 /coverage
 /__snapshots__

.eslintrc-frontend.yml

@@ -1,28 +0,0 @@
-env:
-  browser: true
-
-plugins:
-  - import
-  - react-hooks
-
-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', 'yml': 'always' }]
-  react/jsx-sort-props: 'error'
-  react-hooks/rules-of-hooks: 'error'
-  react-hooks/exhaustive-deps: 'error'

.eslintrc.yml

@@ -1,21 +1,72 @@
 extends:
-  - standard
-  - prettier
-
-env:
-  node: true
-  mocha: true
+  - standard-jsx
+  - standard-react
+  - plugin:@typescript-eslint/recommended
+  - prettier/@typescript-eslint
+  - prettier/standard
+  - prettier/react
+  - eslint:recommended
 
 parserOptions:
   # Override eslint-config-standard, which incorrectly sets this to "module",
   # though that setting is only for ES6 modules, not CommonJS modules.
   sourceType: 'script'
 
+settings:
+  react:
+    version: '16.8'
+
+plugins:
+  - chai-friendly
+  - jsdoc
+  - mocha
+  - no-extension-in-require
+  - 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:
-      - gatsby-browser.js
+      - '**/*.js'
+      - '!frontend/**/*.js'
+    env:
+      node: true
+      es6: true
+    rules:
+      no-console: 'off'
+      '@typescript-eslint/no-var-requires': off
+
+  - files:
+      - '**/*.@(ts|tsx)'
     parserOptions:
       sourceType: 'module'
+    parser: '@typescript-eslint/parser'
+    rules:
+      # Argh.
+      '@typescript-eslint/explicit-function-return-type': 'off'
+      '@typescript-eslint/no-object-literal-type-assertion': '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'
@@ -30,6 +81,7 @@ overrides:
                 'category',
                 'isDeprecated',
                 'route',
+                'auth',
                 'examples',
                 '_cacheLength',
                 'defaultBadgeData',
@@ -42,24 +94,31 @@ overrides:
           },
         ]
 
-plugins:
-  - mocha
-  - no-extension-in-require
-  - chai-friendly
-  - sort-class-members
+  - 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 }]
+
   # 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': error
 
   # 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'
@@ -74,11 +133,38 @@ rules:
   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'
-
   # Chai friendly.
   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 reccomended 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
+
+  react/jsx-sort-props: 'error'
+  react-hooks/rules-of-hooks: 'error'
+  react-hooks/exhaustive-deps: 'error'
+  jsx-quotes: ['error', 'prefer-double']

.github/ISSUE_TEMPLATE/1_Bug_report.md

@@ -1,6 +1,7 @@
 ---
 name: 🐛 Bug Report
 about: Report errors and problems
+labels: 'question'
 ---
 
 Are you experiencing an issue with...

.github/ISSUE_TEMPLATE/2_Failing_service_test.md

@@ -1,6 +1,7 @@
 ---
-name: :green_heart: Failing service test
+name: 💚 Failing service test
 about: Note failing service tests
+labels: 'keep-service-tests-green'
 ---
 
 :clock11: **When did the problem start?**

.github/ISSUE_TEMPLATE/3_Badge_request.md

@@ -1,6 +1,7 @@
 ---
 name: 💡 Badge Request
 about: Ideas for new badges
+labels: 'service-badge'
 ---
 
 :clipboard: **Description**

.github/ISSUE_TEMPLATE/5_Support_question.md

@@ -1,6 +1,7 @@
 ---
 name: ❓ Support Question
 about: Ask a question about shields.io
+labels: 'question'
 ---
 
 :question: **Question**

.gitignore

@@ -110,3 +110,6 @@ service-definitions.yml
 # Cypress
 /cypress/videos/
 /cypress/screenshots/
+
+# Rendered API docs
+/api-docs/

.gitpod.yml

@@ -1,5 +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==

.nycrc.json

@@ -9,9 +9,11 @@
     "**/test-helpers.js",
     "**/*-test-helpers.js",
     "**/*-fixtures.js",
+    "**/mocha-*.js",
     "dangerfile.js",
     "gatsby-*.js",
     "core/service-test-runner",
+    "core/got-test-client.js",
     "services/**/*.tester.js",
     "services/test-validators.js",
     "services/tester.js",

.prettierignore

@@ -3,6 +3,7 @@ package-lock.json
 /__snapshots__
 /.next
 /.cache
+/api-docs
 /build
 /public
 /coverage

CONTRIBUTING.md

@@ -24,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
@@ -95,12 +105,11 @@ There are three places to get help:
 ## Badge URLs
 
 - 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`.
+  `/SERVICE/NOUN/PARAMETERS/QUALIFIERS`. For instance,
+  `/gitter/room/nwjs/nw.js`. The vendor is gitter, the
+  badge is for rooms, and the parameter is nwjs/nw.js.
+- Services which require a url/hostname parameter should use a query parameter to accept that value. For instance,
+  `/discourse/topics?server=https://meta.discourse.org`.
 
 ## Coding guidelines
 

Dockerfile

@@ -1,7 +1,5 @@
 FROM node:8-alpine
 
-RUN apk add --no-cache gettext imagemagick librsvg git
-
 RUN mkdir -p /usr/src/app
 RUN mkdir /usr/src/app/private
 WORKDIR /usr/src/app
@@ -10,8 +8,8 @@ COPY package.json package-lock.json /usr/src/app/
 # Without the gh-badges package.json and CLI script in place, `npm ci` will fail.
 COPY gh-badges /usr/src/app/gh-badges/
 
-# We need dev deps to build the front end.
-RUN NODE_ENV=development npm ci
+# 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

README.md

@@ -1,35 +1,35 @@
 <p align="center">
-    <img src="./frontend/images/logo.svg"
+    <img src="https://raw.githubusercontent.com/badges/shields/master/frontend/images/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.svg" /></a>
+        <img src="https://img.shields.io/github/contributors/badges/shields" /></a>
     <a href="#backers" alt="Backers on Open Collective">
-        <img src="https://img.shields.io/opencollective/backers/shields.svg" /></a>
+        <img src="https://img.shields.io/opencollective/backers/shields" /></a>
     <a href="#sponsors" alt="Sponsors on Open Collective">
-        <img src="https://img.shields.io/opencollective/sponsors/shields.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.svg" /></a>
+        <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>
+        <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.svg?label=service%20tests"
+        <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.svg"
+        <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"
+        <img src="https://img.shields.io/lgtm/alerts/g/badges/shields"
             alt="Total alerts"/></a>
     <a href="https://github.com/badges/shields/compare/gh-pages...master">
-        <img src="https://img.shields.io/github/commits-since/badges/shields/gh-pages.svg?label=commits%20to%20be%20deployed"
+        <img src="https://img.shields.io/github/commits-since/badges/shields/gh-pages?label=commits%20to%20be%20deployed"
             alt="commits to be deployed"></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>
 
@@ -56,19 +56,19 @@ This repo hosts:
 
 ## Examples
 
-- code coverage percentage: ![coverage](https://img.shields.io/badge/coverage-80%25-yellowgreen.svg?cacheSeconds=2592000)
-- stable release version: ![version](https://img.shields.io/badge/version-1.2.3-blue.svg?cacheSeconds=2592000)
-- package manager release: ![gem](https://img.shields.io/badge/gem-2.2.0-blue.svg?cacheSeconds=2592000)
-- status of third-party dependencies: ![dependencies](https://img.shields.io/badge/dependencies-out%20of%20date-orange.svg?cacheSeconds=2592000)
-- static code analysis grade: ![codacy](https://img.shields.io/badge/codacy-B-green.svg?cacheSeconds=2592000)
-- [SemVer](https://semver.org/) version observance: ![semver](https://img.shields.io/badge/semver-2.0.0-blue.svg?cacheSeconds=2592000)
-- amount of [Liberapay](https://liberapay.com/) donations per week: ![receives](https://img.shields.io/badge/receives-2.00%20USD%2Fweek-yellow.svg?cacheSeconds=2592000)
-- Python package downloads: ![downloads](https://img.shields.io/badge/downloads-13k%2Fmonth-brightgreen.svg?cacheSeconds=2592000)
-- Chrome Web Store extension rating: ![rating](https://img.shields.io/badge/rating-★★★★☆-brightgreen.svg?cacheSeconds=2592000)
-- [Uptime Robot](https://uptimerobot.com) percentage: ![uptime](https://img.shields.io/badge/uptime-100%25-brightgreen.svg?cacheSeconds=2592000)
+- 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`)
+(Quick example: `https://img.shields.io/badge/left-right-f39f37`)
 
 Browse a [complete list of badges][shields.io].
 
@@ -84,7 +84,8 @@ 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)
+[![Hacktoberfest](https://img.shields.io/github/hacktoberfest/2019/badges/shields)](https://github.com/badges/shields/issues?q=is%3Aopen+is%3Aissue+label%3Ahacktoberfest)
+[![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)
 
 You can read a [tutorial on how to add a badge][tutorial].
 
@@ -107,14 +108,14 @@ 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 debug a badge from the command line, run `npm run badge -- /npm/v/nock.svg`.
+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.svg`.
+`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 Beta][gitpod], a pre-configured development
+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

app.json

@@ -6,6 +6,16 @@
   "repository": "https://github.com/badges/shields",
   "logo": "http://shields.io/favicon.png",
   "env": {
+    "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
@@ -13,6 +23,14 @@
     "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": {

config/custom-environment-variables.yml

@@ -14,6 +14,8 @@ public:
 
   redirectUri: 'REDIRECT_URI'
 
+  rasterUrl: 'RASTER_URL'
+
   cors:
     allowedOrigin:
       __name: 'ALLOWED_ORIGIN'
@@ -21,7 +23,6 @@ public:
 
   persistence:
     dir: 'PERSISTENCE_DIR'
-    redisUrl: 'REDIS_URL'
 
   services:
     github:
@@ -56,9 +57,12 @@ private:
   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'
+  twitch_client_id: 'TWITCH_CLIENT_ID'
+  twitch_client_secret: 'TWITCH_CLIENT_SECRET'
   wheelmap_token: 'WHEELMAP_TOKEN'

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

@@ -7,4 +7,6 @@ private:
   shields_secret: ...
   sl_insight_userUuid: ...
   sl_insight_apiToken: ...
+  twitch_client_id: ...
+  twitch_client_secret: ...
   wheelmap_token: ...

config/local.template.yml

@@ -5,4 +5,6 @@ private:
   # 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: '...'

config/shields-io-production.yml

@@ -11,6 +11,8 @@ public:
 
   redirectUrl: 'https://shields.io/'
 
+  rasterUrl: 'https://raster.shields.io'
+
 private:
   # These are not really private; they should be moved to `public`.
   shields_ips: ['192.99.59.72', '51.254.114.150', '149.56.96.133']

config/test.yml

@@ -5,6 +5,8 @@ public:
 
   rateLimit: false
 
-  redirectUrl: 'http://badge-server.example.com'
+  redirectUrl: 'http://frontend.example.test'
+
+  rasterUrl: 'http://raster.example.test'
 
   handleInternalErrors: false

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

@@ -0,0 +1,108 @@
+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,
+  color,
+  style,
+  namedLogo,
+  format,
+}: {
+  baseUrl?: string
+  label: string
+  message: string
+  color?: string
+  style?: string
+  namedLogo?: string
+  format?: 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

@@ -1,5 +1,6 @@
 'use strict'
 
+const { URL } = require('url')
 const queryString = require('query-string')
 const pathToRegexp = require('path-to-regexp')
 
@@ -8,7 +9,7 @@ function badgeUrlFromPath({
   path,
   queryParams,
   style,
-  format = 'svg',
+  format = '',
   longCache = false,
 }) {
   const outExt = format.length ? `.${format}` : ''
@@ -29,7 +30,7 @@ function badgeUrlFromPattern({
   namedParams,
   queryParams,
   style,
-  format = 'svg',
+  format = '',
   longCache = false,
 }) {
   const toPath = pathToRegexp.compile(pattern, {
@@ -60,15 +61,16 @@ function staticBadgeUrl({
   color = 'lightgray',
   style,
   namedLogo,
-  format = 'svg',
+  format = '',
 }) {
   const path = [label, message, color].map(encodeField).join('-')
   const outQueryString = queryString.stringify({
     style,
     logo: namedLogo,
   })
+  const outExt = format.length ? `.${format}` : ''
   const suffix = outQueryString ? `?${outQueryString}` : ''
-  return `${baseUrl}/badge/${path}.${format}${suffix}`
+  return `${baseUrl}/badge/${path}${outExt}${suffix}`
 }
 
 function queryStringStaticBadgeUrl({
@@ -82,7 +84,7 @@ function queryStringStaticBadgeUrl({
   logoColor,
   logoWidth,
   logoPosition,
-  format = 'svg',
+  format = '',
 }) {
   // schemaVersion could be a parameter if we iterate on it,
   // for now it's hardcoded to the only supported version.
@@ -98,7 +100,8 @@ function queryStringStaticBadgeUrl({
     logoWidth,
     logoPosition,
   })}`
-  return `${baseUrl}/static/v${schemaVersion}.${format}${suffix}`
+  const outExt = format.length ? `.${format}` : ''
+  return `${baseUrl}/static/v${schemaVersion}${outExt}${suffix}`
 }
 
 function dynamicBadgeUrl({
@@ -111,8 +114,10 @@ function dynamicBadgeUrl({
   suffix,
   color,
   style,
-  format = 'svg',
+  format = '',
 }) {
+  const outExt = format.length ? `.${format}` : ''
+
   const queryParams = {
     label,
     url: dataUrl,
@@ -131,7 +136,16 @@ function dynamicBadgeUrl({
   }
 
   const outQueryString = queryString.stringify(queryParams)
-  return `${baseUrl}/badge/dynamic/${datatype}.${format}?${outQueryString}`
+  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 = {
@@ -141,4 +155,5 @@ module.exports = {
   staticBadgeUrl,
   queryStringStaticBadgeUrl,
   dynamicBadgeUrl,
+  rasterRedirectUrl,
 }

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

@@ -18,7 +18,7 @@ describe('Badge URL generation functions', function() {
       style: 'flat-square',
       longCache: true,
     }).expect(
-      'http://example.com/npm/v/gh-badges.svg?cacheSeconds=2592000&style=flat-square'
+      'http://example.com/npm/v/gh-badges?cacheSeconds=2592000&style=flat-square'
     )
   })
 
@@ -30,7 +30,7 @@ describe('Badge URL generation functions', function() {
       style: 'flat-square',
       longCache: true,
     }).expect(
-      'http://example.com/npm/v/gh-badges.svg?cacheSeconds=2592000&style=flat-square'
+      'http://example.com/npm/v/gh-badges?cacheSeconds=2592000&style=flat-square'
     )
   })
 
@@ -48,7 +48,7 @@ describe('Badge URL generation functions', function() {
       message: 'bar',
       color: 'blue',
       style: 'flat-square',
-    }).expect('/badge/foo-bar-blue.svg?style=flat-square')
+    }).expect('/badge/foo-bar-blue?style=flat-square')
     given({
       label: 'foo',
       message: 'bar',
@@ -62,24 +62,24 @@ describe('Badge URL generation functions', function() {
       message: 'Привет Мир',
       color: '#aabbcc',
     }).expect(
-      '/badge/Hello%20World-%D0%9F%D1%80%D0%B8%D0%B2%D0%B5%D1%82%20%D0%9C%D0%B8%D1%80-%23aabbcc.svg'
+      '/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.svg')
+    }).expect('/badge/123--123-abc--abc-blue')
     given({
       label: '123-123',
       message: '',
       color: 'blue',
       style: 'social',
-    }).expect('/badge/123--123--blue.svg?style=social')
+    }).expect('/badge/123--123--blue?style=social')
     given({
       label: '',
       message: 'blue',
       color: 'blue',
-    }).expect('/badge/-blue-blue.svg')
+    }).expect('/badge/-blue-blue')
   })
 
   test(queryStringStaticBadgeUrl, () => {
@@ -89,9 +89,7 @@ describe('Badge URL generation functions', function() {
       message: 'bar',
       color: 'blue',
       style: 'flat-square',
-    }).expect(
-      '/static/v1.svg?color=blue&label=foo&message=bar&style=flat-square'
-    )
+    }).expect('/static/v1?color=blue&label=foo&message=bar&style=flat-square')
     given({
       label: 'foo Bar',
       message: 'bar Baz',
@@ -107,7 +105,7 @@ describe('Badge URL generation functions', function() {
       message: 'Привет Мир',
       color: '#aabbcc',
     }).expect(
-      '/static/v1.svg?color=%23aabbcc&label=Hello%20World&message=%D0%9F%D1%80%D0%B8%D0%B2%D0%B5%D1%82%20%D0%9C%D0%B8%D1%80'
+      '/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'
     )
   })
 
@@ -125,7 +123,7 @@ describe('Badge URL generation functions', function() {
       style: 'plastic',
     }).expect(
       [
-        'http://img.example.com/badge/dynamic/json.svg',
+        'http://img.example.com/badge/dynamic/json',
         '?label=foo',
         `&prefix=${encodeURIComponent(prefix)}`,
         `&query=${encodeURIComponent(query)}`,
@@ -146,7 +144,7 @@ describe('Badge URL generation functions', function() {
       style: 'plastic',
     }).expect(
       [
-        'http://img.example.com/badge/dynamic/json.svg',
+        'http://img.example.com/badge/dynamic/json',
         '?color=blue',
         '&label=foo',
         `&query=${encodeURIComponent(query)}`,

core/base-service/auth-helper.js

@@ -0,0 +1,55 @@
+'use strict'
+
+class AuthHelper {
+  constructor(
+    {
+      userKey,
+      passKey,
+      isRequired = false,
+      defaultToEmptyStringForUser = false,
+    },
+    privateConfig
+  ) {
+    if (!userKey && !passKey) {
+      throw Error('Expected userKey or passKey to be set')
+    }
+
+    this._userKey = userKey
+    this._passKey = passKey
+    if (userKey) {
+      this.user = privateConfig[userKey]
+    } else {
+      this.user = defaultToEmptyStringForUser ? '' : undefined
+    }
+    this.pass = passKey ? privateConfig[passKey] : undefined
+    this.isRequired = isRequired
+  }
+
+  get isConfigured() {
+    return (
+      (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
+    }
+  }
+
+  get basicAuth() {
+    const { user, pass } = this
+    return this.isConfigured ? { user, pass } : undefined
+  }
+
+  get bearerAuthHeader() {
+    const { pass } = this
+    return this.isConfigured ? { Authorization: `Bearer ${pass}` } : undefined
+  }
+}
+
+module.exports = { AuthHelper }

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

@@ -0,0 +1,103 @@
+'use strict'
+
+const { expect } = require('chai')
+const { test, given, forCases } = require('sazerac')
+const { AuthHelper } = require('./auth-helper')
+
+describe('AuthHelper', function() {
+  it('throws without userKey or passKey', function() {
+    expect(() => new AuthHelper({}, {})).to.throw(
+      Error,
+      'Expected userKey or passKey to be set'
+    )
+  })
+
+  describe('isValid', function() {
+    function validate(config, privateConfig) {
+      return new AuthHelper(config, 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(config, 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',
+      })
+    })
+  })
+})

core/base-service/base-graphql.js

@@ -0,0 +1,92 @@
+/**
+ * @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.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 = {},
+    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 = 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,209 @@
+'use strict'
+
+const Joi = require('@hapi/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 get category() {
+    return 'cat'
+  }
+
+  static get route() {
+    return {
+      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

@@ -1,30 +1,44 @@
+/**
+ * @module
+ */
+
 'use strict'
 
-// See available emoji at http://emoji.muan.co/
-const emojic = require('emojic')
 const BaseService = require('./base')
-const trace = require('./trace')
-const { InvalidResponse } = require('./errors')
+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) {
-    const logTrace = (...args) => trace.logTrace('fetch', ...args)
-    let json
-    try {
-      json = JSON.parse(buffer)
-    } catch (err) {
-      logTrace(emojic.dart, 'Response JSON (unparseable)', buffer)
-      throw new InvalidResponse({
-        prettyMessage: 'unparseable json response',
-        underlyingError: err,
-      })
-    }
-    logTrace(emojic.dart, 'Response JSON (before validation)', json, {
-      deep: true,
-    })
-    return json
+    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' } },

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

@@ -1,6 +1,6 @@
 'use strict'
 
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const { expect } = require('chai')
 const sinon = require('sinon')
 const BaseJsonService = require('./base-json')

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

@@ -2,6 +2,7 @@
 
 const makeBadge = require('../../gh-badges/lib/make-badge')
 const BaseService = require('./base')
+const { MetricHelper } = require('./metric-helper')
 const { setCacheHeaders } = require('./cache-headers')
 const { makeSend } = require('./legacy-result-sender')
 const coalesceBadge = require('./coalesce-badge')
@@ -24,16 +25,19 @@ const { prepareRoute, namedParamsForMatch } = require('./route')
 // configured by the service, the user's request, and the server's default
 // cache length.
 module.exports = class NonMemoryCachingBaseService extends BaseService {
-  static register({ camp, requestCounter }, serviceConfig) {
+  static register({ camp, metricInstance }, serviceConfig) {
     const { cacheHeaders: cacheHeaderConfig } = serviceConfig
     const { _cacheLength: serviceDefaultCacheLengthSeconds } = this
     const { regex, captureNames } = prepareRoute(this.route)
 
-    const serviceRequestCounter = this._createServiceRequestCounter({
-      requestCounter,
+    const metricHelper = MetricHelper.create({
+      metricInstance,
+      ServiceClass: this,
     })
 
     camp.route(regex, async (queryParams, match, end, ask) => {
+      const metricHandle = metricHelper.startRequest()
+
       const namedParams = namedParamsForMatch(captureNames, match, this)
       const serviceData = await this.invoke(
         {},
@@ -50,7 +54,7 @@ module.exports = class NonMemoryCachingBaseService extends BaseService {
       )
 
       // The final capture group is the extension.
-      const format = match.slice(-1)[0]
+      const format = (match.slice(-1)[0] || '.svg').replace(/^\./, '')
       badgeData.format = format
 
       const svg = makeBadge(badgeData)
@@ -64,7 +68,7 @@ module.exports = class NonMemoryCachingBaseService extends BaseService {
 
       makeSend(format, ask.res, end)(svg)
 
-      serviceRequestCounter.inc()
+      metricHandle.noteResponseSent()
     })
   }
 }

core/base-service/base-static.js

@@ -7,18 +7,20 @@ const {
   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, requestCounter }, serviceConfig) {
+  static register({ camp, metricInstance }, serviceConfig) {
     const {
       profiling: { makeBadge: shouldProfileMakeBadge },
     } = serviceConfig
     const { regex, captureNames } = prepareRoute(this.route)
 
-    const serviceRequestCounter = this._createServiceRequestCounter({
-      requestCounter,
+    const metricHelper = MetricHelper.create({
+      metricInstance,
+      ServiceClass: this,
     })
 
     camp.route(regex, async (queryParams, match, end, ask) => {
@@ -29,6 +31,8 @@ module.exports = class BaseStaticService extends BaseService {
         return
       }
 
+      const metricHandle = metricHelper.startRequest()
+
       const namedParams = namedParamsForMatch(captureNames, match, this)
       const serviceData = await this.invoke(
         {},
@@ -45,7 +49,7 @@ module.exports = class BaseStaticService extends BaseService {
       )
 
       // The final capture group is the extension.
-      const format = match.slice(-1)[0]
+      const format = (match.slice(-1)[0] || '.svg').replace(/^\./, '')
       badgeData.format = format
 
       if (shouldProfileMakeBadge) {
@@ -60,7 +64,7 @@ module.exports = class BaseStaticService extends BaseService {
 
       makeSend(format, ask.res, end)(svg)
 
-      serviceRequestCounter.inc()
+      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,7 +13,21 @@ 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 new TypeError('Parameter should be a string')
@@ -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

@@ -2,7 +2,7 @@
 
 const { expect } = require('chai')
 const sinon = require('sinon')
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const makeBadge = require('../../gh-badges/lib/make-badge')
 const BaseSvgScrapingService = require('./base-svg-scraping')
 

core/base-service/base-xml.js

@@ -1,3 +1,7 @@
+/**
+ * @module
+ */
+
 'use strict'
 
 // See available emoji at http://emoji.muan.co/
@@ -7,7 +11,31 @@ 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,

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

@@ -1,6 +1,6 @@
 'use strict'
 
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const { expect } = require('chai')
 const sinon = require('sinon')
 const BaseXmlService = require('./base-xml')

core/base-service/base-yaml.js

@@ -1,3 +1,7 @@
+/**
+ * @module
+ */
+
 'use strict'
 
 const emojic = require('emojic')
@@ -6,7 +10,29 @@ 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,

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

@@ -1,6 +1,6 @@
 'use strict'
 
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const { expect } = require('chai')
 const sinon = require('sinon')
 const BaseYamlService = require('./base-yaml')

core/base-service/base.js

@@ -1,9 +1,14 @@
 'use strict'
+/**
+ * @module
+ */
 
-const decamelize = require('decamelize')
 // See available emoji at http://emoji.muan.co/
 const emojic = require('emojic')
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
+const log = require('../server/log')
+const { AuthHelper } = require('./auth-helper')
+const { MetricHelper } = require('./metric-helper')
 const { assertValidCategory } = require('./categories')
 const checkErrorResponse = require('./check-error-response')
 const coalesceBadge = require('./coalesce-badge')
@@ -11,6 +16,7 @@ const {
   NotFound,
   InvalidResponse,
   Inaccessible,
+  ImproperlyConfigured,
   InvalidParameter,
   Deprecated,
 } = require('./errors')
@@ -33,14 +39,17 @@ const defaultBadgeDataSchema = Joi.object({
   namedLogo: Joi.string(),
 }).required()
 
-const optionalStringWhenNamedLogoPrsent = Joi.alternatives().when('namedLogo', {
-  is: Joi.string().required(),
-  then: Joi.string(),
-})
+const optionalStringWhenNamedLogoPresent = Joi.alternatives().conditional(
+  'namedLogo',
+  {
+    is: Joi.string().required(),
+    then: Joi.string(),
+  }
+)
 
 const optionalNumberWhenAnyLogoPresent = Joi.alternatives()
-  .when('namedLogo', { is: Joi.string().required(), then: Joi.number() })
-  .when('logoSvg', { is: Joi.string().required(), then: Joi.number() })
+  .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(),
@@ -58,7 +67,7 @@ const serviceDataSchema = Joi.object({
   labelColor: Joi.string(),
   namedLogo: Joi.string(),
   logoSvg: Joi.string(),
-  logoColor: optionalStringWhenNamedLogoPrsent,
+  logoColor: optionalStringWhenNamedLogoPresent,
   logoWidth: optionalNumberWhenAnyLogoPresent,
   logoPosition: optionalNumberWhenAnyLogoPresent,
   cacheSeconds: Joi.number()
@@ -69,10 +78,18 @@ const serviceDataSchema = Joi.object({
   .oxor('namedLogo', 'logoSvg')
   .required()
 
-module.exports = class BaseService {
+/**
+ * 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}`)
@@ -83,38 +100,38 @@ module.exports = class BaseService {
   }
 
   /**
-   * Returns an object:
-   *  - base: (Optional) The base path of the routes for this service. This is
-   *    used as a prefix.
-   *  - format: Regular expression to use for routes for this service's badges
-   *  - capture: Array of names for the capture groups in the regular
-   *             expression. The handler will be passed an object containing
-   *             the matches.
-   *  - queryParamSchema: (Optional) A Joi schema (`Joi.object({ ... }).required()`)
-   *                      for the query param object. If you know a parameter
-   *                      will never receive a numeric string, you can use
-   *                      `Joi.string()`. Because of quirks in Scoutcamp and Joi,
-   *                      alphanumeric strings should be declared using
-   *                      `Joi.alternatives().try(Joi.string(), Joi.number())`,
-   *                      otherwise a value like `?success_color=999` will fail.
-   *                      A parameter requiring a numeric string can use
-   *                      `Joi.number()`. A parameter that receives only non-numeric
-   *                      strings can use `Joi.string()`. A parameter that never
-   *                      receives numeric can use `Joi.string()`. A boolean
-   *                      parameter should use `Joi.equal('')` and will receive an
-   *                      empty string on e.g. `?compact_message` and undefined
-   *                      when the parameter is absent. (Note that in,
-   *                      `examples.queryParams` boolean query params should be given
-   *                      `null` values.)
+   * 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}`)
   }
 
   /**
-   * 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.
+   * 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 get auth() {
+    return 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
@@ -123,21 +140,9 @@ module.exports = class BaseService {
    * For services which use a route `format`, the `pattern` can be specified as
    * part of the example.
    *
-   * title: Descriptive text that will be shown next to the badge. The default
-   *   is to use the service class name, which probably is not what you want.
-   * namedParams: An object containing the values of named parameters to
-   *   substitute into the compiled route pattern.
-   * queryParams: An object containing query parameters to include in the
-   *   example URLs. For alphanumeric query parameters, specify a string value.
-   *   For boolean query parameters, specify `null`.
-   * pattern: The route pattern to compile. Defaults to `this.route.pattern`.
-   * staticPreview: A rendered badge of the sort returned by `handle()` or
-   *   `render()`: an object containing `message` and optional `label` and
-   *   `color`. This is usually generated by invoking `this.render()` with some
-   *   explicit props.
-   * keywords: Additional keywords, other than words in the title. This helps
-   *   users locate relevant badges.
-   * documentation: An HTML string that is included in the badge popup.
+   * @see {@link module:core/base-service/base~Example}
+   * @abstract
+   * @type {module:core/base-service/base~Example[]}
    */
   static get examples() {
     return []
@@ -154,9 +159,11 @@ module.exports = class BaseService {
   }
 
   /**
-   * Default data for the badge. Can include label, logo, and color. These
-   * defaults are used if the value is neither included in the service data
+   * 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 get defaultBadgeData() {
     return {}
@@ -207,8 +214,9 @@ module.exports = class BaseService {
     return result
   }
 
-  constructor({ sendAndCacheRequest }, { handleInternalErrors }) {
+  constructor({ sendAndCacheRequest, authHelper }, { handleInternalErrors }) {
     this._requestFetcher = sendAndCacheRequest
+    this.authHelper = authHelper
     this._handleInternalErrors = handleInternalErrors
   }
 
@@ -247,6 +255,13 @@ module.exports = class BaseService {
    * 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}`)
@@ -261,6 +276,7 @@ module.exports = class BaseService {
         color: 'red',
       }
     } else if (
+      error instanceof ImproperlyConfigured ||
       error instanceof InvalidResponse ||
       error instanceof Inaccessible ||
       error instanceof Deprecated
@@ -281,8 +297,8 @@ module.exports = class BaseService {
         )
       ) {
         // This is where we end up if an unhandled exception is thrown in
-        // production. Send the error to the logs.
-        console.log(error)
+        // production. Send the error to Sentry and the logs.
+        log.error(error)
       }
       return {
         isError: true,
@@ -311,12 +327,26 @@ module.exports = class BaseService {
     trace.logTrace('inbound', emojic.ticket, 'Named params', namedParams)
     trace.logTrace('inbound', emojic.crayon, 'Query params', queryParams)
 
-    const serviceInstance = new this(context, config)
+    // 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.private)
+      : 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 (queryParamSchema) {
+    if (!serviceError && queryParamSchema) {
       try {
         transformedQueryParams = validate(
           {
@@ -364,27 +394,17 @@ module.exports = class BaseService {
     return serviceData
   }
 
-  static _createServiceRequestCounter({ requestCounter }) {
-    if (requestCounter) {
-      const { category, serviceFamily, name } = this
-      const service = decamelize(name)
-      return requestCounter.labels(category, serviceFamily, service)
-    } else {
-      // When metrics are disabled, return a mock counter.
-      return { inc: () => {} }
-    }
-  }
-
   static register(
-    { camp, handleRequest, githubApiProvider, requestCounter },
+    { camp, handleRequest, githubApiProvider, metricInstance },
     serviceConfig
   ) {
     const { cacheHeaders: cacheHeaderConfig, fetchLimitBytes } = serviceConfig
     const { regex, captureNames } = prepareRoute(this.route)
     const queryParams = getQueryParamNames(this.route)
 
-    const serviceRequestCounter = this._createServiceRequestCounter({
-      requestCounter,
+    const metricHelper = MetricHelper.create({
+      metricInstance,
+      ServiceClass: this,
     })
 
     camp.route(
@@ -392,6 +412,8 @@ module.exports = class BaseService {
       handleRequest(cacheHeaderConfig, {
         queryParams,
         handler: async (queryParams, match, sendBadge, request) => {
+          const metricHandle = metricHelper.startRequest()
+
           const namedParams = namedParamsForMatch(captureNames, match, this)
           const serviceData = await this.invoke(
             {
@@ -411,10 +433,10 @@ module.exports = class BaseService {
             this
           )
           // The final capture group is the extension.
-          const format = match.slice(-1)[0]
+          const format = (match.slice(-1)[0] || '.svg').replace(/^\./, '')
           sendBadge(format, badgeData)
 
-          serviceRequestCounter.inc()
+          metricHandle.noteResponseSent()
         },
         cacheLength: this._cacheLength,
         fetchLimitBytes,
@@ -422,3 +444,99 @@ module.exports = class BaseService {
     )
   }
 }
+
+/**
+ * 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

@@ -1,6 +1,6 @@
 'use strict'
 
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const { expect } = require('chai')
 const sinon = require('sinon')
 const trace = require('./trace')
@@ -64,7 +64,7 @@ class DummyService extends BaseService {
 }
 
 describe('BaseService', function() {
-  const defaultConfig = { handleInternalErrors: false }
+  const defaultConfig = { handleInternalErrors: false, private: {} }
 
   it('Invokes the handler as expected', async function() {
     expect(
@@ -316,7 +316,9 @@ describe('BaseService', function() {
   })
 
   describe('ScoutCamp integration', function() {
-    const expectedRouteRegex = /^\/foo\/([^/]+?)\.(svg|png|gif|jpg|json)$/
+    // 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
@@ -482,4 +484,43 @@ describe('BaseService', function() {
       }
     })
   })
+
+  describe('auth', function() {
+    class AuthService extends DummyService {
+      static get auth() {
+        return {
+          passKey: 'myci_pass',
+          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(
+          {},
+          { defaultConfig, 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({}, defaultConfig, {
+          namedParamA: 'bar.bar.bar',
+        })
+      ).to.deep.equal({
+        color: 'lightgray',
+        isError: true,
+        message: 'credentials have not been configured',
+      })
+    })
+  })
 })

core/base-service/cache-headers.js

@@ -1,7 +1,7 @@
 'use strict'
 
 const assert = require('assert')
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const coalesce = require('./coalesce')
 
 const serverStartTimeGMTString = new Date().toGMTString()

core/base-service/categories.js

@@ -1,9 +1,9 @@
 'use strict'
 
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const categories = require('../../services/categories')
 
-const isRealCategory = Joi.equal(categories.map(({ id }) => id)).required()
+const isRealCategory = Joi.equal(...categories.map(({ id }) => id)).required()
 
 const isValidCategory = Joi.alternatives()
   .try(isRealCategory, Joi.equal('debug', 'dynamic', 'static').required())

core/base-service/deprecated-service.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const camelcase = require('camelcase')
 const BaseService = require('./base')
 const { isValidCategory } = require('./categories')

core/base-service/errors.js

@@ -1,13 +1,43 @@
+/**
+ * Standard exceptions for handling error cases
+ *
+ * @module
+ */
+
 'use strict'
 
+/**
+ * Base error class
+ *
+ * @abstract
+ */
 class ShieldsRuntimeError extends Error {
+  /**
+   * Name of the class. Implementations of ShieldsRuntimeError
+   * should override this method.
+   *
+   * @type {string}
+   */
   get name() {
     return 'ShieldsRuntimeError'
   }
+
+  /**
+   * Default message for this exception if none is specified.
+   * Implementations of ShieldsRuntimeError should implement this method.
+   *
+   * @abstract
+   * @type {string}
+   */
   get defaultPrettyMessage() {
     throw new Error('Must implement abstract method')
   }
 
+  /**
+   * @param {module:core/base-service/errors~RuntimeErrorProps} props
+   * Refer to individual attrs
+   * @param {string} message Exception message for debug purposes
+   */
   constructor(props = {}, message) {
     super(message)
     this.prettyMessage = props.prettyMessage || this.defaultPrettyMessage
@@ -19,6 +49,9 @@ class ShieldsRuntimeError extends Error {
 
 const defaultNotFoundError = 'not found'
 
+/**
+ * Throw this to wrap a 404 or other 'not found' response from an upstream API
+ */
 class NotFound extends ShieldsRuntimeError {
   get name() {
     return 'NotFound'
@@ -27,6 +60,10 @@ class NotFound extends ShieldsRuntimeError {
     return defaultNotFoundError
   }
 
+  /**
+   * @param {module:core/base-service/errors~RuntimeErrorProps} props
+   * Refer to individual attrs
+   */
   constructor(props = {}) {
     const prettyMessage = props.prettyMessage || defaultNotFoundError
     const message =
@@ -38,6 +75,9 @@ class NotFound extends ShieldsRuntimeError {
   }
 }
 
+/**
+ * Throw this to wrap an invalid or unexpected response from an upstream API
+ */
 class InvalidResponse extends ShieldsRuntimeError {
   get name() {
     return 'InvalidResponse'
@@ -46,6 +86,10 @@ class InvalidResponse extends ShieldsRuntimeError {
     return 'invalid'
   }
 
+  /**
+   * @param {module:core/base-service/errors~RuntimeErrorProps} props
+   * Refer to individual attrs
+   */
   constructor(props = {}) {
     const message = props.underlyingError
       ? `Invalid Response: ${props.underlyingError.message}`
@@ -55,6 +99,10 @@ class InvalidResponse extends ShieldsRuntimeError {
   }
 }
 
+/**
+ * Throw this if we can't contact an upstream API
+ * or to wrap a 5XX response
+ */
 class Inaccessible extends ShieldsRuntimeError {
   get name() {
     return 'Inaccessible'
@@ -63,6 +111,10 @@ class Inaccessible extends ShieldsRuntimeError {
     return 'inaccessible'
   }
 
+  /**
+   * @param {module:core/base-service/errors~RuntimeErrorProps} props
+   * Refer to individual attrs
+   */
   constructor(props = {}) {
     const message = props.underlyingError
       ? `Inaccessible: ${props.underlyingError.message}`
@@ -72,6 +124,34 @@ class Inaccessible extends ShieldsRuntimeError {
   }
 }
 
+/**
+ * Throw this error when required credentials are missing
+ */
+class ImproperlyConfigured extends ShieldsRuntimeError {
+  get name() {
+    return 'ImproperlyConfigured'
+  }
+  get defaultPrettyMessage() {
+    return 'improperly configured'
+  }
+
+  /**
+   * @param {module:core/base-service/errors~RuntimeErrorProps} props
+   * Refer to individual attrs
+   */
+  constructor(props = {}) {
+    const message = props.underlyingError
+      ? `ImproperlyConfigured: ${props.underlyingError.message}`
+      : 'ImproperlyConfigured'
+    super(props, message)
+    this.response = props.response
+  }
+}
+
+/**
+ * Throw this error when a user supplied input or parameter
+ * is invalid or unexpected
+ */
 class InvalidParameter extends ShieldsRuntimeError {
   get name() {
     return 'InvalidParameter'
@@ -80,6 +160,10 @@ class InvalidParameter extends ShieldsRuntimeError {
     return 'invalid parameter'
   }
 
+  /**
+   * @param {module:core/base-service/errors~RuntimeErrorProps} props
+   * Refer to individual attrs
+   */
   constructor(props = {}) {
     const message = props.underlyingError
       ? `Invalid Parameter: ${props.underlyingError.message}`
@@ -89,6 +173,9 @@ class InvalidParameter extends ShieldsRuntimeError {
   }
 }
 
+/**
+ * Throw this error to indicate that a service is deprecated or removed
+ */
 class Deprecated extends ShieldsRuntimeError {
   get name() {
     return 'Deprecated'
@@ -97,15 +184,30 @@ class Deprecated extends ShieldsRuntimeError {
     return 'no longer available'
   }
 
+  /**
+   * @param {module:core/base-service/errors~RuntimeErrorProps} props
+   * Refer to individual attrs
+   */
   constructor(props) {
     const message = 'Deprecated'
     super(props, message)
   }
 }
 
+/**
+ * @typedef {object} RuntimeErrorProps
+ * @property {Error} underlyingError Exception we are wrapping (Optional)
+ * @property {object} response Response from an upstream API to provide
+ * context for the error (Optional)
+ * @property {string} prettyMessage User-facing error message to override the
+ * value of `defaultPrettyMessage()`. This is the text that will appear on the
+ * badge when we catch and render the exception (Optional)
+ */
+
 module.exports = {
   ShieldsRuntimeError,
   NotFound,
+  ImproperlyConfigured,
   InvalidResponse,
   Inaccessible,
   InvalidParameter,

core/base-service/examples.js

@@ -1,7 +1,8 @@
 'use strict'
 
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const pathToRegexp = require('path-to-regexp')
+const categories = require('../../services/categories')
 const coalesceBadge = require('./coalesce-badge')
 const { makeFullUrl } = require('./route')
 
@@ -47,16 +48,12 @@ function validateExample(example, index, ServiceClass) {
 
   if (!pattern && !ServiceClass.route.pattern) {
     throw new Error(
-      `Example for ${
-        ServiceClass.name
-      } at index ${index} does not declare a pattern`
+      `Example for ${ServiceClass.name} at index ${index} does not declare a pattern`
     )
   }
   if (pattern === ServiceClass.route.pattern) {
     throw new Error(
-      `Example for ${
-        ServiceClass.name
-      } at index ${index} declares a redundant pattern which should be removed`
+      `Example for ${ServiceClass.name} at index ${index} declares a redundant pattern which should be removed`
     )
   }
 
@@ -158,7 +155,9 @@ function transformExample(inExample, index, ServiceClass) {
       style: style === 'flat' ? undefined : style,
       namedLogo,
     },
-    keywords,
+    keywords: keywords.concat(
+      categories.find(c => c.id === ServiceClass.category).keywords
+    ),
     documentation: documentation ? { __html: documentation } : undefined,
   }
 }

core/base-service/examples.spec.js

@@ -84,6 +84,7 @@ test(transformExample, function() {
     defaultBadgeData: {
       label: 'downloads',
     },
+    category: 'platform-support',
   }
 
   given(
@@ -109,7 +110,7 @@ test(transformExample, function() {
       namedLogo: undefined,
       style: undefined,
     },
-    keywords: ['hello'],
+    keywords: ['hello', 'platform'],
     documentation: undefined,
   })
 
@@ -135,7 +136,7 @@ test(transformExample, function() {
       namedLogo: undefined,
       style: undefined,
     },
-    keywords: ['hello'],
+    keywords: ['hello', 'platform'],
     documentation: undefined,
   })
 
@@ -162,7 +163,7 @@ test(transformExample, function() {
       namedLogo: undefined,
       style: undefined,
     },
-    keywords: ['hello'],
+    keywords: ['hello', 'platform'],
     documentation: undefined,
   })
 })

core/base-service/graphql.js

@@ -0,0 +1,52 @@
+'use strict'
+/**
+ * @module
+ */
+
+/**
+ * Utility function to merge two graphql queries together
+ * This is basically copied from
+ * [graphql-query-merge](https://www.npmjs.com/package/graphql-query-merge)
+ * but can't use that due to incorrect packaging.
+ *
+ * @param {...object} queries queries to merge
+ * @returns {object} merged query
+ */
+function mergeQueries(...queries) {
+  const merged = {
+    kind: 'Document',
+    definitions: [
+      {
+        directives: [],
+        operation: 'query',
+        variableDefinitions: [],
+        kind: 'OperationDefinition',
+        selectionSet: { kind: 'SelectionSet', selections: [] },
+      },
+    ],
+  }
+
+  queries.forEach(query => {
+    const parsedQuery = query
+    parsedQuery.definitions.forEach(definition => {
+      merged.definitions[0].directives = [
+        ...merged.definitions[0].directives,
+        ...definition.directives,
+      ]
+
+      merged.definitions[0].variableDefinitions = [
+        ...merged.definitions[0].variableDefinitions,
+        ...definition.variableDefinitions,
+      ]
+
+      merged.definitions[0].selectionSet.selections = [
+        ...merged.definitions[0].selectionSet.selections,
+        ...definition.selectionSet.selections,
+      ]
+    })
+  })
+
+  return merged
+}
+
+module.exports = { mergeQueries }

core/base-service/graphql.spec.js

@@ -0,0 +1,94 @@
+'use strict'
+
+const { expect } = require('chai')
+const gql = require('graphql-tag')
+const { print } = require('graphql/language/printer')
+const { mergeQueries } = require('./graphql')
+
+require('../register-chai-plugins.spec')
+
+describe('mergeQueries function', function() {
+  it('merges valid gql queries', function() {
+    expect(
+      print(
+        mergeQueries(
+          gql`
+            query($param: String!) {
+              foo(param: $param) {
+                bar
+              }
+            }
+          `
+        )
+      )
+    ).to.equalIgnoreSpaces(
+      'query ($param: String!) { foo(param: $param) { bar } }'
+    )
+
+    expect(
+      print(
+        mergeQueries(
+          gql`
+            query($param: String!) {
+              foo(param: $param) {
+                bar
+              }
+            }
+          `,
+          gql`
+            query {
+              baz
+            }
+          `
+        )
+      )
+    ).to.equalIgnoreSpaces(
+      'query ($param: String!) { foo(param: $param) { bar } baz }'
+    )
+
+    expect(
+      print(
+        mergeQueries(
+          gql`
+            query {
+              foo
+            }
+          `,
+          gql`
+            query {
+              bar
+            }
+          `,
+          gql`
+            query {
+              baz
+            }
+          `
+        )
+      )
+    ).to.equalIgnoreSpaces('{ foo bar baz }')
+
+    expect(
+      print(
+        mergeQueries(
+          gql`
+            {
+              foo
+            }
+          `,
+          gql`
+            {
+              bar
+            }
+          `
+        )
+      )
+    ).to.equalIgnoreSpaces('{ foo bar }')
+  })
+
+  it('throws an error when passed invalid params', function() {
+    expect(() => mergeQueries('', '')).to.throw(Error)
+    expect(() => mergeQueries(undefined, 17, true)).to.throw(Error)
+    expect(() => mergeQueries(gql``, gql`foo`)).to.throw(Error)
+  })
+})

core/base-service/index.js

@@ -2,6 +2,7 @@
 
 const BaseService = require('./base')
 const BaseJsonService = require('./base-json')
+const BaseGraphqlService = require('./base-graphql')
 const NonMemoryCachingBaseService = require('./base-non-memory-caching')
 const BaseStaticService = require('./base-static')
 const BaseSvgScrapingService = require('./base-svg-scraping')
@@ -20,6 +21,7 @@ const {
 module.exports = {
   BaseService,
   BaseJsonService,
+  BaseGraphqlService,
   NonMemoryCachingBaseService,
   BaseStaticService,
   BaseSvgScrapingService,

core/base-service/json.js

@@ -0,0 +1,28 @@
+'use strict'
+
+// See available emoji at http://emoji.muan.co/
+const emojic = require('emojic')
+const { InvalidResponse } = require('./errors')
+const trace = require('./trace')
+
+function parseJson(buffer) {
+  const logTrace = (...args) => trace.logTrace('fetch', ...args)
+  let json
+  try {
+    json = JSON.parse(buffer)
+  } catch (err) {
+    logTrace(emojic.dart, 'Response JSON (unparseable)', buffer)
+    throw new InvalidResponse({
+      prettyMessage: 'unparseable json response',
+      underlyingError: err,
+    })
+  }
+  logTrace(emojic.dart, 'Response JSON (before validation)', json, {
+    deep: true,
+  })
+  return json
+}
+
+module.exports = {
+  parseJson,
+}

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

@@ -1,12 +1,8 @@
 'use strict'
 
-// eslint-disable-next-line node/no-deprecated-api
-const domain = require('domain')
 const request = require('request')
 const queryString = require('query-string')
-const LruCache = require('../../gh-badges/lib/lru-cache')
 const makeBadge = require('../../gh-badges/lib/make-badge')
-const log = require('../server/log')
 const { setCacheHeaders } = require('./cache-headers')
 const {
   Inaccessible,
@@ -14,6 +10,7 @@ const {
   ShieldsRuntimeError,
 } = require('./errors')
 const { makeSend } = require('./legacy-result-sender')
+const LruCache = require('./lru-cache')
 const coalesceBadge = require('./coalesce-badge')
 
 // We avoid calling the vendor's server for computation of the information in a
@@ -32,12 +29,6 @@ const freqRatioMax = 1 - minAccuracy
 // Request cache size of 5MB (~5000 bytes/image).
 const requestCache = new LruCache(1000)
 
-// Deep error handling for vendor hooks.
-const vendorDomain = domain.create()
-vendorDomain.on('error', err => {
-  log.error('Vendor hook error:', err.stack)
-})
-
 // These query parameters are available to any badge. They are handled by
 // `coalesceBadge`.
 const globalQueryParams = new Set([
@@ -63,6 +54,25 @@ function flattenQueryParams(queryParams) {
   return Array.from(union).sort()
 }
 
+function promisify(cachingRequest) {
+  return (uri, options) =>
+    new Promise((resolve, reject) => {
+      cachingRequest(uri, options, (err, res, buffer) => {
+        if (err) {
+          if (err instanceof ShieldsRuntimeError) {
+            reject(err)
+          } else {
+            // Wrap the error in an Inaccessible so it can be identified
+            // by the BaseService handler.
+            reject(new Inaccessible({ underlyingError: err }))
+          }
+        } else {
+          resolve({ res, buffer })
+        }
+      })
+    })
+}
+
 // handlerOptions can contain:
 // - handler: The service's request handler function
 // - queryParams: An array of the field names of any custom query parameters
@@ -175,12 +185,7 @@ function handleRequest(cacheHeaderConfig, handlerOptions) {
         {}
       )
       const svg = makeBadge(badgeData)
-      let extension
-      try {
-        extension = match[0].split('.').pop()
-      } catch (e) {
-        extension = 'svg'
-      }
+      const extension = (match.slice(-1)[0] || '.svg').replace(/^\./, '')
       setCacheHeadersOnResponse(ask.res)
       makeSend(extension, ask.res, end)(svg)
     }, 25000)
@@ -231,70 +236,51 @@ function handleRequest(cacheHeaderConfig, handlerOptions) {
       })
     }
 
-    // Wrapper around `cachingRequest` that returns a promise rather than
-    // needing to pass a callback.
-    cachingRequest.asPromise = (uri, options) =>
-      new Promise((resolve, reject) => {
-        cachingRequest(uri, options, (err, res, buffer) => {
-          if (err) {
-            if (err instanceof ShieldsRuntimeError) {
-              reject(err)
-            } else {
-              // Wrap the error in an Inaccessible so it can be identified
-              // by the BaseService handler.
-              reject(new Inaccessible({ underlyingError: err }))
-            }
-          } else {
-            resolve({ res, buffer })
-          }
-        })
-      })
+    // Wrapper around `cachingRequest` that returns a promise rather than needing
+    // to pass a callback.
+    cachingRequest.asPromise = promisify(cachingRequest)
 
-    vendorDomain.run(() => {
-      const result = handlerOptions.handler(
-        filteredQueryParams,
-        match,
-        // eslint-disable-next-line mocha/prefer-arrow-callback
-        function sendBadge(format, badgeData) {
-          if (serverUnresponsive) {
-            return
-          }
-          clearTimeout(serverResponsive)
-          // Check for a change in the data.
-          let dataHasChanged = false
-          if (
-            cached !== undefined &&
-            cached.data.badgeData.text[1] !== badgeData.text[1]
-          ) {
-            dataHasChanged = true
-          }
-          // Add format to badge data.
-          badgeData.format = format
-          // Update information in the cache.
-          const updatedCache = {
-            reqs: cached ? cached.reqs + 1 : 1,
-            dataChange: cached
-              ? cached.dataChange + (dataHasChanged ? 1 : 0)
-              : 1,
-            time: +reqTime,
-            interval: cacheInterval,
-            data: { format, badgeData },
-          }
-          requestCache.set(cacheIndex, updatedCache)
-          if (!cachedVersionSent) {
-            const svg = makeBadge(badgeData)
-            setCacheHeadersOnResponse(ask.res, badgeData.cacheLengthSeconds)
-            makeSend(format, ask.res, end)(svg)
-          }
-        },
-        cachingRequest
-      )
-      if (result && result.catch) {
-        result.catch(err => {
-          throw err
-        })
-      }
-    })
+    const result = handlerOptions.handler(
+      filteredQueryParams,
+      match,
+      // eslint-disable-next-line mocha/prefer-arrow-callback
+      function sendBadge(format, badgeData) {
+        if (serverUnresponsive) {
+          return
+        }
+        clearTimeout(serverResponsive)
+        // Check for a change in the data.
+        let dataHasChanged = false
+        if (
+          cached !== undefined &&
+          cached.data.badgeData.text[1] !== badgeData.text[1]
+        ) {
+          dataHasChanged = true
+        }
+        // Add format to badge data.
+        badgeData.format = format
+        // Update information in the cache.
+        const updatedCache = {
+          reqs: cached ? cached.reqs + 1 : 1,
+          dataChange: cached ? cached.dataChange + (dataHasChanged ? 1 : 0) : 1,
+          time: +reqTime,
+          interval: cacheInterval,
+          data: { format, badgeData },
+        }
+        requestCache.set(cacheIndex, updatedCache)
+        if (!cachedVersionSent) {
+          const svg = makeBadge(badgeData)
+          setCacheHeadersOnResponse(ask.res, badgeData.cacheLengthSeconds)
+          makeSend(format, ask.res, end)(svg)
+        }
+      },
+      cachingRequest
+    )
+    if (result && result.catch) {
+      result.catch(err => {
+        throw err
+      })
+    }
   }
 }
 
@@ -304,6 +290,7 @@ function clearRequestCache() {
 
 module.exports = {
   handleRequest,
+  promisify,
   clearRequestCache,
   // Expose for testing.
   _requestCache: requestCache,

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

@@ -1,11 +1,10 @@
 'use strict'
 
 const { expect } = require('chai')
-// https://github.com/nock/nock/issues/1523
-const got = require('got').extend({ retry: 0 })
 const nock = require('nock')
 const portfinder = require('portfinder')
 const Camp = require('camp')
+const got = require('../got-test-client')
 const coalesceBadge = require('./coalesce-badge')
 const {
   handleRequest,

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

@@ -1,15 +1,6 @@
 'use strict'
 
-const fs = require('fs')
-const path = require('path')
 const stream = require('stream')
-const svg2img = require('../../gh-badges/lib/svg-to-img')
-const log = require('../server/log')
-
-const internalError = fs.readFileSync(
-  path.resolve(__dirname, '..', 'server', 'error-pages', '500.html'),
-  'utf-8'
-)
 
 function streamFromString(str) {
   const newStream = new stream.Readable()
@@ -25,21 +16,6 @@ function sendSVG(res, askres, end) {
   end(null, { template: streamFromString(res) })
 }
 
-function sendOther(format, res, askres, end) {
-  askres.setHeader('Content-Type', `image/${format}`)
-  svg2img(res, format)
-    // This interacts with callback code and can't use async/await.
-    // eslint-disable-next-line promise/prefer-await-to-then
-    .then(data => {
-      end(null, { template: streamFromString(data) })
-    })
-    .catch(err => {
-      // This emits status code 200, though 500 would be preferable.
-      log.error('svg2img error', err)
-      end(internalError)
-    })
-}
-
 function sendJSON(res, askres, end) {
   askres.setHeader('Content-Type', 'application/json')
   askres.setHeader('Access-Control-Allow-Origin', '*')
@@ -52,7 +28,7 @@ function makeSend(format, askres, end) {
   } else if (format === 'json') {
     return res => sendJSON(res, askres, end)
   } else {
-    return res => sendOther(format, res, askres, end)
+    throw Error(`Unrecognized format: ${format}`)
   }
 }
 

core/base-service/lru-cache.js

@@ -7,6 +7,23 @@ const typeEnum = {
   heap: 1,
 }
 
+// In bytes.
+let heapSize
+function computeHeapSize() {
+  return (heapSize = process.memoryUsage().heapTotal)
+}
+
+let heapSizeTimeout
+function getHeapSize() {
+  if (heapSizeTimeout == null) {
+    // Compute the heap size every 60 seconds.
+    heapSizeTimeout = setInterval(computeHeapSize, 60 * 1000)
+    return computeHeapSize()
+  } else {
+    return heapSize
+  }
+}
+
 function CacheSlot(key, value) {
   this.key = key
   this.value = value
@@ -116,20 +133,4 @@ Cache.prototype = {
   },
 }
 
-// In bytes.
-let heapSize
-let heapSizeTimeout
-function getHeapSize() {
-  if (heapSizeTimeout == null) {
-    // Compute the heap size every 60 seconds.
-    heapSizeTimeout = setInterval(computeHeapSize, 60 * 1000)
-    return computeHeapSize()
-  } else {
-    return heapSize
-  }
-}
-function computeHeapSize() {
-  return (heapSize = process.memoryUsage().heapTotal)
-}
-
 module.exports = Cache

core/base-service/metric-helper.js

@@ -0,0 +1,45 @@
+'use strict'
+
+const { performance } = require('perf_hooks')
+
+class MetricHelper {
+  constructor({ metricInstance }, { category, serviceFamily, name }) {
+    if (metricInstance) {
+      this.metricInstance = metricInstance
+      this.serviceRequestCounter = metricInstance.createNumRequestCounter({
+        category,
+        serviceFamily,
+        name,
+      })
+    } else {
+      this.metricInstance = undefined
+      this.serviceRequestCounter = undefined
+    }
+  }
+
+  static create({ metricInstance, ServiceClass }) {
+    const { category, serviceFamily, name } = ServiceClass
+    return new this({ metricInstance }, { category, serviceFamily, name })
+  }
+
+  startRequest() {
+    const { metricInstance, serviceRequestCounter } = this
+
+    const requestStartTime = performance.now()
+
+    return {
+      noteResponseSent() {
+        if (metricInstance) {
+          const elapsedTime = performance.now() - requestStartTime
+          metricInstance.noteResponseTime(elapsedTime)
+        }
+
+        if (serviceRequestCounter) {
+          serviceRequestCounter.inc()
+        }
+      },
+    }
+  }
+}
+
+module.exports = { MetricHelper }

core/base-service/redirector.js

@@ -2,14 +2,16 @@
 
 const camelcase = require('camelcase')
 const emojic = require('emojic')
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const queryString = require('query-string')
+const log = require('../server/log')
 const BaseService = require('./base')
 const {
   serverHasBeenUpSinceResourceCached,
   setCacheHeadersForStaticResource,
 } = require('./cache-headers')
 const { isValidCategory } = require('./categories')
+const { MetricHelper } = require('./metric-helper')
 const { isValidRoute, prepareRoute, namedParamsForMatch } = require('./route')
 const trace = require('./trace')
 
@@ -62,11 +64,15 @@ module.exports = function redirector(attrs) {
       return route
     }
 
-    static register({ camp, requestCounter }) {
-      const { regex, captureNames } = prepareRoute(this.route)
+    static register({ camp, metricInstance }, { rasterUrl }) {
+      const { regex, captureNames } = prepareRoute({
+        ...this.route,
+        withPng: Boolean(rasterUrl),
+      })
 
-      const serviceRequestCounter = this._createServiceRequestCounter({
-        requestCounter,
+      const metricHelper = MetricHelper.create({
+        metricInstance,
+        ServiceClass: this,
       })
 
       camp.route(regex, async (queryParams, match, end, ask) => {
@@ -77,6 +83,8 @@ module.exports = function redirector(attrs) {
           return
         }
 
+        const metricHandle = metricHelper.startRequest()
+
         const namedParams = namedParamsForMatch(captureNames, match, this)
         trace.logTrace(
           'inbound',
@@ -103,20 +111,27 @@ module.exports = function redirector(attrs) {
         }
 
         // The final capture group is the extension.
-        const format = match.slice(-1)[0]
-        const redirectUrl = `${targetPath}.${format}${urlSuffix}`
+        const format = (match.slice(-1)[0] || '.svg').replace(/^\./, '')
+        const redirectUrl = `${
+          format === 'png' ? rasterUrl : ''
+        }${targetPath}.${format}${urlSuffix}`
         trace.logTrace('outbound', emojic.shield, 'Redirect URL', redirectUrl)
 
-        ask.res.statusCode = 301
-        ask.res.setHeader('Location', redirectUrl)
-
+        try {
+          ask.res.statusCode = 301
+          ask.res.setHeader('Location', redirectUrl)
+        } catch (e) {
+          log.error(new Error(`An invalid URL in '${this.name}' redirector.`))
+          ask.res.statusCode = 302
+          ask.res.setHeader('Location', '/badge/badge-inaccessible-lightgray')
+        }
         // To avoid caching mistakes for a long time, and to make this simpler
         // to reason about, use the same cache semantics as the static badge.
         setCacheHeadersForStaticResource(ask.res)
 
         ask.res.end()
 
-        serviceRequestCounter.inc()
+        metricHandle.noteResponseSent()
       })
     }
   }

core/base-service/redirector.spec.js

@@ -1,9 +1,9 @@
 'use strict'
 
 const Camp = require('camp')
-const got = require('got')
 const portfinder = require('portfinder')
 const { expect } = require('chai')
+const got = require('../got-test-client')
 const redirector = require('./redirector')
 
 describe('Redirector', function() {
@@ -75,7 +75,10 @@ describe('Redirector', function() {
         transformPath,
         dateAdded,
       })
-      ServiceClass.register({ camp }, {})
+      ServiceClass.register(
+        { camp },
+        { rasterUrl: 'http://raster.example.test' }
+      )
     })
 
     it('should redirect as configured', async function() {
@@ -90,7 +93,20 @@ describe('Redirector', function() {
       expect(headers.location).to.equal('/new/service/hello-world.svg')
     })
 
-    it('should preserve the extension', async function() {
+    // https://github.com/badges/shields/issues/4013
+    it('should temporarily redirect to a badge with message "inaccesible" when redirect URL is invalid (contains invalid characters)', async function() {
+      const { statusCode, headers } = await got(
+        `${baseUrl}/very/old/service/hello\nworld.svg`,
+        {
+          followRedirect: false,
+        }
+      )
+
+      expect(statusCode).to.equal(302)
+      expect(headers.location).to.equal('/badge/badge-inaccessible-lightgray')
+    })
+
+    it('should redirect raster extensions to the canonical path as configured', async function() {
       const { statusCode, headers } = await got(
         `${baseUrl}/very/old/service/hello-world.png`,
         {
@@ -99,7 +115,9 @@ describe('Redirector', function() {
       )
 
       expect(statusCode).to.equal(301)
-      expect(headers.location).to.equal('/new/service/hello-world.png')
+      expect(headers.location).to.equal(
+        'http://raster.example.test/new/service/hello-world.png'
+      )
     })
 
     it('should forward the query params', async function() {

core/base-service/route.js

@@ -1,6 +1,7 @@
 'use strict'
 
-const Joi = require('joi')
+const escapeStringRegexp = require('escape-string-regexp')
+const Joi = require('@hapi/joi')
 const pathToRegexp = require('path-to-regexp')
 
 function makeFullUrl(base, partialUrl) {
@@ -13,7 +14,7 @@ const isValidRoute = Joi.object({
     .required(),
   pattern: Joi.string().allow(''),
   format: Joi.string(),
-  capture: Joi.alternatives().when('format', {
+  capture: Joi.alternatives().conditional('format', {
     is: Joi.string().required(),
     then: Joi.array().items(Joi.string().required()),
   }),
@@ -26,18 +27,17 @@ function assertValidRoute(route, message = undefined) {
   Joi.assert(route, isValidRoute, message)
 }
 
-function prepareRoute({ base, pattern, format, capture }) {
+function prepareRoute({ base, pattern, format, capture, withPng }) {
+  const extensionRegex = ['', '.svg', '.json']
+    .concat(withPng ? ['.png'] : [])
+    .map(escapeStringRegexp)
+    .join('|')
   let regex, captureNames
   if (pattern === undefined) {
-    regex = new RegExp(
-      `^${makeFullUrl(base, format)}\\.(svg|png|gif|jpg|json)$`
-    )
+    regex = new RegExp(`^${makeFullUrl(base, format)}(${extensionRegex})$`)
     captureNames = capture || []
   } else {
-    const fullPattern = `${makeFullUrl(
-      base,
-      pattern
-    )}.:ext(svg|png|gif|jpg|json)`
+    const fullPattern = `${makeFullUrl(base, pattern)}:ext(${extensionRegex})`
     const keys = []
     regex = pathToRegexp(fullPattern, keys, {
       strict: true,
@@ -55,9 +55,7 @@ function namedParamsForMatch(captureNames = [], match, ServiceClass) {
 
   if (captureNames.length !== captures.length) {
     throw new Error(
-      `Service ${
-        ServiceClass.name
-      } declares incorrect number of named params ` +
+      `Service ${ServiceClass.name} declares incorrect number of named params ` +
         `(expected ${captures.length}, got ${captureNames.length})`
     )
   }
@@ -71,8 +69,8 @@ function namedParamsForMatch(captureNames = [], match, ServiceClass) {
 
 function getQueryParamNames({ queryParamSchema }) {
   if (queryParamSchema) {
-    const { children, renames = [] } = Joi.describe(queryParamSchema)
-    return Object.keys(children).concat(renames.map(({ from }) => from))
+    const { keys, renames = [] } = queryParamSchema.describe()
+    return Object.keys(keys).concat(renames.map(({ from }) => from))
   } else {
     return []
   }

core/base-service/route.spec.js

@@ -1,7 +1,7 @@
 'use strict'
 
 const { expect } = require('chai')
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const { test, given, forCases } = require('sazerac')
 const {
   prepareRoute,
@@ -19,13 +19,7 @@ describe('Route helpers', function() {
 
     const regexExec = str => regex.exec(str)
     test(regexExec, () => {
-      forCases([
-        given('/foo/bar.bar.bar.zip'),
-        given('/foo/bar/bar.svg'),
-        // This is a valid example with the wrong extension separator, to
-        // test that we only accept a `.`.
-        given('/foo/bar.bar.bar_svg'),
-      ]).expect(null)
+      given('/foo/bar/bar.svg').expect(null)
     })
 
     const namedParams = str =>
@@ -33,30 +27,25 @@ describe('Route helpers', function() {
     test(namedParams, () => {
       forCases([
         given('/foo/bar.bar.bar.svg'),
-        given('/foo/bar.bar.bar.png'),
-        given('/foo/bar.bar.bar.gif'),
-        given('/foo/bar.bar.bar.jpg'),
         given('/foo/bar.bar.bar.json'),
       ]).expect({ namedParamA: 'bar.bar.bar' })
+
+      // This pattern catches bugs related to escaping the extension separator.
+      given('/foo/bar.bar.bar_svg').expect({ namedParamA: 'bar.bar.bar_svg' })
+      given('/foo/bar.bar.bar.zip').expect({ namedParamA: 'bar.bar.bar.zip' })
     })
   })
 
   context('A `format` with a named param is declared', function() {
     const { regex, captureNames } = prepareRoute({
       base: 'foo',
-      format: '([^/]+)',
+      format: '([^/]+?)',
       capture: ['namedParamA'],
     })
 
     const regexExec = str => regex.exec(str)
     test(regexExec, () => {
-      forCases([
-        given('/foo/bar.bar.bar.zip'),
-        given('/foo/bar/bar.svg'),
-        // This is a valid example with the wrong extension separator, to
-        // test that we only accept a `.`.
-        given('/foo/bar.bar.bar_svg'),
-      ]).expect(null)
+      given('/foo/bar/bar.svg').expect(null)
     })
 
     const namedParams = str =>
@@ -64,11 +53,12 @@ describe('Route helpers', function() {
     test(namedParams, () => {
       forCases([
         given('/foo/bar.bar.bar.svg'),
-        given('/foo/bar.bar.bar.png'),
-        given('/foo/bar.bar.bar.gif'),
-        given('/foo/bar.bar.bar.jpg'),
         given('/foo/bar.bar.bar.json'),
       ]).expect({ namedParamA: 'bar.bar.bar' })
+
+      // This pattern catches bugs related to escaping the extension separator.
+      given('/foo/bar.bar.bar_svg').expect({ namedParamA: 'bar.bar.bar_svg' })
+      given('/foo/bar.bar.bar.zip').expect({ namedParamA: 'bar.bar.bar.zip' })
     })
   })
 
@@ -83,9 +73,6 @@ describe('Route helpers', function() {
     test(namedParams, () => {
       forCases([
         given('/foo/bar.bar.bar.svg'),
-        given('/foo/bar.bar.bar.png'),
-        given('/foo/bar.bar.bar.gif'),
-        given('/foo/bar.bar.bar.jpg'),
         given('/foo/bar.bar.bar.json'),
       ]).expect({})
     })

core/base-service/service-definitions.js

@@ -1,13 +1,13 @@
 'use strict'
 
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 
 // This should be kept in sync with the schema in
-// `frontend/lib/service-definitions/service-definition-prop-types.js`.
+// `frontend/lib/service-definitions/index.ts`.
 
 const arrayOfStrings = Joi.array()
   .items(Joi.string())
-  .allow([])
+  .min(0)
   .required()
 
 const objectOfKeyValues = Joi.object()
@@ -66,6 +66,7 @@ const serviceDefinitionExport = Joi.object({
       Joi.object({
         id: Joi.string().required(),
         name: Joi.string().required(),
+        keywords: arrayOfStrings,
       })
     )
     .required(),

core/base-service/validate.js

@@ -1,7 +1,7 @@
 'use strict'
 
 const emojic = require('emojic')
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const trace = require('./trace')
 
 function validate(
@@ -16,16 +16,15 @@ function validate(
   data,
   schema
 ) {
-  if (!schema || !schema.isJoi) {
+  if (!schema || !Joi.isSchema(schema)) {
     throw Error('A Joi schema is required')
   }
-  const options = allowAndStripUnknownKeys
-    ? {
-        allowUnknown: true,
-        stripUnknown: true,
-      }
-    : undefined
-  const { error, value } = Joi.validate(data, schema, options)
+  const options = { abortEarly: false }
+  if (allowAndStripUnknownKeys) {
+    options['allowUnknown'] = true
+    options['stripUnknown'] = true
+  }
+  const { error, value } = schema.validate(data, options)
   if (error) {
     trace.logTrace(
       'validate',

core/base-service/validate.spec.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const { expect } = require('chai')
 const sinon = require('sinon')
 const trace = require('./trace')
@@ -72,7 +72,7 @@ describe('validate', function() {
       } catch (e) {
         expect(e).to.be.an.instanceof(InvalidParameter)
         expect(e.message).to.equal(
-          'Invalid Parameter: child "requiredString" fails because ["requiredString" must be a string]'
+          'Invalid Parameter: "requiredString" must be a string'
         )
         expect(e.prettyMessage).to.equal(prettyErrorMessage)
       }
@@ -80,7 +80,7 @@ describe('validate', function() {
         'validate',
         sinon.match.string,
         traceErrorMessage,
-        'child "requiredString" fails because ["requiredString" must be a string]'
+        '"requiredString" must be a string'
       )
     })
 
@@ -98,7 +98,7 @@ describe('validate', function() {
         } catch (e) {
           expect(e).to.be.an.instanceof(InvalidParameter)
           expect(e.message).to.equal(
-            'Invalid Parameter: child "requiredString" fails because ["requiredString" must be a string]'
+            'Invalid Parameter: "requiredString" must be a string'
           )
           expect(e.prettyMessage).to.equal(
             `${prettyErrorMessage}: requiredString`

core/got-test-client.js

@@ -0,0 +1,6 @@
+'use strict'
+
+const got = require('got')
+
+// https://github.com/nock/nock/issues/1523
+module.exports = got.extend({ retry: 0 })

core/server/log.js

@@ -1,6 +1,5 @@
 'use strict'
-const Raven = require('raven')
-const throttle = require('lodash.throttle')
+const Sentry = require('@sentry/node')
 
 const listeners = []
 
@@ -30,22 +29,11 @@ module.exports = function log(...msg) {
   console.log(d, ...msg)
 }
 
-const throttledConsoleError = throttle(console.error, 10000, {
-  trailing: false,
-})
-
-module.exports.error = function error(...msg) {
+module.exports.error = function error(err) {
   const d = date()
-  listeners.forEach(f => f(d, ...msg))
-  Raven.captureException(msg, sendErr => {
-    if (sendErr) {
-      throttledConsoleError(
-        'Failed to send captured exception to Sentry',
-        sendErr.message
-      )
-    }
-  })
-  console.error(d, ...msg)
+  listeners.forEach(f => f(d, err))
+  Sentry.captureException(err)
+  console.error(d, err)
 }
 
 module.exports.addListener = function addListener(func) {

core/server/log.spec.js

@@ -1,63 +0,0 @@
-'use strict'
-const chai = require('chai')
-const expect = chai.expect
-const sinon = require('sinon')
-const sinonChai = require('sinon-chai')
-const Raven = require('raven')
-
-chai.use(sinonChai)
-
-function requireUncached(module) {
-  delete require.cache[require.resolve(module)]
-  return require(module)
-}
-
-describe('log', function() {
-  describe('error', function() {
-    before(function() {
-      this.clock = sinon.useFakeTimers()
-      sinon.stub(Raven, 'captureException').callsFake((e, callback) => {
-        callback(new Error(`Cannot send message "${e}" to Sentry.`))
-      })
-      // we have to create a spy before requiring 'error' function
-      sinon.spy(console, 'error')
-      this.error = requireUncached('./log').error
-    })
-
-    after(function() {
-      this.clock.restore()
-      console.error.restore()
-      Raven.captureException.restore()
-    })
-
-    it('should throttle errors from Raven client', function() {
-      this.error('test error 1')
-      this.error('test error 2')
-      this.error('test error 3')
-      this.clock.tick(11000)
-      this.error('test error 4')
-      this.error('test error 5')
-
-      expect(console.error).to.be.calledWithExactly(
-        'Failed to send captured exception to Sentry',
-        'Cannot send message "test error 1" to Sentry.'
-      )
-      expect(console.error).to.not.be.calledWithExactly(
-        'Failed to send captured exception to Sentry',
-        'Cannot send message "test error 2" to Sentry.'
-      )
-      expect(console.error).to.not.be.calledWithExactly(
-        'Failed to send captured exception to Sentry',
-        'Cannot send message "test error 3" to Sentry.'
-      )
-      expect(console.error).to.be.calledWithExactly(
-        'Failed to send captured exception to Sentry',
-        'Cannot send message "test error 4" to Sentry.'
-      )
-      expect(console.error).to.not.be.calledWithExactly(
-        'Failed to send captured exception to Sentry',
-        'Cannot send message "test error 5" to Sentry.'
-      )
-    })
-  })
-})

core/server/monitor.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const serverSecrets = require('../../lib/server-secrets')
+const config = require('config').util.toObject()
 const secretIsValid = require('./secret-is-valid')
 const RateLimit = require('./rate-limit')
 const log = require('./log')
@@ -16,9 +16,11 @@ function secretInvalid(req, res) {
   return false
 }
 
-function setRoutes({ rateLimit }, server) {
+function setRoutes({ rateLimit }, { server, metricInstance }) {
   const ipRateLimit = new RateLimit({
-    whitelist: /^192\.30\.252\.\d+$/, // Whitelist GitHub IPs.
+    // Exclude IPs for GitHub Camo, determined experimentally by running e.g.
+    // `curl --insecure -u ":shields-secret" https://s0.shields-server.com/sys/rate-limit`
+    whitelist: /^(?:192\.30\.252\.\d+)|(?:140\.82\.115\.\d+)$/,
   })
   const badgeTypeRateLimit = new RateLimit({ maxHitsPerPeriod: 3000 })
   const refererRateLimit = new RateLimit({
@@ -44,12 +46,15 @@ function setRoutes({ rateLimit }, server) {
       const referer = req.headers['referer']
 
       if (ipRateLimit.isBanned(ip, req, res)) {
+        metricInstance.noteRateLimitExceeded('ip')
         return
       }
       if (badgeTypeRateLimit.isBanned(badgeType, req, res)) {
+        metricInstance.noteRateLimitExceeded('badge_type')
         return
       }
       if (refererRateLimit.isBanned(referer, req, res)) {
+        metricInstance.noteRateLimitExceeded('referrer')
         return
       }
     }
@@ -58,7 +63,7 @@ function setRoutes({ rateLimit }, server) {
   })
 
   server.get('/sys/network', (req, res) => {
-    res.json({ ips: serverSecrets.shields_ips })
+    res.json({ ips: config.public.shields_ips })
   })
 
   server.ws('/sys/logs', socket => {

core/server/prometheus-metrics.js

@@ -1,16 +1,65 @@
 'use strict'
 
+const decamelize = require('decamelize')
 const prometheus = require('prom-client')
 
 module.exports = class PrometheusMetrics {
   constructor() {
     this.register = new prometheus.Registry()
-    this.requestCounter = new prometheus.Counter({
-      name: 'service_requests_total',
-      help: 'Total service requests',
-      labelNames: ['category', 'family', 'service'],
-      registers: [this.register],
-    })
+    this.counters = {
+      numRequests: new prometheus.Counter({
+        name: 'service_requests_total',
+        help: 'Total service requests',
+        labelNames: ['category', 'family', 'service'],
+        registers: [this.register],
+      }),
+      responseTime: new prometheus.Histogram({
+        name: 'service_response_millis',
+        help: 'Service response time in milliseconds',
+        // 250 ms increments up to 2 seconds, then 500 ms increments up to 8
+        // seconds, then 1 second increments up to 15 seconds.
+        buckets: [
+          250,
+          500,
+          750,
+          1000,
+          1250,
+          1500,
+          1750,
+          2000,
+          2250,
+          2500,
+          2750,
+          3000,
+          3250,
+          3500,
+          3750,
+          4000,
+          4500,
+          5000,
+          5500,
+          6000,
+          6500,
+          7000,
+          7500,
+          8000,
+          9000,
+          10000,
+          11000,
+          12000,
+          13000,
+          14000,
+          15000,
+        ],
+        registers: [this.register],
+      }),
+      rateLimitExceeded: new prometheus.Counter({
+        name: 'rate_limit_exceeded_total',
+        help: 'Count of rate limit exceeded by type',
+        labelNames: ['rate_limit_type'],
+        registers: [this.register],
+      }),
+    }
   }
 
   async initialize(server) {
@@ -30,4 +79,20 @@ module.exports = class PrometheusMetrics {
       this.interval = undefined
     }
   }
+
+  /**
+   * @returns {object} `{ inc() {} }`.
+   */
+  createNumRequestCounter({ category, serviceFamily, name }) {
+    const service = decamelize(name)
+    return this.counters.numRequests.labels(category, serviceFamily, service)
+  }
+
+  noteResponseTime(responseTime) {
+    return this.counters.responseTime.observe(responseTime)
+  }
+
+  noteRateLimitExceeded(rateLimitType) {
+    return this.counters.rateLimitExceeded.labels(rateLimitType).inc()
+  }
 }

core/server/prometheus-metrics.spec.js

@@ -1,10 +1,9 @@
 'use strict'
 
 const { expect } = require('chai')
-// https://github.com/nock/nock/issues/1523
-const got = require('got').extend({ retry: 0 })
 const Camp = require('camp')
 const portfinder = require('portfinder')
+const got = require('../got-test-client')
 const Metrics = require('./prometheus-metrics')
 
 describe('Prometheus metrics route', function() {

core/server/secret-is-valid.js

@@ -2,13 +2,6 @@
 
 const serverSecrets = require('../../lib/server-secrets')
 
-function secretIsValid(secret = '') {
-  return (
-    serverSecrets.shields_secret &&
-    constEq(secret, serverSecrets.shields_secret)
-  )
-}
-
 function constEq(a, b) {
   if (a.length !== b.length) {
     return false
@@ -20,4 +13,9 @@ function constEq(a, b) {
   return zero === 0
 }
 
-module.exports = secretIsValid
+module.exports = function secretIsValid(secret = '') {
+  return (
+    serverSecrets.shields_secret &&
+    constEq(secret, serverSecrets.shields_secret)
+  )
+}

core/server/server.js

@@ -1,10 +1,12 @@
 'use strict'
+/**
+ * @module
+ */
 
-const fs = require('fs')
 const path = require('path')
 const url = require('url')
 const bytes = require('bytes')
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const Camp = require('camp')
 const makeBadge = require('../../gh-badges/lib/make-badge')
 const GithubConstellation = require('../../services/github/github-constellation')
@@ -16,7 +18,7 @@ const {
   clearRequestCache,
 } = require('../base-service/legacy-request-handler')
 const { clearRegularUpdateCache } = require('../legacy/regular-update')
-const { staticBadgeUrl } = require('../badge-urls/make-badge-url')
+const { rasterRedirectUrl } = require('../badge-urls/make-badge-url')
 const log = require('./log')
 const sysMonitor = require('./monitor')
 const PrometheusMetrics = require('./prometheus-metrics')
@@ -24,11 +26,6 @@ const PrometheusMetrics = require('./prometheus-metrics')
 const optionalUrl = Joi.string().uri({ scheme: ['http', 'https'] })
 const requiredUrl = optionalUrl.required()
 
-const notFound = fs.readFileSync(
-  path.resolve(__dirname, 'error-pages', '404.html'),
-  'utf-8'
-)
-
 const publicConfigSchema = Joi.object({
   bind: {
     port: Joi.number().port(),
@@ -52,6 +49,7 @@ const publicConfigSchema = Joi.object({
     cert: Joi.string(),
   },
   redirectUrl: optionalUrl,
+  rasterUrl: optionalUrl,
   cors: {
     allowedOrigin: Joi.array()
       .items(optionalUrl)
@@ -59,7 +57,6 @@ const publicConfigSchema = Joi.object({
   },
   persistence: {
     dir: Joi.string().required(),
-    redisUrl: optionalUrl,
   },
   services: {
     github: {
@@ -101,16 +98,34 @@ const privateConfigSchema = Joi.object({
   nexus_user: Joi.string(),
   nexus_pass: Joi.string(),
   npm_token: Joi.string(),
+  redis_url: Joi.string().uri({ scheme: ['redis', 'rediss'] }),
   sentry_dsn: Joi.string(),
   shields_ips: Joi.array().items(Joi.string().ip()),
   shields_secret: Joi.string(),
   sl_insight_userUuid: Joi.string(),
   sl_insight_apiToken: Joi.string(),
   sonarqube_token: Joi.string(),
+  twitch_client_id: Joi.string(),
+  twitch_client_secret: Joi.string(),
   wheelmap_token: Joi.string(),
 }).required()
 
-module.exports = class Server {
+/**
+ * The Server is based on the web framework Scoutcamp. It creates
+ * an http server, sets up helpers for token persistence and monitoring.
+ * Then it loads all the services, injecting dependencies as it
+ * asks each one to register its route with Scoutcamp.
+ */
+class Server {
+  /**
+   * Badge Server Constructor
+   *
+   * @param {object} config Configuration object read from config yaml files
+   *    by https://www.npmjs.com/package/config and validated against
+   *    publicConfigSchema and privateConfigSchema
+   * @see https://github.com/badges/shields/blob/master/doc/production-hosting.md#configuration
+   * @see https://github.com/badges/shields/blob/master/doc/server-secrets.md
+   */
   constructor(config) {
     const publicConfig = Joi.attempt(config.public, publicConfigSchema)
     let privateConfig
@@ -132,9 +147,10 @@ module.exports = class Server {
     this.githubConstellation = new GithubConstellation({
       persistence: publicConfig.persistence,
       service: publicConfig.services.github,
+      private: privateConfig,
     })
     if (publicConfig.metrics.prometheus.enabled) {
-      this.metrics = new PrometheusMetrics()
+      this.metricInstance = new PrometheusMetrics()
     }
   }
 
@@ -160,77 +176,119 @@ module.exports = class Server {
     })
   }
 
+  /**
+   * Set up Scoutcamp routes for 404/not found responses
+   */
   registerErrorHandlers() {
-    const { camp } = this
+    const { camp, config } = this
+    const {
+      public: { rasterUrl },
+    } = config
 
-    camp.notfound(/\.(svg|png|gif|jpg|json)/, (query, match, end, request) => {
+    camp.route(/\.(gif|jpg)$/, (query, match, end, request) => {
       const [, format] = match
-      const svg = makeBadge({
-        text: ['404', 'badge not found'],
-        color: 'red',
-        format,
-      })
-      makeSend(format, request.res, end)(svg)
-    })
-
-    camp.notfound(/.*/, (query, match, end, request) => {
-      end(notFound)
-    })
-  }
-
-  registerServices() {
-    const { config, camp } = this
-    const { apiProvider: githubApiProvider } = this.githubConstellation
-    const { requestCounter } = this.metrics || {}
-
-    loadServiceClasses().forEach(serviceClass =>
-      serviceClass.register(
-        { camp, handleRequest, githubApiProvider, requestCounter },
-        {
-          handleInternalErrors: config.public.handleInternalErrors,
-          cacheHeaders: config.public.cacheHeaders,
-          profiling: config.public.profiling,
-          fetchLimitBytes: bytes(config.public.fetchLimit),
-        }
+      makeSend('svg', request.res, end)(
+        makeBadge({
+          text: ['410', `${format} no longer available`],
+          color: 'lightgray',
+          format: 'svg',
+        })
       )
-    )
+    })
+
+    if (!rasterUrl) {
+      camp.route(/\.png$/, (query, match, end, request) => {
+        makeSend('svg', request.res, end)(
+          makeBadge({
+            text: ['404', 'raster badges not available'],
+            color: 'lightgray',
+            format: 'svg',
+          })
+        )
+      })
+    }
+
+    camp.notfound(/(\.svg|\.json|)$/, (query, match, end, request) => {
+      const [, extension] = match
+      const format = (extension || '.svg').replace(/^\./, '')
+
+      makeSend(format, request.res, end)(
+        makeBadge({
+          text: ['404', 'badge not found'],
+          color: 'red',
+          format,
+        })
+      )
+    })
   }
 
+  /**
+   * Set up a couple of redirects:
+   * One for the raster badges.
+   * Another to redirect the base URL /
+   * (we use this to redirect {@link https://img.shields.io/}
+   * to {@link https://shields.io/} )
+   */
   registerRedirects() {
     const { config, camp } = this
+    const {
+      public: { rasterUrl, redirectUrl },
+    } = config
 
-    // Any badge, old version. This route must be registered last.
-    camp.route(/^\/([^/]+)\/(.+).png$/, (queryParams, match, end, ask) => {
-      const [, label, message] = match
-      const { color } = queryParams
+    if (rasterUrl) {
+      // Redirect to the raster server for raster versions of modern badges.
+      camp.route(/\.png$/, (queryParams, match, end, ask) => {
+        ask.res.statusCode = 301
+        ask.res.setHeader(
+          'Location',
+          rasterRedirectUrl({ rasterUrl }, ask.req.url)
+        )
 
-      const redirectUrl = staticBadgeUrl({
-        label,
-        message,
-        // Fixes https://github.com/badges/shields/issues/3260
-        color: color ? color.toString() : undefined,
-        format: 'png',
+        const cacheDuration = (30 * 24 * 3600) | 0 // 30 days.
+        ask.res.setHeader('Cache-Control', `max-age=${cacheDuration}`)
+
+        ask.res.end()
       })
+    }
 
-      ask.res.statusCode = 301
-      ask.res.setHeader('Location', redirectUrl)
-
-      // The redirect is permanent.
-      const cacheDuration = (365 * 24 * 3600) | 0 // 1 year
-      ask.res.setHeader('Cache-Control', `max-age=${cacheDuration}`)
-
-      ask.res.end()
-    })
-
-    if (config.public.redirectUrl) {
+    if (redirectUrl) {
       camp.route(/^\/$/, (data, match, end, ask) => {
         ask.res.statusCode = 302
-        ask.res.setHeader('Location', config.public.redirectUrl)
+        ask.res.setHeader('Location', redirectUrl)
         ask.res.end()
       })
     }
   }
 
+  /**
+   * Iterate all the service classes defined in /services,
+   * load each service and register a Scoutcamp route for each service.
+   */
+  registerServices() {
+    const { config, camp, metricInstance } = this
+    const { apiProvider: githubApiProvider } = this.githubConstellation
+
+    loadServiceClasses().forEach(serviceClass =>
+      serviceClass.register(
+        { camp, handleRequest, githubApiProvider, metricInstance },
+        {
+          handleInternalErrors: config.public.handleInternalErrors,
+          cacheHeaders: config.public.cacheHeaders,
+          profiling: config.public.profiling,
+          fetchLimitBytes: bytes(config.public.fetchLimit),
+          rasterUrl: config.public.rasterUrl,
+          private: config.private,
+        }
+      )
+    )
+  }
+
+  /**
+   * Start the HTTP server:
+   * Bootstrap Scoutcamp,
+   * Register handlers,
+   * Start listening for requests on this.baseUrl()
+   */
   async start() {
     const {
       bind: { port, address: hostname },
@@ -250,20 +308,30 @@ module.exports = class Server {
       key,
     }))
 
-    this.cleanupMonitor = sysMonitor.setRoutes({ rateLimit }, camp)
+    const { metricInstance } = this
+    this.cleanupMonitor = sysMonitor.setRoutes(
+      { rateLimit },
+      { server: camp, metricInstance }
+    )
 
-    const { githubConstellation, metrics } = this
+    const { githubConstellation } = this
     githubConstellation.initialize(camp)
-    if (metrics) {
-      metrics.initialize(camp)
+    if (metricInstance) {
+      metricInstance.initialize(camp)
     }
 
     const { apiProvider: githubApiProvider } = this.githubConstellation
     suggest.setRoutes(allowedOrigin, githubApiProvider, camp)
 
+    // https://github.com/badges/shields/issues/3273
+    camp.handle((req, res, next) => {
+      res.setHeader('Access-Control-Allow-Origin', '*')
+      next()
+    })
+
     this.registerErrorHandlers()
-    this.registerServices()
     this.registerRedirects()
+    this.registerServices()
 
     await new Promise(resolve => camp.on('listening', () => resolve()))
   }
@@ -279,6 +347,9 @@ module.exports = class Server {
     this.constructor.resetGlobalState()
   }
 
+  /**
+   * Stop the HTTP server and clean up helpers
+   */
   async stop() {
     if (this.camp) {
       await new Promise(resolve => this.camp.close(resolve))
@@ -295,8 +366,10 @@ module.exports = class Server {
       this.githubConstellation = undefined
     }
 
-    if (this.metrics) {
-      this.metrics.stop()
+    if (this.metricInstance) {
+      this.metricInstance.stop()
     }
   }
 }
+
+module.exports = Server

core/server/server.spec.js

@@ -1,15 +1,9 @@
 'use strict'
 
-const fs = require('fs')
-const path = require('path')
 const { expect } = require('chai')
-// https://github.com/nock/nock/issues/1523
-const got = require('got').extend({ retry: 0 })
-const isPng = require('is-png')
 const isSvg = require('is-svg')
-const sinon = require('sinon')
 const portfinder = require('portfinder')
-const svg2img = require('../../gh-badges/lib/svg-to-img')
+const got = require('../got-test-client')
 const { createTestServer } = require('./in-process-server-test-helpers')
 
 describe('The server', function() {
@@ -38,12 +32,36 @@ describe('The server', function() {
       .and.to.include('apple')
   })
 
-  it('should produce colorscheme PNG badges', async function() {
-    const { statusCode, body } = await got(`${baseUrl}:fruit-apple-green.png`, {
-      encoding: null,
+  it('should redirect colorscheme PNG badges as configured', async function() {
+    const { statusCode, headers } = await got(
+      `${baseUrl}:fruit-apple-green.png`,
+      {
+        followRedirect: false,
+      }
+    )
+    expect(statusCode).to.equal(301)
+    expect(headers.location).to.equal(
+      'http://raster.example.test/:fruit-apple-green.png'
+    )
+  })
+
+  it('should redirect modern PNG badges as configured', async function() {
+    const { statusCode, headers } = await got(`${baseUrl}npm/v/express.png`, {
+      followRedirect: false,
     })
+    expect(statusCode).to.equal(301)
+    expect(headers.location).to.equal(
+      'http://raster.example.test/npm/v/express.png'
+    )
+  })
+
+  it('should produce json badges', async function() {
+    const { statusCode, body, headers } = await got(
+      `${baseUrl}npm/v/express.json`
+    )
     expect(statusCode).to.equal(200)
-    expect(body).to.satisfy(isPng)
+    expect(headers['content-type']).to.equal('application/json')
+    expect(() => JSON.parse(body)).not.to.throw()
   })
 
   it('should preserve label case', async function() {
@@ -100,13 +118,16 @@ describe('The server', function() {
       .and.to.include('badge not found')
   })
 
-  it('should return the 404 html page for rando links', async function() {
+  it('should return the 404 badge page for rando links', async function() {
     const { statusCode, body } = await got(
       `${baseUrl}this/is/most/definitely/not/a/badge.js`,
       { throwHttpErrors: false }
     )
     expect(statusCode).to.equal(404)
-    expect(body).to.include('blood, toil, tears and sweat')
+    expect(body)
+      .to.satisfy(isSvg)
+      .and.to.include('404')
+      .and.to.include('badge not found')
   })
 
   it('should redirect the root as configured', async function() {
@@ -116,31 +137,24 @@ describe('The server', function() {
 
     expect(statusCode).to.equal(302)
     // This value is set in `config/test.yml`
-    expect(headers.location).to.equal('http://badge-server.example.com')
+    expect(headers.location).to.equal('http://frontend.example.test')
   })
 
-  context('with svg2img error', function() {
-    const expectedError = fs.readFileSync(
-      path.resolve(__dirname, 'error-pages', '500.html')
-    )
+  it('should return the 410 badge for obsolete formats', async function() {
+    const { statusCode, body } = await got(`${baseUrl}npm/v/express.jpg`, {
+      throwHttpErrors: false,
+    })
+    // TODO It would be nice if this were 404 or 410.
+    expect(statusCode).to.equal(200)
+    expect(body)
+      .to.satisfy(isSvg)
+      .and.to.include('410')
+      .and.to.include('jpg no longer available')
+  })
 
-    let toBufferStub
-    beforeEach(function() {
-      toBufferStub = sinon
-        .stub(svg2img._imageMagick.prototype, 'toBuffer')
-        .callsArgWith(1, Error('whoops'))
-    })
-    afterEach(function() {
-      toBufferStub.restore()
-    })
-
-    it('should emit the 500 message', async function() {
-      const { statusCode, body } = await got(
-        `${baseUrl}:some_new-badge-green.png`
-      )
-      // This emits status code 200, though 500 would be preferable.
-      expect(statusCode).to.equal(200)
-      expect(body).to.include(expectedError)
-    })
+  it('should return cors header for the request', async function() {
+    const { statusCode, headers } = await got(`${baseUrl}npm/v/express.svg`)
+    expect(statusCode).to.equal(200)
+    expect(headers['access-control-allow-origin']).to.equal('*')
   })
 })

core/service-test-runner/cli.js

@@ -15,6 +15,11 @@
 // Run tests on a given instance:
 //   SKIP_INTERCEPTED=TRUE TESTED_SERVER_URL=https://test.shields.io npm run test:services --
 //
+// Run tests with given number of retries and backoff (in milliseconds):
+//   RETRY_COUNT=3 RETRY_BACKOFF=100 npm run test:services --
+// Retry option documentation:
+// https://github.com/IcedFrisby/IcedFrisby/blob/master/API.md#retrycount-backoff
+//
 // Service tests are run in CI in two cases: scheduled builds and pull
 // requests. The scheduled builds run _all_ the service tests, whereas the
 // pull requests run service tests designated in the PR title. In this way,
@@ -59,6 +64,9 @@ const Runner = require('./runner')
 
 require('../unhandled-rejection.spec')
 
+const retry = {}
+retry.count = parseInt(process.env.RETRY_COUNT) || 0
+retry.backoff = parseInt(process.env.RETRY_BACKOFF) || 0
 let baseUrl, server
 if (process.env.TESTED_SERVER_URL) {
   baseUrl = process.env.TESTED_SERVER_URL
@@ -77,7 +85,7 @@ if (process.env.TESTED_SERVER_URL) {
 }
 
 const skipIntercepted = envFlag(process.env.SKIP_INTERCEPTED, false)
-const runner = new Runner({ baseUrl, skipIntercepted })
+const runner = new Runner({ baseUrl, skipIntercepted, retry })
 runner.prepare()
 
 // The server's request cache causes side effects between tests.

core/service-test-runner/create-service-tester.js

@@ -1,16 +1,24 @@
 'use strict'
+/**
+ * @module
+ */
 
 const caller = require('caller')
 const BaseService = require('../base-service/base')
 const ServiceTester = require('./service-tester')
 
-// Automatically create a ServiceTester.
-//
-// When run from e.g. `gem-rank.tester.js`, this will create a tester that
-// attaches to the service found in `gem-rank.service.js`.
-//
-// This can't be used for `.service.js` files which export more than one
-// service.
+/**
+ * Automatically create a ServiceTester.
+ *
+ * When run from e.g. `gem-rank.tester.js`, this will create a tester that
+ * attaches to the service found in `gem-rank.service.js`.
+ *
+ * This can't be used for `.service.js` files which export more than one
+ * service.
+ *
+ * @returns {module:core/service-test-runner/service-tester~ServiceTester}
+ *    ServiceTester instance
+ */
 function createServiceTester() {
   const servicePath = caller().replace('.tester.js', '.service.js')
   const ServiceClass = require(servicePath)

core/service-test-runner/icedfrisby-shields.js

@@ -1,12 +1,20 @@
 'use strict'
+/**
+ * @module
+ */
 
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const { expect } = require('chai')
 
-// based on https://github.com/paulmelnikow/icedfrisby-nock/blob/master/icedfrisby-nock.js
-// can be used to wrap the original "icedfrisby-nock" with additional functionality:
-// - check if a request was intercepted
-// - set expectations on the badge JSON response
+/**
+ * Factory which wraps an "icedfrisby-nock" with some additional functionality:
+ * - check if a request was intercepted
+ * - set expectations on the badge JSON response
+ *
+ * @param {Function} superclass class to extend
+ * @see https://github.com/paulmelnikow/icedfrisby-nock/blob/master/icedfrisby-nock.js
+ * @returns {Function} wrapped class
+ */
 const factory = superclass =>
   class IcedFrisbyNock extends superclass {
     constructor(message) {
@@ -44,12 +52,23 @@ const factory = superclass =>
     }
 
     static _expectField(json, name, expected) {
-      if (typeof expected === 'string') {
+      if (typeof expected === 'undefined') return
+      if (typeof expected === 'string' || typeof expected === 'number') {
         expect(json[name], `${name} mismatch`).to.equal(expected)
       } else if (Array.isArray(expected)) {
         expect(json[name], `${name} mismatch`).to.deep.equal(expected)
-      } else if (typeof expected === 'object') {
+      } else if (Joi.isSchema(expected)) {
         Joi.attempt(json[name], expected, `${name} mismatch:`)
+      } else if (expected instanceof RegExp) {
+        Joi.attempt(
+          json[name],
+          Joi.string().regex(expected),
+          `${name} mismatch:`
+        )
+      } else {
+        throw new Error(
+          "'expected' must be a string, a number, a regex, an array or a Joi schema"
+        )
       }
     }
   }

core/service-test-runner/infer-pull-request.js

@@ -1,4 +1,7 @@
 'use strict'
+/**
+ * @module
+ */
 
 const { URL, format: urlFormat } = require('url')
 
@@ -60,6 +63,14 @@ function _inferPullRequestFromCircleEnv(env) {
   return parseGithubPullRequestUrl(env.CI_PULL_REQUEST)
 }
 
+/**
+ * When called inside a CI build, infer the details
+ * of a pull request from the environment variables.
+ *
+ * @param {object} [env=process.env] Environment variables
+ * @returns {module:core/service-test-runner/infer-pull-request~PullRequest}
+ *    Pull Request
+ */
 function inferPullRequest(env = process.env) {
   if (env.TRAVIS) {
     return _inferPullRequestFromTravisEnv(env)
@@ -76,6 +87,17 @@ function inferPullRequest(env = process.env) {
   }
 }
 
+/**
+ * Pull Request
+ *
+ * @typedef PullRequest
+ * @property {string} pr.baseUrl (returned for travis CI only)
+ * @property {string} owner
+ * @property {string} repo
+ * @property {string} pullRequest PR/issue number
+ * @property {string} slug owner/repo/#pullRequest
+ */
+
 module.exports = {
   parseGithubPullRequestUrl,
   parseGithubRepoSlug,

core/service-test-runner/runner.js

@@ -1,4 +1,7 @@
 'use strict'
+/**
+ * @module
+ */
 
 const { loadTesters } = require('../base-service/loader')
 
@@ -6,9 +9,10 @@ const { loadTesters } = require('../base-service/loader')
  * Load a collection of ServiceTester objects and register them with Mocha.
  */
 class Runner {
-  constructor({ baseUrl, skipIntercepted }) {
+  constructor({ baseUrl, skipIntercepted, retry }) {
     this.baseUrl = baseUrl
     this.skipIntercepted = skipIntercepted
+    this.retry = retry
   }
 
   /**
@@ -36,7 +40,7 @@ class Runner {
   /**
    * Limit the test run to the specified services.
    *
-   * @param services An array of service id prefixes to run
+   * @param {string[]} services An array of service id prefixes to run
    */
   only(services) {
     const normalizedServices = new Set(services.map(v => v.toLowerCase()))
@@ -64,8 +68,8 @@ class Runner {
    * Register the tests with Mocha.
    */
   toss() {
-    const { testers, baseUrl, skipIntercepted } = this
-    testers.forEach(tester => tester.toss({ baseUrl, skipIntercepted }))
+    const { testers, baseUrl, skipIntercepted, retry } = this
+    testers.forEach(tester => tester.toss({ baseUrl, skipIntercepted, retry }))
   }
 }
 module.exports = Runner

core/service-test-runner/service-tester.js

@@ -1,4 +1,7 @@
 'use strict'
+/**
+ * @module
+ */
 
 const emojic = require('emojic')
 const trace = require('../base-service/trace')
@@ -10,13 +13,21 @@ const frisby = require('./icedfrisby-shields')(
 /**
  * Encapsulate a suite of tests. Create new tests using create() and register
  * them with Mocha using toss().
+ *
+ * @see https://github.com/badges/shields/blob/master/doc/service-tests.md
  */
 class ServiceTester {
   /**
-   * @param attrs { id, title, pathPrefix } The `id` is used to specify which
-   *   tests to run from the CLI or pull requests. The `title` prints in the
-   *   Mocha output. The `path` is the path prefix which is automatically
-   *   prepended to each tested URI. The default is `/${attrs.id}`.
+   * Service Tester Constructor
+   *
+   * @param {object} attrs Refer to individual attrs
+   * @param {string} attrs.id
+   *    Specifies which tests to run from the CLI or pull requests
+   * @param {string} attrs.title
+   *    Prints in the Mocha output
+   * @param {string} attrs.path
+   *    Prefix which is automatically prepended to each tested URI.
+   *    The default is `/${attrs.id}`.
    */
   constructor({ id, title, pathPrefix }) {
     if (pathPrefix === undefined) {
@@ -31,6 +42,14 @@ class ServiceTester {
     })
   }
 
+  /**
+   * Construct a ServiceTester instance for a single service class
+   *
+   * @param {Function} ServiceClass
+   *    A class that extends base-service/base.BaseService
+   * @returns {module:core/service-test-runner/service-tester~ServiceTester}
+   *    ServiceTester for ServiceClass
+   */
   static forServiceClass(ServiceClass) {
     const id = ServiceClass.name
     const pathPrefix = ServiceClass.route.base
@@ -51,11 +70,13 @@ class ServiceTester {
 
   /**
    * Create a new test. The hard work is delegated to IcedFrisby.
-   * https://github.com/MarkHerhold/IcedFrisby/#show-me-some-code
+   * {@link https://github.com/MarkHerhold/IcedFrisby/#show-me-some-code}
    *
    * Note: The caller should not invoke toss() on the Frisby chain, as it's
    * invoked automatically by the tester.
-   * @param msg The name of the test
+   *
+   * @param {string} msg The name of the test
+   * @returns {module:icedfrisby~IcedFrisby} IcedFrisby instance
    */
   create(msg) {
     const spec = frisby
@@ -90,8 +111,15 @@ class ServiceTester {
 
   /**
    * Register the tests with Mocha.
+   *
+   * @param {object} attrs Refer to individual attrs
+   * @param {string} attrs.baseUrl base URL for test server
+   * @param {boolean} attrs.skipIntercepted skip tests which intercept requests
+   * @param {object} attrs.retry retry configuration
+   * @param {number} attrs.retry.count number of times to retry test
+   * @param {number} attrs.retry.backoff number of milliseconds to add to the wait between each retry
    */
-  toss({ baseUrl, skipIntercepted }) {
+  toss({ baseUrl, skipIntercepted, retry }) {
     const { specs, pathPrefix } = this
     const testerBaseUrl = `${baseUrl}${pathPrefix}`
 
@@ -99,12 +127,17 @@ class ServiceTester {
     // eslint-disable-next-line mocha/prefer-arrow-callback
     fn(this.title, function() {
       specs.forEach(spec => {
+        spec._message = `[${spec.hasIntercept ? 'mocked' : 'live'}] ${
+          spec._message
+        }`
         if (!skipIntercepted || !spec.intercepted) {
           spec.baseUri(testerBaseUrl)
+          spec.retry(retry.count, retry.backoff)
           spec.toss()
         }
       })
     })
   }
 }
+
 module.exports = ServiceTester

core/service-test-runner/services-for-title.js

@@ -1,8 +1,20 @@
 'use strict'
+/**
+ * @module
+ */
 
 const difference = require('lodash.difference')
 
-module.exports = function servicesForTitle(title) {
+/**
+ * Given a pull request title like
+ * '[Travis Sonar] Support user token authentication'
+ * extract the list of service names in square brackets
+ * as an array of strings.
+ *
+ * @param {string} title Pull Request title
+ * @returns {string[]} Array of service names
+ */
+function servicesForTitle(title) {
   const bracketed = /\[([^\]]+)\]/g
 
   const preNormalized = title.toLowerCase()
@@ -18,3 +30,5 @@ module.exports = function servicesForTitle(title) {
   const ignored = ['wip', 'rfc', 'security']
   return difference(services, ignored)
 }
+
+module.exports = servicesForTitle

core/token-pooling/redis-token-persistence.integration.js

@@ -1,8 +1,7 @@
 'use strict'
 
-const { promisify } = require('util')
 const RedisServer = require('redis-server')
-const redis = require('redis')
+const Redis = require('ioredis')
 const { expect } = require('chai')
 const RedisTokenPersistence = require('./redis-token-persistence')
 
@@ -18,17 +17,15 @@ describe('Redis token persistence', function() {
 
   const key = 'tokenPersistenceIntegrationTest'
 
-  let client
+  let redis
   beforeEach(async function() {
-    client = redis.createClient()
-    const del = promisify(client.del).bind(client)
-    await del(key)
+    redis = new Redis()
+    await redis.del(key)
   })
   afterEach(async function() {
-    if (client) {
-      const quit = promisify(client.quit).bind(client)
-      await quit()
-      client = undefined
+    if (redis) {
+      await redis.quit()
+      redis = undefined
     }
   })
 
@@ -61,18 +58,12 @@ describe('Redis token persistence', function() {
     const initialTokens = ['a', 'b', 'c'].map(char => char.repeat(40))
 
     beforeEach(async function() {
-      const rpush = promisify(client.rpush).bind(client)
-      await rpush(key, initialTokens)
-    })
-
-    let lrange
-    beforeEach(function() {
-      lrange = promisify(client.lrange).bind(client)
+      await redis.sadd(key, initialTokens)
     })
 
     it('loads the contents', async function() {
       const tokens = await persistence.initialize()
-      expect(tokens).to.deep.equal(initialTokens)
+      expect(tokens.sort()).to.deep.equal(initialTokens)
     })
 
     context('when tokens are added', function() {
@@ -84,8 +75,8 @@ describe('Redis token persistence', function() {
         await persistence.initialize()
         await persistence.noteTokenAdded(newToken)
 
-        const savedTokens = await lrange(key, 0, -1)
-        expect(savedTokens).to.deep.equal(expected)
+        const savedTokens = await redis.smembers(key)
+        expect(savedTokens.sort()).to.deep.equal(expected)
       })
     })
 
@@ -98,8 +89,8 @@ describe('Redis token persistence', function() {
 
         await persistence.noteTokenRemoved(toRemove)
 
-        const savedTokens = await lrange(key, 0, -1)
-        expect(savedTokens).to.deep.equal(expected)
+        const savedTokens = await redis.smembers(key)
+        expect(savedTokens.sort()).to.deep.equal(expected)
       })
     })
   })

core/token-pooling/redis-token-persistence.js

@@ -1,11 +1,11 @@
 'use strict'
 
-const { promisify } = require('util')
-const redis = require('redis')
+const { URL } = require('url')
+const Redis = require('ioredis')
 const log = require('../server/log')
 const TokenPersistence = require('./token-persistence')
 
-class RedisTokenPersistence extends TokenPersistence {
+module.exports = class RedisTokenPersistence extends TokenPersistence {
   constructor({ url, key }) {
     super()
     this.url = url
@@ -13,31 +13,31 @@ class RedisTokenPersistence extends TokenPersistence {
   }
 
   async initialize() {
-    this.client = redis.createClient(this.url)
-    this.client.on('error', e => {
+    const options =
+      this.url && this.url.startsWith('rediss:')
+        ? {
+            //  https://www.compose.com/articles/ssl-connections-arrive-for-redis-on-compose/
+            tls: { servername: new URL(this.url).hostname },
+          }
+        : undefined
+    this.redis = new Redis(this.url, options)
+    this.redis.on('error', e => {
       log.error(e)
     })
 
-    const lrange = promisify(this.client.lrange).bind(this.client)
-
-    const tokens = await lrange(this.key, 0, -1)
+    const tokens = await this.redis.smembers(this.key)
     return tokens
   }
 
   async stop() {
-    const quit = promisify(this.client.quit).bind(this.client)
-    await quit()
+    await this.redis.quit()
   }
 
   async onTokenAdded(token) {
-    const rpush = promisify(this.client.rpush).bind(this.client)
-    await rpush(this.key, token)
+    await this.redis.sadd(this.key, token)
   }
 
   async onTokenRemoved(token) {
-    const lrem = promisify(this.client.lrem).bind(this.client)
-    await lrem(this.key, 0, token)
+    await this.redis.srem(this.key, token)
   }
 }
-
-module.exports = RedisTokenPersistence

core/token-pooling/token-pool.js

@@ -1,9 +1,17 @@
 'use strict'
+/**
+ * @module
+ */
 
 const crypto = require('crypto')
 const PriorityQueue = require('priorityqueuejs')
 
-// Compute a one-way hash of the input string.
+/**
+ * Compute a one-way hash of the input string.
+ *
+ * @param {string} id token
+ * @returns {string} hash
+ */
 function sanitizeToken(id) {
   return crypto
     .createHash('sha256')
@@ -15,11 +23,23 @@ function getUtcEpochSeconds() {
   return (Date.now() / 1000) >>> 0
 }
 
-// Encapsulate a rate-limited token, with a user-provided ID and user-provided data.
-//
-// Each token has a notion of the number of uses remaining until exhausted,
-// and the next reset time, when it can be used again even if it's exhausted.
+/**
+ * Encapsulate a rate-limited token, with a user-provided ID and user-provided data.
+ *
+ * Each token has a notion of the number of uses remaining until exhausted,
+ * and the next reset time, when it can be used again even if it's exhausted.
+ */
 class Token {
+  /**
+   * Token Constructor
+   *
+   * @param {string} id token string
+   * @param {*} data reserved for future use
+   * @param {number} usesRemaining
+   *    Number of uses remaining until the token is exhausted
+   * @param {number} nextReset
+   *    Time when the token can be used again even if it's exhausted (unix timestamp)
+   */
   constructor(id, data, usesRemaining, nextReset) {
     // Use underscores to avoid conflict with property accessors.
     Object.assign(this, {
@@ -59,7 +79,14 @@ class Token {
     return this.usesRemaining <= 0 && !this.hasReset
   }
 
-  // Update the uses remaining and next reset time for a token.
+  /**
+   * Update the uses remaining and next reset time for a token.
+   *
+   * @param {number} usesRemaining
+   *    Number of uses remaining until the token is exhausted
+   * @param {number} nextReset
+   *    Time when the token can be used again even if it's exhausted (unix timestamp)
+   */
   update(usesRemaining, nextReset) {
     if (!Number.isInteger(usesRemaining)) {
       throw Error('usesRemaining must be an integer')
@@ -89,18 +116,24 @@ class Token {
     }
   }
 
-  // Indicate that the token should no longer be used.
+  /**
+   * Indicate that the token should no longer be used.
+   */
   invalidate() {
     this._isValid = false
   }
 
-  // Freeze the uses remaining and next reset values. Helpful for keeping
-  // stable ordering for a valid priority queue.
+  /**
+   * Freeze the uses remaining and next reset values. Helpful for keeping
+   * stable ordering for a valid priority queue.
+   */
   freeze() {
     this._isFrozen = true
   }
 
-  // Unfreeze the uses remaining and next reset values.
+  /**
+   * Unfreeze the uses remaining and next reset values.
+   */
   unfreeze() {
     this._isFrozen = false
   }
@@ -126,14 +159,21 @@ class Token {
 // Large sentinel value which means "never reset".
 Token.nextResetNever = Number.MAX_SAFE_INTEGER
 
-// Encapsulate a collection of rate-limited tokens and choose the next
-// available token when one is needed.
-//
-// Designed for the Github API, though may be also useful with other rate-
-// limited APIs.
+/**
+ * Encapsulate a collection of rate-limited tokens and choose the next
+ * available token when one is needed.
+ *
+ * Designed for the Github API, though may be also useful with other rate-
+ * limited APIs.
+ */
 class TokenPool {
-  // batchSize: The maximum number of times we use each token before moving
-  //   on to the next one.
+  /**
+   * TokenPool Constructor
+   *
+   * @param {number} batchSize
+   *    The maximum number of times we use each token before moving
+   *    on to the next one.
+   */
   constructor({ batchSize = 1 } = {}) {
     this.batchSize = batchSize
 
@@ -147,16 +187,29 @@ class TokenPool {
     this.priorityQueue = new PriorityQueue(this.constructor.compareTokens)
   }
 
-  // Use the token whose current rate allotment is expiring soonest.
+  /**
+   * compareTokens
+   *
+   * @param {module:core/token-pooling/token-pool~Token} first first token to compare
+   * @param {module:core/token-pooling/token-pool~Token} second second token to compare
+   * @returns {module:core/token-pooling/token-pool~Token} The token whose current rate allotment is expiring soonest.
+   */
   static compareTokens(first, second) {
     return second.nextReset - first.nextReset
   }
 
-  // Add a token with user-provided ID and data.
-  //
-  // The ID can be a primitive value or an object reference, and is used (with
-  // `Set`) for deduplication. If a token already exists with a given id, it
-  // will be ignored.
+  /**
+   * Add a token with user-provided ID and data.
+   *
+   * @param {string} id token string
+   * @param {*} data reserved for future use
+   * @param {number} usesRemaining
+   *    Number of uses remaining until the token is exhausted
+   * @param {number} nextReset
+   *    Time when the token can be used again even if it's exhausted (unix timestamp)
+   *
+   * @returns {boolean} Was the token added to the pool?
+   */
   add(id, data, usesRemaining, nextReset) {
     if (this.tokenIds.has(id)) {
       return false
@@ -210,31 +263,35 @@ class TokenPool {
     throw Error('Token pool is exhausted')
   }
 
-  // Obtain the next available token, returning `null` if no tokens are
-  // available.
-  //
-  // Tokens are initially pulled from a FIFO queue. The first token is used
-  // for a batch of requests, then returned to the queue to give those
-  // requests the opportunity to complete. The next token is used for the next
-  // batch of requests.
-  //
-  // This strategy allows a token to be used for concurrent requests, not just
-  // sequential request, and simplifies token recovery after errored and timed
-  // out requests.
-  //
-  // By the time the original token re-emerges, its requests should have long
-  // since completed. Even if a couple them are still running, they can
-  // reasonably be ignored. The uses remaining won't be 100% correct, but
-  // that's fine, because Shields uses only 75%
-  //
-  // The process continues until an exhausted token is pulled from the FIFO
-  // queue. At that time it's placed in the priority queue based on its
-  // scheduled reset time. To ensure the priority queue works as intended,
-  // the scheduled reset time is frozen then.
-  //
-  // After obtaining a token using `next()`, invoke `update()` on it to set a
-  // new use-remaining count and next-reset time. Invoke `invalidate()` to
-  // indicate it should not be reused.
+  /**
+   * Obtain the next available token, returning `null` if no tokens are
+   * available.
+   *
+   * Tokens are initially pulled from a FIFO queue. The first token is used
+   * for a batch of requests, then returned to the queue to give those
+   * requests the opportunity to complete. The next token is used for the next
+   * batch of requests.
+   *
+   * This strategy allows a token to be used for concurrent requests, not just
+   * sequential request, and simplifies token recovery after errored and timed
+   * out requests.
+   *
+   * By the time the original token re-emerges, its requests should have long
+   * since completed. Even if a couple them are still running, they can
+   * reasonably be ignored. The uses remaining won't be 100% correct, but
+   * that's fine, because Shields uses only 75%
+   *
+   * The process continues until an exhausted token is pulled from the FIFO
+   * queue. At that time it's placed in the priority queue based on its
+   * scheduled reset time. To ensure the priority queue works as intended,
+   * the scheduled reset time is frozen then.
+   *
+   * After obtaining a token using `next()`, invoke `update()` on it to set a
+   * new use-remaining count and next-reset time. Invoke `invalidate()` to
+   * indicate it should not be reused.
+   *
+   * @returns {module:core/token-pooling/token-pool~Token} token
+   */
   next() {
     let token = this.currentBatch.token
     const remaining = this.currentBatch.remaining
@@ -255,7 +312,11 @@ class TokenPool {
     return token
   }
 
-  // Iterate over all valid tokens.
+  /**
+   * Iterate over all valid tokens.
+   *
+   * @param {Function} callback function to execute on each valid token
+   */
   forEach(callback) {
     function visit(item) {
       if (item.isValid) {

cypress/integration/main-page.spec.js

@@ -4,6 +4,15 @@ describe('Main page', function() {
   const backendUrl = Cypress.env('backend_url')
   const SEARCH_INPUT = 'input[placeholder="search / project URL"]'
 
+  function expectBadgeExample(title, previewUrl, pattern) {
+    cy.contains('tr', `${title}:`)
+      .find('code')
+      .should('have.text', pattern)
+    cy.contains('tr', `${title}:`)
+      .find('img')
+      .should('have.attr', 'src', previewUrl)
+  }
+
   it('Search for badges', function() {
     cy.visit('/')
 
@@ -12,20 +21,28 @@ describe('Main page', function() {
     cy.contains('PyPI - License')
   })
 
+  it('Shows badge from category', function() {
+    cy.visit('/category/chat')
+
+    expectBadgeExample(
+      'Discourse status',
+      'http://localhost:8080/badge/discourse-online-brightgreen',
+      '/discourse/status?server=https%3A%2F%2Fmeta.discourse.org'
+    )
+  })
+
   it('Suggest badges', function() {
-    const badgeUrl = `${backendUrl}/github/issues/badges/shields.svg`
+    const badgeUrl = `${backendUrl}/github/issues/badges/shields`
     cy.visit('/')
 
     cy.get(SEARCH_INPUT).type('https://github.com/badges/shields')
     cy.contains('Suggest badges').click()
 
-    cy.contains('GitHub issues')
-    cy.get(`img[src='${badgeUrl}']`)
-    cy.contains(badgeUrl)
+    expectBadgeExample('GitHub issues', badgeUrl, badgeUrl)
   })
 
   it('Customization form is filled with suggested badge details', function() {
-    const badgeUrl = `${backendUrl}/github/issues/badges/shields.svg`
+    const badgeUrl = `${backendUrl}/github/issues/badges/shields`
     cy.visit('/')
     cy.get(SEARCH_INPUT).type('https://github.com/badges/shields')
     cy.contains('Suggest badges').click()
@@ -37,7 +54,7 @@ describe('Main page', function() {
   })
 
   it('Customizate suggested badge', function() {
-    const badgeUrl = `${backendUrl}/github/issues/badges/shields.svg`
+    const badgeUrl = `${backendUrl}/github/issues/badges/shields`
     cy.visit('/')
     cy.get(SEARCH_INPUT).type('https://github.com/badges/shields')
     cy.contains('Suggest badges').click()
@@ -45,8 +62,6 @@ describe('Main page', function() {
 
     cy.get('table input[name="color"]').type('orange')
 
-    cy.get(
-      `img[src='${backendUrl}/github/issues/badges/shields.svg?color=orange']`
-    )
+    cy.get(`img[src='${backendUrl}/github/issues/badges/shields?color=orange']`)
   })
 })

dangerfile.js

@@ -106,19 +106,26 @@ if (allFiles.length > 100) {
   warn("Lots 'o changes. Skipping diff-based checks.")
 } else {
   allFiles.forEach(file => {
+    if (file === 'dangerfile.js') {
+      return
+    }
+
     // eslint-disable-next-line promise/prefer-await-to-then
     danger.git.diffForFile(file).then(({ diff }) => {
-      if (/serverSecrets/.test(diff) && !secretsDocs.modified) {
+      if (
+        (diff.includes('authHelper') || diff.includes('serverSecrets')) &&
+        !secretsDocs.modified
+      ) {
         warn(
           [
-            `:books: Remember to ensure any changes to \`serverSecrets\` `,
+            `:books: Remember to ensure any changes to \`config.private\` `,
             `in \`${file}\` are reflected in the [server secrets documentation]`,
             '(https://github.com/badges/shields/blob/master/doc/server-secrets.md)',
           ].join('')
         )
       }
 
-      if (/\+.*assert[(.]/.test(diff)) {
+      if (diff.includes('.assert(')) {
         warn(
           [
             `Found 'assert' statement added in \`${file}\`. <br>`,
@@ -127,6 +134,15 @@ if (allFiles.length > 100) {
           ].join('')
         )
       }
+
+      if (diff.includes("require('joi')")) {
+        fail(
+          [
+            `Found import of 'joi' in \`${file}\`. <br>`,
+            "Joi must be imported as '@hapi/joi'.",
+          ].join('')
+        )
+      }
     })
   })
 }

doc/TUTORIAL.md

@@ -1,16 +1,17 @@
 # Tutorial on how to add a badge for a service
 
 This tutorial should help you add a service to shields.io in form of a badge.
-You will need to learn to use JavaScript, Git and GitHub.
+You will need to learn to use JavaScript, Git and GitHub, however, this document
+will guide you through that journey if you are a beginner.
 Please [improve the tutorial](https://github.com/badges/shields/edit/master/doc/TUTORIAL.md) while you read it.
 
 ## (1) Reading
 
-You should read [CONTRIBUTING.md](../CONTRIBUTING.md)
-
-You can also read previous
-[merged pull-requests with the 'service-badge' label](https://github.com/badges/shields/pulls?utf8=%E2%9C%93&q=is%3Apr+label%3Aservice-badge+is%3Amerged)
-to see how other people implemented their badges.
+- [Contributing Guidance](../CONTRIBUTING.md)
+- [Documentation](https://contributing.shields.io/index.html) for the Shields Core API
+- You can also read previous
+  [merged pull-requests with the 'service-badge' label](https://github.com/badges/shields/pulls?utf8=%E2%9C%93&q=is%3Apr+label%3Aservice-badge+is%3Amerged)
+  to see how other people implemented their badges.
 
 ## (2) Setup
 
@@ -41,14 +42,9 @@ install node and npm: https://nodejs.org/en/download/
 
 In case you get the _"getaddrinfo ENOTFOUND localhost"_ error, visit [http://127.0.0.1:3000/](http://127.0.0.1:3000) instead or take a look at [this issue](https://github.com/angular/angular-cli/issues/2227#issuecomment-358036526).
 
-You may also want to install
-[ImageMagick](https://www.imagemagick.org/script/download.php).
-This is an optional dependency needed for generating badges in raster format,
-but you can get a dev copy running without it.
-
 ## (3) Open an Issue
 
-Before you want to implement your service, you may want to [open an issue](https://github.com/badges/shields/issues/new?template=2_Badge_request.md) and describe what you have in mind:
+Before you want to implement your service, you may want to [open an issue](https://github.com/badges/shields/issues/new?template=3_Badge_request.md) and describe what you have in mind:
 
 - What is the badge for?
 - Which API do you want to use?
@@ -69,7 +65,7 @@ Each service has a directory for its files:
   This might be the case when you add a badge for an API which is already used
   by other badges.
 
-  Imagine a service that lives at https://img.shields.io/example/some-param-here.svg.
+  Imagine a service that lives at https://img.shields.io/example/some-param-here.
 
   - For services with a single badge, the badge code will generally be stored in
     `/services/example/example.service.js`.
@@ -94,14 +90,20 @@ Each service has a directory for its files:
 All service badge classes inherit from [BaseService] or another class which extends it.
 Other classes implement useful behavior on top of [BaseService].
 
-- [BaseJsonService](https://github.com/badges/shields/blob/master/core/base-service/base-json.js)
+- [BaseJsonService](https://contributing.shields.io/module-core_base-service_base-json-basejsonservice)
   implements methods for performing requests to a JSON API and schema validation.
-- [BaseXmlService](https://github.com/badges/shields/blob/master/core/base-service/base-xml.js)
+- [BaseXmlService](https://contributing.shields.io/module-core_base-service_base-xml-basexmlservice)
   implements methods for performing requests to an XML API and schema validation.
+- [BaseYamlService](https://contributing.shields.io/module-core_base-service_base-yaml-baseyamlservice)
+  implements methods for performing requests to a YAML API and schema validation.
+- [BaseSvgScrapingService](https://contributing.shields.io/module-core_base-service_base-svg-scraping-basesvgscrapingservice)
+  implements methods for retrieving information from existing third-party badges.
+- [BaseGraphqlService](https://contributing.shields.io/module-core_base-service_base-graphql-basegraphqlservice)
+  implements methods for performing requests to a GraphQL API and schema validation.
 - If you are contributing to a _service family_, you may define a common super
   class for the badges or one may already exist.
 
-[baseservice]: https://github.com/badges/shields/blob/master/core/base-service/base.js
+[baseservice]: https://contributing.shields.io/module-core_base-service_base-baseservice
 
 As a first step we will look at the code for an example which generates a badge without contacting an API.
 
@@ -144,17 +146,12 @@ Description of the code:
 3. Our module must export a class which extends `BaseService`.
 4. Returns the name of the category to sort this badge into (eg. "build"). Used to sort the examples on the main [shields.io](https://shields.io) website. [Here](https://github.com/badges/shields/blob/master/services/categories.js) is the list of the valid categories. See [section 4.4](#44-adding-an-example-to-the-front-page) for more details on examples.
 5. `route()` declares the URL path at which the service operates. It also maps components of the URL path to handler parameters.
-   - `base` defines the first part of the URL that doesn't change, e.g. `/example/`.
-   - `pattern` defines the variable part of the route, everything that comes after `/example/`. It can include any
-     number of named parameters. These are converted into
-     regular expressions by [`path-to-regexp`][path-to-regexp]. the list of the valid categories can be seen
-6. `route()` declares the URL path at which the service operates. It also maps components of the URL path to handler parameters.
    - `base` defines the first part of the URL that doesn't change, e.g. `/example/`.
    - `pattern` defines the variable part of the route, everything that comes after `/example/`. It can include any
      number of named parameters. These are converted into
      regular expressions by [`path-to-regexp`][path-to-regexp].
-7. Because a service instance won't be created until it's time to handle a request, the route and other metadata must be obtained by examining the classes themselves. [That's why they're marked `static`.][static]
-8. All badges must implement the `async handle()` function that receives parameters to render the badge. Parameters of `handle()` will match the name defined in `route()` Because we're capturing a single variable called `text` our function signature is `async handle({ text })`. `async` is needed to let JavaScript do other things while we are waiting for result from external API. Although in this simple case, we don't make any external calls. Our `handle()` function should return an object with 3 properties:
+     Because a service instance won't be created until it's time to handle a request, the route and other metadata must be obtained by examining the classes themselves. [That's why they're marked `static`.][static]
+6. All badges must implement the `async handle()` function that receives parameters to render the badge. Parameters of `handle()` will match the name defined in `route()` Because we're capturing a single variable called `text` our function signature is `async handle({ text })`. `async` is needed to let JavaScript do other things while we are waiting for result from external API. Although in this simple case, we don't make any external calls. Our `handle()` function should return an object with 3 properties:
    - `label`: the text on the left side of the badge
    - `message`: the text on the right side of the badge - here we are passing through the parameter we captured in the route regex
    - `color`: the background color of the right side of the badge
@@ -166,8 +163,8 @@ To try out this example badge:
 1. Copy and paste this code into a new file in `/services/example/example.service.js`
 2. The server should restart on its own. (If it doesn't for some reason, quit
    the running server with `Control+C`, then start it again with `npm start`.)
-3. Visit the badge at <http://localhost:8080/example/foo.svg>.
-   It should look like this: ![](https://img.shields.io/badge/example-foo-blue.svg)
+3. Visit the badge at <http://localhost:8080/example/foo>.
+   It should look like this: ![](https://img.shields.io/badge/example-foo-blue)
 
 [path-to-regexp]: https://github.com/pillarjs/path-to-regexp#parameters
 [static]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/static
@@ -188,7 +185,7 @@ const { renderVersionBadge } = require('..//version')
 const { BaseJsonService } = require('..')
 
 // (4)
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const schema = Joi.object({
   version: Joi.string().required(),
 }).required()
@@ -270,9 +267,9 @@ Description of the code:
 
 11. The `static render()` method is responsible for formatting the data for display. `render()` is a pure function so we can make it a `static` method. By convention we declare functions which don't reference `this` as `static`. We could explicitly return an object here, as we did in the previous example. In this case, we will hand the version string off to `renderVersionBadge()` which will format it consistently and set an appropriate color. Because `renderVersionBadge()` doesn't return a `label` key, the default label we defined in `defaultBadgeData()` will be used when we generate the badge.
 
-This code allows us to call this URL <https://img.shields.io/gem/v/formatador.svg> to generate this badge: ![](https://img.shields.io/gem/v/formatador.svg)
+This code allows us to call this URL <https://img.shields.io/gem/v/formatador> to generate this badge: ![](https://img.shields.io/gem/v/formatador)
 
-It is also worth considering the code we _haven't_ written here. Note that our example doesn't contain any explicit error handling code, but our badge handles errors gracefully. For example, if we call https://img.shields.io/gem/v/does-not-exist.svg we render a 'not found' badge ![](https://img.shields.io/gem/v/does-not-exist.svg) because https://rubygems.org/api/v1/gems/this-package-does-not-exist.json returns a `404 Not Found` status code. When dealing with well-behaved APIs, some of our error handling will be handled implicitly in `BaseJsonService`.
+It is also worth considering the code we _haven't_ written here. Note that our example doesn't contain any explicit error handling code, but our badge handles errors gracefully. For example, if we call https://img.shields.io/gem/v/does-not-exist we render a 'not found' badge ![](https://img.shields.io/gem/v/does-not-exist) because https://rubygems.org/api/v1/gems/this-package-does-not-exist.json returns a `404 Not Found` status code. When dealing with well-behaved APIs, some of our error handling will be handled implicitly in `BaseJsonService`.
 
 Specifically `BaseJsonService` will handle the following errors for us:
 
@@ -282,8 +279,8 @@ Specifically `BaseJsonService` will handle the following errors for us:
 - API returns a response which doesn't validate against our schema
 
 Sometimes it may be necessary to manually throw an exception to deal with a
-non-standard error condition. If so, there are several standard exceptions that can be used. These exceptions are defined in
-[errors.js](https://github.com/badges/shields/blob/master/services/errors.js)
+non-standard error condition. If so, there are several standard exceptions that can be used. The errors are documented at
+[errors](https://contributing.shields.io/module-core_base-service_errors.html)
 and can be imported via the import shortcut and then thrown:
 
 ```js
@@ -327,7 +324,7 @@ module.exports = class GemVersion extends BaseJsonService {
    - `namedParams`: Provide a valid example of params we can substitute into
      the pattern. In this case we need a valid ruby gem, so we've picked [formatador](https://rubygems.org/gems/formatador).
    - `staticPreview`: On the index page we want to show an example badge, but for performance reasons we want that example to be generated without making an API call. `staticPreview` should be populated by calling our `render()` method with some valid data.
-   - `keywords`: If we want to provide additional keywords other than the title, we can add them here. This helps users to search for relevant badges.
+   - `keywords`: If we want to provide additional keywords other than the title and the category, we can add them here. This helps users to search for relevant badges.
 
 Save, run `npm start`, and you can see it [locally](http://127.0.0.1:3000/).
 

doc/deprecating-badges.md

@@ -22,7 +22,7 @@ module.exports = deprecatedService({
   category: 'size',
   route: {
     base: 'imagelayers',
-    format: '(?:.+)',
+    format: '(?:.+?)',
   },
   label: 'imagelayers',
   dateAdded: new Date('2019-xx-xx'), // Be sure to update this with today's date!

doc/production-hosting.md

@@ -7,22 +7,32 @@
 [operations issues]: https://github.com/badges/shields/issues?q=is%3Aissue+is%3Aopen+label%3Aoperations
 [ops discord]: https://discordapp.com/channels/308323056592486420/480747695879749633
 
-| Component      | Subcomponent             | People with access                                                                         |
-| -------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
-| Badge servers  | Account owner            | @espadrine                                                                                 |
-| Badge servers  | ssh, logs                | @espadrine                                                                                 |
-| Badge servers  | Deployment               | @espadrine, @paulmelnikow                                                                  |
-| Badge servers  | Admin endpoints          | @espadrine, @paulmelnikow                                                                  |
-| Cloudflare     | Account owner            | @espadrine                                                                                 |
-| Cloudflare     | Admin access             | @espadrine, @paulmelnikow                                                                  |
-| GitHub         | OAuth app                | @espadrine ([could be transferred to the badges org][oauth transfer])                      |
-| DNS            | Account owner            | @olivierlacan                                                                              |
-| DNS            | Read-only account access | @espadrine, @paulmelnikow, @chris48s                                                       |
-| Sentry         | Error reports            | @espadrine, @paulmelnikow                                                                  |
-| Frontend       | Deployment               | Technically anyone with push access but in practice must be deployed with the badge server |
-| Metrics server | Owner                    | @platan                                                                                    |
-| UptimeRobot    | Account owner            | @paulmelnikow                                                                              |
-| More metrics   | Owner                    | @RedSparr0w                                                                                |
+| Component                     | Subcomponent                    | People with access                                                                         |
+| ----------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------ |
+| Badge servers                 | Account owner                   | @espadrine                                                                                 |
+| Badge servers                 | ssh, logs                       | @espadrine                                                                                 |
+| Badge servers                 | Deployment                      | @espadrine, @paulmelnikow                                                                  |
+| Badge servers                 | Admin endpoints                 | @espadrine, @paulmelnikow                                                                  |
+| Compose.io Redis              | Account owner                   | @paulmelnikow                                                                              |
+| Compose.io Redis              | Account access                  | @paulmelnikow                                                                              |
+| Compose.io Redis              | Database connection credentials | @espadrine, @paulmelnikow                                                                  |
+| Zeit Now                      | Team owner                      | @paulmelnikow                                                                              |
+| Zeit Now                      | Team members                    | @paulmelnikow, @chris48s, @calebcartwright, @platan                                        |
+| Raster server                 | Full access as team members     | @paulmelnikow, @chris48s, @calebcartwright, @platan                                        |
+| shields-server.com redirector | Full access as team members     | @paulmelnikow, @chris48s, @calebcartwright, @platan                                        |
+| Cloudflare                    | Account owner                   | @espadrine                                                                                 |
+| Cloudflare                    | Admin access                    | @espadrine, @paulmelnikow                                                                  |
+| GitHub                        | OAuth app                       | @espadrine ([could be transferred to the badges org][oauth transfer])                      |
+| Twitch                        | OAuth app                       | @PyvesB                                                                                    |
+| OpenStreetMap (for Wheelmap)  | Account owner                   | @paulmelnikow                                                                              |
+| DNS                           | Account owner                   | @olivierlacan                                                                              |
+| DNS                           | Read-only account access        | @espadrine, @paulmelnikow, @chris48s                                                       |
+| Sentry                        | Error reports                   | @espadrine, @paulmelnikow                                                                  |
+| Frontend                      | Deployment                      | Technically anyone with push access but in practice must be deployed with the badge server |
+| Metrics server                | Owner                           | @platan                                                                                    |
+| UptimeRobot                   | Account owner                   | @paulmelnikow                                                                              |
+| More metrics                  | Owner                           | @RedSparr0w                                                                                |
+| Netlify (documentation site)  | Owner                           | @chris48s                                                                                  |
 
 There are [too many bottlenecks][issue 2577]!
 
@@ -32,9 +42,9 @@ There are three public badge servers on OVH VPS’s.
 
 | Cname                       | Hostname             | Type | IP             | Location           |
 | --------------------------- | -------------------- | ---- | -------------- | ------------------ |
-| [s0.shields-server.com][s0] | vps71670.vps.ovh.ca  | VPS  | 192.99.59.72   | Quebec, Canada     |
-| [s1.shields-server.com][s1] | vps244529.ovh.net    | VPS  | 51.254.114.150 | Gravelines, France |
-| [s2.shields-server.com][s2] | vps117870.vps.ovh.ca | VPS  | 149.56.96.133  | Quebec, Canada     |
+| [s0.servers.shields.io][s0] | vps71670.vps.ovh.ca  | VPS  | 192.99.59.72   | Quebec, Canada     |
+| [s1.servers.shields.io][s1] | vps244529.ovh.net    | VPS  | 51.254.114.150 | Gravelines, France |
+| [s2.servers.shields.io][s2] | vps117870.vps.ovh.ca | VPS  | 149.56.96.133  | Quebec, Canada     |
 
 - These are single-core virtual hosts with 2 GB RAM [VPS SSD 1][].
 - The Node version (v9.4.0 at time of writing) and dependency versions on the
@@ -52,9 +62,9 @@ There are three public badge servers on OVH VPS’s.
 - The public servers _do not_ use docker. The `Dockerfile` is included for
   self-hosting (including on a Docker-capable PaaS).
 
-[s0]: https://s0.shields-server.com/index.html
-[s1]: https://s1.shields-server.com/index.html
-[s2]: https://s2.shields-server.com/index.html
+[s0]: https://s0.servers.shields.io/index.html
+[s1]: https://s1.servers.shields.io/index.html
+[s2]: https://s2.servers.shields.io/index.html
 [vps ssd 1]: https://www.ovh.com/world/vps/vps-ssd.xml
 [issue 1460]: https://github.com/badges/shields/issues/1460
 [serverscript]: https://github.com/badges/ServerScript
@@ -63,18 +73,16 @@ There are three public badge servers on OVH VPS’s.
 
 Shields has mercifully little persistent state:
 
-1.  The GitHub tokens we collect are saved on each server in JSON files on disk.
-    They can be fetched from the [GitHub auth admin endpoint][] for debugging.
+1.  The GitHub tokens we collect are saved on each server in a cloud Redis database.
+    They can also be fetched from the [GitHub auth admin endpoint][] for debugging.
 2.  The server keeps a few caches in memory. These are neither persisted nor
     inspectable.
     - The [request cache][]
     - The [regular-update cache][]
-    - The [raster cache][]
 
 [github auth admin endpoint]: https://github.com/badges/shields/blob/master/services/github/auth/admin.js
 [request cache]: https://github.com/badges/shields/blob/master/core/base-service/legacy-request-handler.js#L29-L30
 [regular-update cache]: https://github.com/badges/shields/blob/master/core/legacy/regular-update.js
-[raster cache]: https://github.com/badges/shields/blob/master/gh-badges/lib/svg-to-img.js#L9-L10
 [oauth transfer]: https://developer.github.com/apps/managing-oauth-apps/transferring-ownership-of-an-oauth-app/
 
 ## Configuration
@@ -98,7 +106,7 @@ files:
 
 [start-shields.sh]: https://github.com/badges/ServerScript/blob/master/start-shields.sh#L7
 [config]: https://github.com/lorenwest/node-config/wiki/Configuration-Files
-[local-shields-io-production.yml]: ../config/local-shields-io-production.example.yml
+[local-shields-io-production.yml]: ../config/local-shields-io-production.template.yml
 [shields-io-production.yml]: ../config/shields-io-production.yml
 [default.yml]: ../config/default.yml
 
@@ -128,6 +136,15 @@ with the badge server via the deployment process described below.
 [github pages]: https://pages.github.com/
 [gh-pages]: https://github.com/badges/shields/tree/gh-pages
 
+## Raster server
+
+The raster server `raster.shields.io` (a.k.a. the rasterizing proxy) is
+hosted on [Zeit Now][]. It's managed in the
+[svg-to-image-proxy repo][svg-to-image-proxy].
+
+[zeit now]: https://zeit.co/now
+[svg-to-image-proxy]: https://github.com/badges/svg-to-image-proxy
+
 ## Deployment
 
 To set things up for deployment:
@@ -138,9 +155,9 @@ To set things up for deployment:
 3.  Add remotes:
 
 ```sh
-git remote add s0 root@s0.shields-server.com:/home/m/shields.git
-git remote add s1 root@s1.shields-server.com:/home/m/shields.git
-git remote add s2 root@s2.shields-server.com:/home/m/shields.git
+git remote add s0 root@s0.servers.shields.io:/home/m/shields.git
+git remote add s1 root@s1.servers.shields.io:/home/m/shields.git
+git remote add s2 root@s2.servers.shields.io:/home/m/shields.git
 ```
 
 `origin` should point to GitHub as usual.

doc/rewriting-services.md

@@ -152,7 +152,7 @@ Once the route is working, fill out `render()` and `handle()`.
 <details>
 
 ```js
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const { errorMessagesFor } = require('./github-helpers')
 
 const issueSchema = Joi.object({
@@ -181,7 +181,7 @@ or create an abstract superclass like **PypiBase**:
 <details>
 
 ```js
-const Joi = require('joi')
+const Joi = require('@hapi/joi')
 const BaseJsonService = require('../base-json')
 
 const schema = Joi.object({

doc/self-hosting.md

@@ -69,7 +69,7 @@ Successfully built 4471b442c220
 ```
 
 Optionally, create a file called `shields.env` that contains the needed
-configuration. See [server-secrets.md](server-secrets.md) and [../config/custom-environment-variables.yml](config/custom-environment-variables.yml) for examples.
+configuration. See [server-secrets.md](server-secrets.md) and [config/custom-environment-variables.yml](/config/custom-environment-variables.yml) for examples.
 
 Then run the container:
 
@@ -93,6 +93,27 @@ machine.
 
 [shields.example.env]: ../shields.example.env
 
+## Raster server
+
+If you want to host PNG badges, you can also self-host a [raster server][]
+which points to your badge server. It's designed as a web function which is
+tested on Zeit Now, though you may be able to run it on AWS Lambda. It's
+built on the [micro][] framework, and comes with a `start` script that allows
+it to run as a standalone Node service.
+
+- In your raster instance, set `BASE_URL` to your Shields instance, e.g.
+  `https://shields.example.co`.
+- Optionally, in your Shields, instance, configure `RASTER_URL` to the base
+  URL, e.g. `https://raster.example.co`. This will send 301 redirects
+  for the legacy raster URLs instead of 404's.
+
+If anyone has set this up, more documentation on how to do this would be
+welcome! It would also be nice to ship a Docker image that includes a
+preconfigured raster server.
+
+[raster server]: https://github.com/badges/svg-to-image-proxy
+[micro]: https://github.com/zeit/micro
+
 ## Zeit Now
 
 To deploy using Zeit Now:

doc/server-secrets.md

@@ -141,6 +141,14 @@ Create an account, sign in and obtain a uuid and token from your
 to give your self-hosted Shields installation access to a
 private SonarQube instance or private project on a public instance.
 
+## Twitch
+
+- `TWITCH_CLIENT_ID` (yml: `twitch_client_id`)
+- `TWITCH_CLIENT_SECRET` (yml: `twitch_client_secret`)
+
+Register an application in the [Twitch developer console](https://dev.twitch.tv/console)
+in order to obtain a client id and a client secret for making Twitch API calls.
+
 ## Wheelmap
 
 - `WHEELMAP_TOKEN` (yml: `wheelmap_token`)

doc/service-tests.md

@@ -221,7 +221,7 @@ static render({ status, result }) {
 We can also use nock to intercept API calls to return a known response body.
 
 ```js
-t.create('Build passed (mocked)')
+t.create('Build passed')
   .get('/build/wercker/go-wercker-api.json')
   .intercept(nock =>
     nock('https://app.wercker.com/api/v3/applications/')
@@ -234,7 +234,7 @@ t.create('Build passed (mocked)')
     color: 'brightgreen',
   })
 
-t.create('Build failed (mocked)')
+t.create('Build failed')
   .get('/build/wercker/go-wercker-api.json')
   .intercept(nock =>
     nock('https://app.wercker.com/api/v3/applications/')

entrypoint.spec.js

@@ -1,9 +1,8 @@
 'use strict'
 
 const { expect } = require('chai')
-// https://github.com/nock/nock/issues/1523
-const got = require('got').extend({ retry: 0 })
 const isSvg = require('is-svg')
+const got = require('./core/got-test-client')
 
 let server
 before(function() {

frontend/.eslintrc.yml

@@ -1 +0,0 @@
-extends: '../.eslintrc-frontend.yml'

frontend/components/badge-examples.js

@@ -1,96 +0,0 @@
-import React from 'react'
-import PropTypes from 'prop-types'
-import styled from 'styled-components'
-import {
-  badgeUrlFromPattern,
-  staticBadgeUrl,
-} from '../../core/badge-urls/make-badge-url'
-import { examplePropType } from '../lib/service-definitions/example-prop-types'
-import { Badge } from './common'
-import { StyledCode } from './snippet'
-
-const ExampleTable = styled.table`
-  min-width: 50%;
-  margin: auto;
-
-  th,
-  td {
-    text-align: left;
-  }
-`
-
-const ClickableTh = styled.th`
-  cursor: pointer;
-`
-
-const ClickableCode = styled(StyledCode)`
-  cursor: pointer;
-`
-
-function Example({ baseUrl, onClick, exampleData }) {
-  const { title, example, preview } = exampleData
-
-  const { pattern, namedParams, queryParams } = example
-  const exampleUrl = badgeUrlFromPattern({
-    baseUrl,
-    pattern,
-    namedParams,
-    queryParams,
-  })
-
-  let previewUrl
-  if (preview.buildFromExample) {
-    previewUrl = exampleUrl
-  } else {
-    const { label, message, color, style, namedLogo } = preview
-    previewUrl = staticBadgeUrl({
-      baseUrl,
-      label,
-      message,
-      color,
-      style,
-      namedLogo,
-    })
-  }
-
-  const handleClick = () => onClick(exampleData)
-
-  return (
-    <tr>
-      <ClickableTh onClick={handleClick}>{title}:</ClickableTh>
-      <td>
-        <Badge clickable onClick={handleClick} src={previewUrl} />
-      </td>
-      <td>
-        <ClickableCode onClick={handleClick}>{exampleUrl}</ClickableCode>
-      </td>
-    </tr>
-  )
-}
-Example.propTypes = {
-  exampleData: examplePropType.isRequired,
-  baseUrl: PropTypes.string,
-  onClick: PropTypes.func.isRequired,
-}
-
-export default function BadgeExamples({ examples, baseUrl, onClick }) {
-  return (
-    <ExampleTable>
-      <tbody>
-        {examples.map(exampleData => (
-          <Example
-            baseUrl={baseUrl}
-            exampleData={exampleData}
-            key={`${exampleData.title} ${exampleData.example.pattern}`}
-            onClick={onClick}
-          />
-        ))}
-      </tbody>
-    </ExampleTable>
-  )
-}
-BadgeExamples.propTypes = {
-  examples: PropTypes.arrayOf(examplePropType).isRequired,
-  baseUrl: PropTypes.string,
-  onClick: PropTypes.func.isRequired,
-}

frontend/components/badge-examples.spec.js

@@ -1,110 +0,0 @@
-import React from 'react'
-import { shallow } from 'enzyme'
-import BadgeExamples from './badge-examples'
-
-import '../enzyme-conf.spec'
-
-const exampleServiceDefinitions = [
-  {
-    title: 'Mozilla Add-on',
-    example: {
-      pattern: '/amo/d/:addonId',
-      namedParams: {
-        addonId: 'dustman',
-      },
-      queryParams: {},
-    },
-    preview: {
-      label: 'downloads',
-      message: '12k',
-      color: 'brightgreen',
-    },
-    keywords: ['amo', 'firefox'],
-  },
-  {
-    title: 'Mozilla Add-on',
-    example: {
-      pattern: '/amo/rating/:addonId',
-      namedParams: {
-        addonId: 'dustman',
-      },
-      queryParams: {},
-    },
-    preview: {
-      label: 'rating',
-      message: '4/5',
-      color: 'brightgreen',
-    },
-    keywords: ['amo', 'firefox'],
-  },
-  {
-    title: 'Mozilla Add-on',
-    example: {
-      pattern: '/amo/stars/:addonId',
-      namedParams: {
-        addonId: 'dustman',
-      },
-      queryParams: {},
-    },
-    preview: {
-      label: 'stars',
-      message: '★★★★☆',
-      color: 'brightgreen',
-    },
-    keywords: ['amo', 'firefox'],
-  },
-  {
-    title: 'Mozilla Add-on',
-    example: {
-      pattern: '/amo/users/:addonId',
-      namedParams: {
-        addonId: 'dustman',
-      },
-      queryParams: {},
-    },
-    preview: {
-      label: 'users',
-      message: '750',
-      color: 'blue',
-    },
-    keywords: ['amo', 'firefox'],
-  },
-  {
-    title: 'Mozilla Add-on',
-    example: {
-      pattern: '/amo/v/:addonId',
-      namedParams: {
-        addonId: 'dustman',
-      },
-      queryParams: {},
-    },
-    preview: {
-      label: 'mozilla add-on',
-      message: 'v2.1.0',
-      color: 'blue',
-    },
-    keywords: ['amo', 'firefox'],
-  },
-]
-
-describe('<BadgeExamples />', function() {
-  it('renders with no examples', function() {
-    shallow(
-      <BadgeExamples
-        baseUrl="https://example.shields.io"
-        examples={[]}
-        onClick={() => {}}
-      />
-    )
-  })
-
-  it('renders an array of examples', function() {
-    shallow(
-      <BadgeExamples
-        baseUrl="https://example.shields.io"
-        examples={exampleServiceDefinitions}
-        onClick={() => {}}
-      />
-    )
-  })
-})

frontend/components/badge-examples.tsx

@@ -0,0 +1,125 @@
+import React from 'react'
+import styled from 'styled-components'
+import {
+  badgeUrlFromPath,
+  badgeUrlFromPattern,
+  staticBadgeUrl,
+} from '../../core/badge-urls/make-badge-url'
+import { removeRegexpFromPattern } from '../lib/pattern-helpers'
+import {
+  Example as ExampleData,
+  Suggestion,
+  RenderableExample,
+} from '../lib/service-definitions'
+import { Badge } from './common'
+import { StyledCode } from './snippet'
+
+const ExampleTable = styled.table`
+  min-width: 50%;
+  margin: auto;
+
+  th,
+  td {
+    text-align: left;
+  }
+`
+
+const ClickableTh = styled.th`
+  cursor: pointer;
+`
+
+const ClickableCode = styled(StyledCode)`
+  cursor: pointer;
+`
+
+function Example({
+  baseUrl,
+  onClick,
+  exampleData,
+  isBadgeSuggestion,
+}: {
+  baseUrl?: string
+  onClick: (example: RenderableExample, isSuggestion: boolean) => void
+  exampleData: RenderableExample
+  isBadgeSuggestion: boolean
+}) {
+  function handleClick() {
+    onClick(exampleData, isBadgeSuggestion)
+  }
+
+  let exampleUrl, previewUrl
+  if (isBadgeSuggestion) {
+    const {
+      example: { pattern, namedParams, queryParams },
+    } = exampleData as Suggestion
+    exampleUrl = previewUrl = badgeUrlFromPattern({
+      baseUrl,
+      pattern,
+      namedParams,
+      queryParams,
+    })
+  } else {
+    const {
+      example: { pattern, queryParams },
+      preview: { label, message, color, style, namedLogo },
+    } = exampleData as ExampleData
+    previewUrl = staticBadgeUrl({
+      baseUrl,
+      label: label || '',
+      message,
+      color,
+      style,
+      namedLogo,
+    })
+    exampleUrl = badgeUrlFromPath({
+      path: removeRegexpFromPattern(pattern),
+      queryParams,
+    })
+  }
+
+  const { title } = exampleData
+  return (
+    <tr>
+      <ClickableTh onClick={handleClick}>{title}:</ClickableTh>
+      <td>
+        <Badge
+          alt={`${title} badge`}
+          clickable
+          onClick={handleClick}
+          src={previewUrl}
+        />
+      </td>
+      <td>
+        <ClickableCode onClick={handleClick}>{exampleUrl}</ClickableCode>
+      </td>
+    </tr>
+  )
+}
+
+export function BadgeExamples({
+  examples,
+  areBadgeSuggestions,
+  baseUrl,
+  onClick,
+}: {
+  examples: RenderableExample[]
+  areBadgeSuggestions: boolean
+  baseUrl?: string
+  onClick: (exampleData: RenderableExample, isSuggestion: boolean) => void
+}) {
+  return (
+    <ExampleTable>
+      <tbody>
+        {examples.map(exampleData => (
+          <Example
+            baseUrl={baseUrl}
+            exampleData={exampleData}
+            isBadgeSuggestion={areBadgeSuggestions}
+            key={`${exampleData.title} ${exampleData.example.pattern}`}
+            onClick={onClick}
+          />
+        ))}
+      </tbody>
+    </ExampleTable>
+  )
+}

frontend/components/category-headings.spec.js

@@ -1,33 +0,0 @@
-import React from 'react'
-import { shallow } from 'enzyme'
-import { expect } from 'chai'
-import { H3 } from './common'
-import { CategoryHeading, CategoryHeadings } from './category-headings'
-
-import '../enzyme-conf.spec'
-
-const exampleCategories = [{ id: 'cat', name: 'Example category' }]
-
-describe('<CategoryHeading />', function() {
-  it('renders', function() {
-    shallow(<CategoryHeading category={exampleCategories[0]} />)
-  })
-
-  it('contains the expected heading', function() {
-    const wrapper = shallow(<CategoryHeading category={exampleCategories[0]} />)
-    expect(wrapper).to.contain(<H3 id="cat">Example category</H3>)
-  })
-})
-
-describe('<CategoryHeadings />', function() {
-  it('renders', function() {
-    shallow(<CategoryHeadings categories={exampleCategories} />)
-  })
-
-  it('contains the expected child', function() {
-    const wrapper = shallow(<CategoryHeadings categories={exampleCategories} />)
-    expect(wrapper).to.contain(
-      <CategoryHeading category={exampleCategories[0]} />
-    )
-  })
-})

frontend/components/category-headings.tsx

@@ -1,24 +1,26 @@
 import React from 'react'
-import PropTypes from 'prop-types'
 import styled from 'styled-components'
 import { Link } from 'gatsby'
 import { H3 } from './common'
 
-export function CategoryHeading({ category: { id, name } }) {
+export interface Category {
+  id: string
+  name: string
+}
+
+export function CategoryHeading({
+  category: { id, name },
+}: {
+  category: Category
+}) {
   return (
     <Link to={`/category/${id}`}>
       <H3 id={id}>{name}</H3>
     </Link>
   )
 }
-CategoryHeading.propTypes = {
-  category: PropTypes.shape({
-    id: PropTypes.string.isRequired,
-    name: PropTypes.string.isRequired,
-  }).isRequired,
-}
 
-export function CategoryHeadings({ categories }) {
+export function CategoryHeadings({ categories }: { categories: Category[] }) {
   return (
     <div>
       {categories.map(category => (
@@ -27,9 +29,6 @@ export function CategoryHeadings({ categories }) {
     </div>
   )
 }
-CategoryHeadings.propTypes = {
-  categories: PropTypes.arrayOf(CategoryHeading.propTypes.category).isRequired,
-}
 
 const StyledNav = styled.nav`
   ul {
@@ -62,7 +61,7 @@ const StyledNav = styled.nav`
   }
 `
 
-export function CategoryNav({ categories }) {
+export function CategoryNav({ categories }: { categories: Category[] }) {
   return (
     <StyledNav>
       <ul>
@@ -75,6 +74,3 @@ export function CategoryNav({ categories }) {
     </StyledNav>
   )
 }
-CategoryNav.propTypes = {
-  categories: PropTypes.arrayOf(CategoryHeading.propTypes.category).isRequired,
-}

frontend/components/common.spec.js

@@ -1,69 +0,0 @@
-import React from 'react'
-import { shallow, render } from 'enzyme'
-import { expect } from 'chai'
-import * as common from './common'
-
-import '../enzyme-conf.spec'
-
-describe('Common modules', function() {
-  describe('<GlobalStyle />', function() {
-    it('renders', function() {
-      shallow(<common.GlobalStyle />)
-    })
-  })
-
-  describe('<BaseFont />', function() {
-    it('renders', function() {
-      shallow(<common.BaseFont />)
-    })
-  })
-
-  describe('<H2 />', function() {
-    it('renders', function() {
-      shallow(<common.H2 />)
-    })
-  })
-
-  describe('<H3 />', function() {
-    it('renders', function() {
-      shallow(<common.H3 />)
-    })
-  })
-
-  describe('<Badge />', function() {
-    it('renders', function() {
-      shallow(<common.Badge src="/badge/foo-bar-blue.svg" />)
-    })
-
-    it('contains a link to the image', function() {
-      const wrapper = render(<common.Badge src="/badge/foo-bar-blue.svg" />)
-      expect(wrapper.html()).to.contain(
-        '<img alt="" src="/badge/foo-bar-blue.svg">'
-      )
-    })
-  })
-
-  describe('<StyledInput />', function() {
-    it('renders', function() {
-      shallow(<common.StyledInput />)
-    })
-  })
-
-  describe('<InlineInput />', function() {
-    it('renders', function() {
-      shallow(<common.InlineInput />)
-    })
-  })
-
-  describe('<BlockInput />', function() {
-    it('renders', function() {
-      shallow(<common.BlockInput />)
-    })
-  })
-
-  describe('<VerticalSpace />', function() {
-    it('renders', function() {
-      shallow(<common.VerticalSpace />)
-    })
-  })
-})

frontend/components/common.tsx

@@ -1,12 +1,11 @@
 import React from 'react'
-import PropTypes from 'prop-types'
 import styled, { css, createGlobalStyle } from 'styled-components'
 
 export const noAutocorrect = Object.freeze({
   autoComplete: 'off',
   autoCorrect: 'off',
   autoCapitalize: 'off',
-  spellCheck: 'false',
+  spellcheck: 'false',
 })
 
 export const nonBreakingSpace = '\u00a0'
@@ -41,7 +40,13 @@ export const H3 = styled.h3`
   font-style: italic;
 `
 
-const BadgeWrapper = styled.span`
+interface BadgeWrapperProps {
+  height: string
+  display: string
+  clickable: boolean
+}
+
+const BadgeWrapper = styled.span<BadgeWrapperProps>`
   padding: 2px;
   height: ${({ height }) => height};
   vertical-align: middle;
@@ -54,6 +59,14 @@ const BadgeWrapper = styled.span`
     `};
 `
 
+interface BadgeProps extends React.HTMLAttributes<HTMLImageElement> {
+  src: string
+  alt?: string
+  display?: 'inline' | 'block' | 'inline-block'
+  height?: string
+  clickable?: boolean
+}
+
 export function Badge({
   src,
   alt = '',
@@ -61,20 +74,13 @@ export function Badge({
   height = '20px',
   clickable = false,
   ...rest
-}) {
+}: BadgeProps) {
   return (
     <BadgeWrapper clickable={clickable} display={display} height={height}>
       {src ? <img alt={alt} src={src} {...rest} /> : nonBreakingSpace}
     </BadgeWrapper>
   )
 }
-Badge.propTypes = {
-  src: PropTypes.string.isRequired,
-  alt: PropTypes.string,
-  display: PropTypes.oneOf(['inline', 'block', 'inline-block']),
-  height: PropTypes.string,
-  clickable: PropTypes.bool,
-}
 
 export const StyledInput = styled.input`
   height: 15px;