Back to Top

shields.io master

Shields.io server and frontend

_makeBadge()

Returns

Void

makeBadge(format)

Create a badge

Parameters

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'

Returns

string

Badge in SVG format

new BaseGraphqlService()

Services which query a GraphQL endpoint should extend BaseGraphqlService

Returns

Void

BaseGraphqlService._parseJson(buffer)

Parse data from JSON endpoint

Parameters

Name Type Description
buffer string

JSON repsonse from upstream API

Returns

object

Parsed response

new BaseJsonService()

Services which query a JSON endpoint should extend BaseJsonService

Returns

Void

BaseJsonService._parseJson(buffer)

Parse data from JSON endpoint

Parameters

Name Type Description
buffer string

JSON repsonse from upstream API

Returns

object

Parsed response

new BaseSvgScrapingService()

Services which scrape data from another SVG badge should extend BaseSvgScrapingService

Returns

Void

BaseSvgScrapingService.valueFromSvgBadge(svg[, valueMatcher=defaultValueMatcher])

Extract a value from SVG

Parameters

Name Type Description
svg string

SVG to parse

valueMatcher=defaultValueMatcher RegExp

RegExp to match the value we want to parse from the SVG

Optional

Returns

string

Matched value

new BaseXmlService()

Services which query a XML endpoint should extend BaseXmlService

Returns

Void

new BaseYamlService()

Services which query a YAML endpoint should extend BaseYamlService

Returns

Void

new BaseService()

Abstract base class which all service classes inherit from. Concrete implementations of BaseService must implement the methods category(), route() and handle(namedParams, queryParams)

Returns

Void

module.exports()

Properties

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 null.

pattern string

The route pattern to compile. Defaults to this.route.pattern.

staticPreview object

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 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.

Returns

Void

new ShieldsRuntimeError()

Base error class

Returns

Void

ShieldsRuntimeError.name()

Name of the class. Implementations of ShieldsRuntimeError should override this method.

Returns

Void

ShieldsRuntimeError.defaultPrettyMessage()

Default message for this exception if none is specified. Implementations of ShieldsRuntimeError should implement this method.

Returns

Void

ShieldsRuntimeError.constructor(props, message)

Parameters

Name Type Description
props

Refer to individual attrs

message string

Exception message for debug purposes

Returns

Void

new NotFound()

Throw this to wrap a 404 or other 'not found' response from an upstream API

Returns

Void

NotFound.constructor(props)

Parameters

Name Type Description
props

Refer to individual attrs

Returns

Void

new InvalidResponse()

Throw this to wrap an invalid or unexpected response from an upstream API

Returns

Void

InvalidResponse.constructor(props)

Parameters

Name Type Description
props

Refer to individual attrs

Returns

Void

new Inaccessible()

Throw this if we can't contact an upstream API or to wrap a 5XX response

Returns

Void

Inaccessible.constructor(props)

Parameters

Name Type Description
props

Refer to individual attrs

Returns

Void

new ImproperlyConfigured()

Throw this error when required credentials are missing

Returns

Void

ImproperlyConfigured.constructor(props)

Parameters

Name Type Description
props

Refer to individual attrs

Returns

Void

new InvalidParameter()

Throw this error when a user supplied input or parameter is invalid or unexpected

Returns

Void

InvalidParameter.constructor(props)

Parameters

Name Type Description
props

Refer to individual attrs

Returns

Void

new Deprecated()

Throw this error to indicate that a service is deprecated or removed

Returns

Void

Deprecated.constructor(props)

Parameters

Name Type Description
props

Refer to individual attrs

Returns

Void

module.exports()

Properties

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 defaultPrettyMessage(). This is the text that will appear on the badge when we catch and render the exception (Optional)

Returns

Void

mergeQueries(queries)

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.

Parameters

Name Type Description
queries object

queries to merge

Returns

object

merged query

createNumRequestCounter(attrs)

Parameters

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'

Returns

object

{ inc() {} }.

path()

Returns

Void

new 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.

Returns

Void

Server.constructor(config)

Badge Server Constructor

Parameters

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

Returns

Void

Server.registerErrorHandlers()

Set up Scoutcamp routes for 404/not found responses

Returns

Void

Server.registerRedirects()

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/} )

Returns

Void

Server.registerServices()

Iterate all the service classes defined in /services, load each service and register a Scoutcamp route for each service.

Returns

Void

caller()

Returns

Void

createServiceTester()

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

ServiceTester instance

Joi()

