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 berequest
orresponse
.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 isstring
.binary-mode
: Binary mode,body
will be passed to the script as aUint8Array
instead of astring
.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 asrequest
,response
, andtile
.$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 whenrequires-body: true
. Depending on whether binary mode is enabled, it can be astring
orUint8Array
.
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 whenrequires-body: true
. Depending on whether binary mode is enabled, it can be astring
orUint8Array
.
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.