Script
Rewrite HTTP

Rewriting HTTP

Users can modify HTTP requests and responses that pass through Stash using JavaScript scripts.

Configuration Format

http:
  script:
    - match: url-you-want-to-match
      name: your-fancy-script
      type: response # request / response
      require-body: true
      timeout: 20
      argument: ''
      binary-mode: false
      max-size: 1048576 # 1MB
 
script-providers:
  your-fancy-script:
    url: https://your-fancy-script.com/your-fancy-script.js
    interval: 86400

Parameters:

  • match: URL regular expression that the script matches.
  • type: Script type, can be request or response.
  • require-body: Whether the request body / response body is required. Processing the body in the script requires more memory space and should only be enabled when necessary.
  • timeout: Script execution timeout in seconds.
  • argument: Arguments passed to the script, type is string.
  • binary-mode: Binary mode, body will be passed to the script as a Uint8Array instead of a string.
  • max-size: Maximum size in bytes. Requests with a body larger than this size will not trigger the script.
💡
Binary mode is only supported in Stash iOS 2.0.2 and later versions.

Syntax and Interface

Basic Methods

  • $script.name: Script name.
  • $script.type: Script type, such as request, response, and tile.
  • $script.startTime: The time when the script started running.
  • $environment["stash-build"]: Stash Build number.
  • $environment["stash-version"]: Stash version number.
  • $environment.language: Stash runtime language.
  • $environment.system: Stash runtime system (iOS / macOS).
  • $argument: Running arguments.
  • $done(value): End script execution and release resources.
  • $notification.post(title, subtitle, body): Send iOS notifications.
  • console.log(value): Output logs. Script logs will be output to a separate file.
  • setTimeout(callback, delay): Delay execution of the callback function.

Persistent Storage

  • $persistentStore.write(value, key): Write to persistent storage.
  • $persistentStore.read(key): Read from persistent storage.

Request Object

  • $request.url: Request URL.
  • $request.method: Request method.
  • $request.headers: Request headers.
  • $request.body: Request body. Only available when requires-body: true. Depending on whether binary mode is enabled, it can be a string or Uint8Array.

Response Object

  • $request.url: Request URL.
  • $request.method: Request method.
  • $request.headers: Request headers.
  • $response.status: Response status code.
  • $response.headers: Response headers.
  • $response.body: Response body. Only available when requires-body: true. Depending on whether binary mode is enabled, it can be a string or Uint8Array.

HTTP Client

  • $httpClient.get(object)
  • $httpClient.put(object)
  • $httpClient.delete(object)
  • $httpClient.head(object)
  • $httpClient.options(object)
  • $httpClient.patch(object)

Example

$httpClient.get('http://www.example.com', (error, response, data) => {
  if (error) {
    console.log(error)
  } else {
    console.log(data)
  }
})
 
$httpClient.post(
  {
    url: 'http://www.example.com',
    headers: { headerKey: 'headerValue' },
    body: '{}', // can be object or string
  },
  (error, response, data) => {
    if (error) {
      console.log(error)
    } else {
      console.log(data)
    }
  }
)

$done(value)

⚠️

For all scripts, you must call the $done(value) method to release resources when ending.

For request-type scripts, calling $done(object) can rewrite the HTTP request. object can include the following fields:

  • url: Modify the URL of the request.
  • headers: Modify the headers of the request.
  • body: Modify the body of the request.
  • response: Replace the HTTP response and no longer actually send an HTTP request.

You can call $done() to interrupt the request, or $done({}) to not modify any content of the request.

For response-type scripts, calling $done(object) can rewrite the HTTP response. object can include the following fields:

  • status: Modify the status code of the response.
  • headers: Modify the headers of the response.
  • body: Modify the body of the response.

You can call $done() to interrupt the request, or $done({}) to not modify any content of the response.