Returns

Void

factory(superclass)

Factory which wraps an "icedfrisby-nock" with some additional functionality:

  • check if a request was intercepted
  • set expectations on the badge JSON response

Parameters

Name Type Description
superclass Function

class to extend

Returns

Function

wrapped class

inferPullRequest()

When called inside a CI build, infer the details of a pull request from the environment variables.

Parameters

Name Type Description
env=process.env object

Environment variables

Optional

Returns

Pull Request

module.exports()

Pull Request

Properties

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

Returns

Void

new Runner()

Load a collection of ServiceTester objects and register them with Mocha.

Returns

Void

Runner.beforeEach()

Function to invoke before each test. This is a stub which can be overridden on instances.

Returns

Void

Runner.prepare()

Prepare the runner by loading up all the ServiceTester objects.

Returns

Void

Runner.only(services)

Limit the test run to the specified services.

Parameters

Name Type Description
services Array.<string>

An array of service id prefixes to run

Returns

Void

Runner.toss()

Register the tests with Mocha.

Returns

Void

emojic()

Returns

Void

new ServiceTester()

Encapsulate a suite of tests. Create new tests using create() and register them with Mocha using toss().

Returns

Void

ServiceTester.constructor(attrs)

Service Tester Constructor

Parameters

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 /${attrs.id}.

Returns

Void

ServiceTester.forServiceClass(ServiceClass)

Construct a ServiceTester instance for a single service class

Parameters

Name Type Description
ServiceClass Function

A class that extends base-service/base.BaseService

Returns

ServiceTester for ServiceClass

ServiceTester.beforeEach()

Invoked before each test. This is a stub which can be overridden on instances.

Returns

Void

ServiceTester.create(msg)

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.

Parameters

Name Type Description
msg string

The name of the test

Returns

IcedFrisby instance

ServiceTester.only()

Run only this tester. This can be invoked using the --only argument to the CLI, or directly on the tester.

Returns

Void

ServiceTester.toss(attrs)

Register the tests with Mocha.

Parameters

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

Returns

Void

difference()

Returns

Void

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.

Parameters

Name Type Description
title string

Pull Request title

Returns

Array.<string>

Array of service names

crypto()

Returns

Void

sanitizeToken(id)

Compute a one-way hash of the input string.

Parameters

Name Type Description
id string

token

Returns

string

hash

new Token()

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.

Returns

Void

Token.constructor(id, data, usesRemaining, nextReset)

Token Constructor

Parameters

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)

Returns

Void

Token.update(usesRemaining, nextReset)

Update the uses remaining and next reset time for a token.

Parameters

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)

Returns

Void

Token.invalidate()

Indicate that the token should no longer be used.

Returns

Void

Token.freeze()

Freeze the uses remaining and next reset values. Helpful for keeping stable ordering for a valid priority queue.

Returns

Void

Token.unfreeze()

Unfreeze the uses remaining and next reset values.

Returns

Void

new TokenPool()

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.

Returns

Void

TokenPool.constructor(batchSize)

TokenPool Constructor

Parameters

Name Type Description
batchSize number

The maximum number of times we use each token before moving on to the next one.

Returns

Void

TokenPool.compareTokens(first, second)

compareTokens

Parameters

Name Type Description
first

first token to compare

second

second token to compare

Returns

The token whose current rate allotment is expiring soonest.

TokenPool.add(id, data, usesRemaining, nextReset)

Add a token with user-provided ID and data.

Parameters

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)

Returns

boolean

Was the token added to the pool?

TokenPool.next()

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

token

TokenPool.forEach(callback)

Iterate over all valid tokens.

Parameters

Name Type Description
callback Function

function to execute on each valid token

Returns

Void

module.exports()

Returns

Void

module.exports(superclass)

Dynamic service class factory which wraps {@link module:core/base-service/base~BaseService} with support of {@link https://jsonpath.com/|JSONPath}.

Parameters

Name Type Description
superclass Function

class to extend

Returns

Function

wrapped class

validateAffiliations(value, helpers)

Validates affiliations should contain combination of allowed values in any order.

Parameters

Name Type Description
value string

affiliation current value

helpers

object to construct custom error

Returns

string

valiadtion error or value unchanged

getColor(attrs)

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.

Parameters

Name Type Description
attrs object

Refer to individual attrs

attrs.status string

Specifies the current maintenance status

Returns

string

color

new BaseSteamAPI()

The steam api is based like /{interface}/{method}/v{version}/

Returns

Void