This document specifies the contract for running an Accelerator in the context of a client-server interaction, where the "http endpoint" is typically running inside a kubernetes cluster, alongside a web UI that allows triggering it.

Context of invocation

It is expected that the endpoint gets invoked by virtue of a user browsing one of the App Accelerator UI (directly or indirectly populated by bits of information found in the status of an Accelerator Custom Resource), filling some values for the available Accelerator options and hitting a big "Generate" button. The user then gets served the result of the processing as a zip file, or gets an error report. The Accelerator Engine Endpoint is provided with a pointer to the accelerator sources, typically coming from a git repository in tarball form as well as the set of values that the user chose for the Accelerator options.

Endpoint Contract

Request to run an accelerator is performed by POSTing to the /invocations endpoint with a JSON (Content-Type: application/json) formatted payload of the following form:

{
  "steps": [
    {
      "sources": {
        "archive": "http://<host>/gitrepository/default/podinfo/363a6a8fe6a7f13e05d34c163b0ef02a777da20a.tar.gz",
        "location": "file:///some/local/exploded/path",
        "subpath": "/my-sub-folder"
      }, 
      "options": {
        "optionOne": true,
        "optionTwo": "a string",
        "optionThree": ["an", "array", "of", "strings"],
        "optionFour": 9999
      }
    }
  ]
}

The following is a lightweight specification for that payload: - The payload MUST be a JSON object with a top-level steps property, itself being a one-element array of JSON objects. - that inner object MUST have both of the sources and options properties, even if empty. - The sources property is an object which MUST contain exactly one of the mutually exclusive properties archive or location. The former is typical in the context of regular use and points to a tarball of a repository contents, e.g. from the Flux git repository. That location MUST be accessible by the Accelerator Engine (host correctly qualified, etc). The only supported protocol is http(s). The latter is used for development purposes only and should not be considered a feature in the long run. It should point to a directory on the local filesystem. - Additionally, the sources object MAY contain a subpath property that should be considered as a sub-folder inside the contents of the sources to locate the root of the accelerator (i.e. the location of <ROOT> where the <ROOT>/accelerator.yaml resides). The default value is the empty string (i.e. the root of the tarball contents is to be considered the root of the accelerator). Any other value should be a forward-slash segmented string to be resolved relative to the actual tarball contents (with no leading slash). - The options property is a JSON object containing the values entered by the user, in accordance with the accelerator manifest: - All keys of that object MUST be camelCase words - Default values MUST do not need to be resolved prior to invocation (they will be resolved server-side) - Values must be resolved to their correct JSON type - Given the specification of the accelerator manifest, in practice, the only possible types for values are - JSON boolean for values whose dataType is boolean - JSON string for values whose dataType is string - JSON number for values whose dataType is number - JSON arrays of the above.

The response to an invocation is either - A byte stream, with http status 200 and Content-Type: application/zip in case of successful invocation, containing the resulting files encoded in a zip file. The zip file MAY have an additional top-level directory named after the projectName option (i.e. an accelerator index.html at the root of the accelerator is at <projectName>/index.html in the resulting zip file) - An error report, with http status 4xx or 5xx and Content-Type: application/json containing a description of what went wrong, with the following format:

{
  "title": "...",
  "status": 500,
  "detail": "...",
  "reportString": "...",
  "report": {...}
}

where - title is a short description of the error, - status has the same semantics as an http error code, - detail provides a longer description of the error, - reportString and report MAY both contain the execution log of the accelerator, if invocation went that far. The former is an ascii art rendering of it, while the latter is a JSON object with the same info.

check-circle-line exclamation-circle-line close-line
Scroll to top icon