Shields.io server and frontend
Create a badge
Name | Type | Description | |
---|---|---|---|
format |
object
|
Object specifying badge data |
|
format.label |
string
|
(Optional) Badge label (e.g: 'build') |
|
format.message |
string
|
(Required) Badge message (e.g: 'passing') |
|
format.labelColor |
string
|
(Optional) Label color |
|
format.color |
string
|
(Optional) Message color |
|
format.style |
string
|
(Optional) Visual style e.g: 'flat' |
string
Badge in SVG format
Services which query a GraphQL endpoint should extend BaseGraphqlService
Void
Parse data from JSON endpoint
Name | Type | Description | |
---|---|---|---|
buffer |
string
|
JSON repsonse from upstream API |
object
Parsed response
Services which query a JSON endpoint should extend BaseJsonService
Void
Parse data from JSON endpoint
Name | Type | Description | |
---|---|---|---|
buffer |
string
|
JSON repsonse from upstream API |
object
Parsed response
Services which scrape data from another SVG badge should extend BaseSvgScrapingService
Void
Extract a value from SVG
Name | Type | Description | |
---|---|---|---|
svg |
string
|
SVG to parse |
|
valueMatcher=defaultValueMatcher |
RegExp
|
RegExp to match the value we want to parse from the SVG |
Optional |
string
Matched value
Services which query a XML endpoint should extend BaseXmlService
Void
Services which query a YAML endpoint should extend BaseYamlService
Void
Abstract base class which all service classes inherit from. Concrete implementations of BaseService must implement the methods category(), route() and handle(namedParams, queryParams)
Void
Name | Type | Description | |
---|---|---|---|
title |
string
|
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 |
object
|
An object containing the values of named parameters to substitute into the compiled route pattern. |
|
queryParams |
object
|
An object containing query parameters to include in the
example URLs. For alphanumeric query parameters, specify a string value.
For boolean query parameters, specify |
|
pattern |
string
|
The route pattern to compile. Defaults to |
|
staticPreview |
object
|
A rendered badge of the sort returned by |
|
keywords |
Array.<string>
|
Additional keywords, other than words in the title. This helps users locate relevant badges. |
|
documentation |
string
|
An HTML string that is included in the badge popup. |
Void
Name of the class. Implementations of ShieldsRuntimeError should override this method.
Void
Default message for this exception if none is specified. Implementations of ShieldsRuntimeError should implement this method.
Void
Name | Type | Description | |
---|---|---|---|
props | Refer to individual attrs |
||
message |
string
|
Exception message for debug purposes |
Void
Throw this to wrap a 404 or other 'not found' response from an upstream API
Void
Name | Type | Description | |
---|---|---|---|
props | Refer to individual attrs |
Void
Throw this to wrap an invalid or unexpected response from an upstream API
Void
Name | Type | Description | |
---|---|---|---|
props | Refer to individual attrs |
Void
Throw this if we can't contact an upstream API or to wrap a 5XX response
Void
Name | Type | Description | |
---|---|---|---|
props | Refer to individual attrs |
Void
Name | Type | Description | |
---|---|---|---|
props | Refer to individual attrs |
Void
Throw this error when a user supplied input or parameter is invalid or unexpected
Void
Name | Type | Description | |
---|---|---|---|
props | Refer to individual attrs |
Void
Throw this error to indicate that a service is deprecated or removed
Void
Name | Type | Description | |
---|---|---|---|
props | Refer to individual attrs |
Void
Name | Type | Description | |
---|---|---|---|
underlyingError |
Error
|
Exception we are wrapping (Optional) |
|
response |
object
|
Response from an upstream API to provide context for the error (Optional) |
|
prettyMessage |
string
|
User-facing error message to override the value of |
Void
Utility function to merge two graphql queries together This is basically copied from graphql-query-merge but can't use that due to incorrect packaging.
Name | Type | Description | |
---|---|---|---|
queries |
object
|
queries to merge |
object
merged query
Name | Type | Description | |
---|---|---|---|
attrs |
object
|
Refer to individual attrs |
|
attrs.category |
string
|
e.g: 'build' |
|
attrs.serviceFamily |
string
|
e.g: 'npm' |
|
attrs.name |
string
|
e.g: 'NpmVersion' |
object
{ inc() {} }
.
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.
Void
Badge Server Constructor
Name | Type | Description | |
---|---|---|---|
config |
object
|
Configuration object read from config yaml files by https://www.npmjs.com/package/config and validated against publicConfigSchema and privateConfigSchema |
Void
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/} )
Void
Iterate all the service classes defined in /services, load each service and register a Scoutcamp route for each service.
Void
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.
ServiceTester instance
Factory which wraps an "icedfrisby-nock" with some additional functionality:
Name | Type | Description | |
---|---|---|---|
superclass |
Function
|
class to extend |
Function
wrapped class
When called inside a CI build, infer the details of a pull request from the environment variables.
Name | Type | Description | |
---|---|---|---|
env=process.env |
object
|
Environment variables |
Optional |
Pull Request
Pull Request
Name | Type | Description | |
---|---|---|---|
pr.baseUrl |
string
|
(returned for travis CI only) |
|
owner |
string
|
||
repo |
string
|
||
pullRequest |
string
|
PR/issue number |
|
slug |
string
|
owner/repo/#pullRequest |
Void
Load a collection of ServiceTester objects and register them with Mocha.
Void
Function to invoke before each test. This is a stub which can be overridden on instances.
Void
Limit the test run to the specified services.
Name | Type | Description | |
---|---|---|---|
services |
Array.<string>
|
An array of service id prefixes to run |
Void
Encapsulate a suite of tests. Create new tests using create() and register them with Mocha using toss().
Void
Service Tester Constructor
Name | Type | Description | |
---|---|---|---|
attrs |
object
|
Refer to individual attrs |
|
attrs.id |
string
|
Specifies which tests to run from the CLI or pull requests |
|
attrs.title |
string
|
Prints in the Mocha output |
|
attrs.pathPrefix |
string
|
Prefix which is automatically prepended to each tested URI.
The default is |
Void
Construct a ServiceTester instance for a single service class
Name | Type | Description | |
---|---|---|---|
ServiceClass |
Function
|
A class that extends base-service/base.BaseService |
ServiceTester for ServiceClass
Invoked before each test. This is a stub which can be overridden on instances.
Void
Create a new test. The hard work is delegated to IcedFrisby. {@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.
Name | Type | Description | |
---|---|---|---|
msg |
string
|
The name of the test |
IcedFrisby instance
Run only this tester. This can be invoked using the --only argument to the CLI, or directly on the tester.
Void
Register the tests with Mocha.
Name | Type | Description | |
---|---|---|---|
attrs |
object
|
Refer to individual attrs |
|
attrs.baseUrl |
string
|
base URL for test server |
|
attrs.skipIntercepted |
boolean
|
skip tests which intercept requests |
|
attrs.retry |
object
|
retry configuration |
|
attrs.retry.count |
number
|
number of times to retry test |
|
attrs.retry.backoff |
number
|
number of milliseconds to add to the wait between each retry |
Void
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.
Name | Type | Description | |
---|---|---|---|
title |
string
|
Pull Request title |
Array.<string>
Array of service names
Compute a one-way hash of the input string.
Name | Type | Description | |
---|---|---|---|
id |
string
|
token |
string
hash
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.
Void
Token Constructor
Name | Type | Description | |
---|---|---|---|
id |
string
|
token string |
|
data | reserved for future use |
||
usesRemaining |
number
|
Number of uses remaining until the token is exhausted |
|
nextReset |
number
|
Time when the token can be used again even if it's exhausted (unix timestamp) |
Void
Update the uses remaining and next reset time for a token.
Name | Type | Description | |
---|---|---|---|
usesRemaining |
number
|
Number of uses remaining until the token is exhausted |
|
nextReset |
number
|
Time when the token can be used again even if it's exhausted (unix timestamp) |
Void
Freeze the uses remaining and next reset values. Helpful for keeping stable ordering for a valid priority queue.
Void
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.
Void
TokenPool Constructor
Name | Type | Description | |
---|---|---|---|
batchSize |
number
|
The maximum number of times we use each token before moving on to the next one. |
Void
compareTokens
Name | Type | Description | |
---|---|---|---|
first | first token to compare |
||
second | second token to compare |
The token whose current rate allotment is expiring soonest.
Add a token with user-provided ID and data.
Name | Type | Description | |
---|---|---|---|
id |
string
|
token string |
|
data | reserved for future use |
||
usesRemaining |
number
|
Number of uses remaining until the token is exhausted |
|
nextReset |
number
|
Time when the token can be used again even if it's exhausted (unix timestamp) |
boolean
Was the token added to the pool?
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.
token
Iterate over all valid tokens.
Name | Type | Description | |
---|---|---|---|
callback |
Function
|
function to execute on each valid token |
Void
Dynamic service class factory which wraps {@link module:core/base-service/base~BaseService} with support of {@link https://jsonpath.com/|JSONPath}.
Name | Type | Description | |
---|---|---|---|
superclass |
Function
|
class to extend |
Function
wrapped class
Validates affiliations should contain combination of allowed values in any order.
Name | Type | Description | |
---|---|---|---|
value |
string
|
affiliation current value |
|
helpers | object to construct custom error |
string
valiadtion error or value unchanged
Return color for active, maintenance and archived statuses, which were the three example keywords used in Netflix's open-source meetup. See https://slideshare.net/aspyker/netflix-open-source-meetup-season-4-episode-1 Other keywords are possible, but will appear in grey.
Name | Type | Description | |
---|---|---|---|
attrs |
object
|
Refer to individual attrs |
|
attrs.status |
string
|
Specifies the current maintenance status |
string
color