Supershields scripting

General about scripting

When Supershields gets a request from an HTTP client who wants to load an SVG badge, this happens:

1. Supershields will fire off an AWS Lambda instance and use it to execute the Lua script associated with the badge

2. The query() function defined in the script code gets executed (not having a query() function results in an error when someone tries to load the badge)

3. The return value from query() should be a configuration object - i.e. a Lua object containing formatting data the server will then use when it renders the actual SVG code that is returned to the HTTP client

See the The configuration object for more info on the object query() should return.

Caching

Badges are cached using a CDN (Cloudflare). This makes delivery to many clients fast and scalable, but means badge updates are not instantaneous as the Lua code is only executed when a badge is fetched from the Supershields servers directly.

The default is for the CDN to cache a badge 300 seconds (5 minutes) before getting a new copy from source. The HTTP Cache header will reflect this, making browsers keep from asking for new data unnecessarily often.

Premium users may set a lower cache time for their badges by manipulating the fetch_interval and min_fetch_interval members of the configuration object. Free users can also change these values, but only set them to 300 (seconds) or more.

The Supershields scripting API

The scripting API functionality available to Lua scripts consists of a few standard Lua libraries (as implemented in gopher-lua) plus a couple of Supershields-specific things.

Note that require is disabled in the scripts. I.e. all the libraries you have access to have already been loaded for you when the script starts executing

Standard libraries:

• math

Libraries imported from https://github.com/vadv/gopher-lua-libs:

• http
• json
• time

Supershields-specific:

• print() takes one or more string arguments and will print those, separated by tabs and ended with a newline. The output will end up in the script test window/tab, allowing you to print out debugging information while testing your scripts

• write() does the same thing as print, but does not add any tabs or newlines

• get_config() returns the badge configuration, including the formatting that was configured using the badge config editor. A static text badge will usually have its appearance defined there and have a Lua script that just does function query() return get_config() end

• html

  • html.escape_string() HTML-escapes a string. It uses the Go html.EscapeString

  • html.unescape_string() HTML-unescapes a string. It uses the Go html.UnescapeString

• github

If you install the Github app and then create new badges, you may choose to associate the badges with one of your Github repositories. When you do that, the github.* functions can be used to get information about the repository

• github.repo_name() returns the name of the associated Github repo

• github.owner_name() returns the Github username of the owner of the associated repo

• github.access_token() returns the installation access token that can be used to fetch information about the repo (if it is private). You can create a badge from one of the Github templates and then look at its Lua script, to get an example of how to use the access token.

• github.repo_id() returns the numerical ID of the associated Github repo

• github.owner_id() returns the numerical ID of the Github user that owns the associated repo

• github.installation_id() returns the numerical ID of the Github app installation

• misc

  • misc.int_format() takes an integer argument and returns it as a string, formatted like this:

    • misc.int_format(893)=893
    • misc.int_format(8930)=8.9k
    • misc.int_format(89300)=89k
    • misc.int_format(893000)=893k
    • misc.int_format(8930000)=8.9M
    • misc.int_format(89300000)=89M
    • etc.

  • misc.byte_format() takes an integer argument and returns it as a string representing an amount of data, like:

    • misc.byte_format(893)=893
    • misc.byte_format(8930)=8.7k (8930/1024)
    • misc.byte_format(89300)=87.2k
    • misc.byte_format(893000)=872k
    • misc.byte_format(8930000)=8.5M (8930000/1024/1024)
    • etc.

• color contains a bunch of color constants (strings)

  • color.brightgreen = "#4c1"
  • color.green = "97ca00"
  • color.yellowgreen = "#a4a61d"
  • color.yellow =`"#dfb317"
  • color.orange = "#fe7d37"
  • color.red = "#e05d44"
  • color.blue = "#007ec6"
  • color.lightgrey= "#9f9f9f"
  • color.success = "#4c1"
  • color.important = "#fe7d37"
  • color.critical = "#e05d44"
  • color.informational = "#007ec6"
  • color.inactive = "#9f9f9f"