http-response Script

An http-response script inspects and modifies an HTTP response before Surge delivers it to the client. Use it to rewrite response status, headers, or body in ways that the static rewrite features cannot express.

[Script]
modify-resp = type=http-response,pattern=^https?://www\.example\.com/test,script-path=test.js,requires-body=true,max-size=16384

Like other HTTP processing features, the script only sees requests that go through Surge's HTTP engine. HTTPS requests require MITM to be enabled for the host. See HTTP Processing Overview.

Trigger

The script runs when the response arrives for a request whose URL matches the pattern regex. At most one script runs per response: the first enabled http-response script in the profile whose pattern matches wins.

Parameters

These parameters apply to http-response (and http-request) script lines, in addition to the common script parameters. See the http-request page for the full descriptions.

pattern

Required, regular expression

The regex matched against the request URL.

requires-body

Optional, true/false, default false

Buffers the entire response body (decompressed) and passes it to the script, allowing the script to replace it. Without requires-body, the script runs as soon as the response header arrives and must not return a body in its result.

max-size

Optional, bytes, default 1 MB on iOS, 10 MB on macOS

The maximum body size buffered for the script. If the response body exceeds this limit, Surge falls back to passthrough mode: the script is skipped for this request and a note is attached to the request record. Use -1 for no limit.

binary-body-mode

Optional, true/false, default false

Passes the body as a Uint8Array instead of a UTF-8 decoded string, and accepts a Uint8Array back.

full-header-mode

Optional, true/false, default false

Delivers headers as an array of {field, value} objects instead of a plain object, preserving duplicate fields such as Set-Cookie.

Scripting with requires-body requires Surge to load the entire response body into memory. On iOS, the system limits the memory a Network Extension may use, so a huge response body can cause problems. Keep patterns narrow and only enable body access for the URLs that need it.

Input

The script receives both the request and the response:

Field Type Description
$request.url String Request URL.
$request.method String Request HTTP method.
$request.headers Object Request HTTP headers.
$request.id String A unique ID for the request, stable between the http-request script and the paired http-response script.
$response.status Number Response HTTP status code.
$response.headers Object Response HTTP headers. An array of {field, value} objects in full-header-mode.
$response.body String or Uint8Array Response HTTP body, decoded to a string with UTF-8 unless binary-body-mode is set. Only present when requires-body=true and the body is not empty.
$response.trailers Object The response's trailer section, in the format of $response.headers. Only present when requires-body=true and the response ended with one. iOS 6.0.0+ Mac 6.12.0+

Result

The script must finish by calling $done() with an object. The object may contain:

  • status<Number>: Replace the status code.
  • headers<Object or Array>: Replace all response headers.
  • body<String or Uint8Array>: Replace the response body. Only works when requires-body=true. A script running without requires-body must not return a body; doing so aborts the connection.
  • trailers<Object or Array>: Replace the trailer section. Only works when requires-body=true and the client speaks HTTP/2. An empty object removes the trailer section. iOS 6.0.0+ Mac 6.12.0+
  • abort<Boolean>: If true, Surge aborts the connection instead of delivering the response.

Calling $done({}) — or $done() with no argument — delivers the response untouched. As with headers, leaving trailers out of the result keeps the trailer section the server sent.

Trailer Section

A chunked HTTP/1.1 response or an HTTP/2 response may end with a trailer section: header fields that follow the body. gRPC uses it for the status of a call (grpc-status, grpc-message), so a script on a gRPC endpoint must leave those fields intact. Surge passes the section on by itself; a script only needs trailers to read or change it. The request detail view of the Dashboard and of Surge iOS shows the section under Response Trailers.

Three limits apply:

  • Reading needs requires-body. The trailer section arrives after the body, so a script that runs as soon as the response header is in has already finished before the fields exist. Without requires-body there is no $response.trailers, and a trailers in the result is ignored with a note on the request record.
  • Writing needs an HTTP/2 client. When a script replaces the body, Surge re-frames the response with a Content-Length, which leaves nowhere to put a trailer section for an HTTP/1.1 client. An HTTP/2 client receives it as a trailer HEADERS frame. The trailer fields are recorded either way, so the request detail still shows them.
  • Duplicate fields are lost. Like headers, the object has one entry per field name, so a section with the same field twice reaches the script once, and the order of the fields written back is not preserved. gRPC trailer fields are unique, so this rarely matters. full-header-mode delivers trailers as an array of {field, value} objects, as it does for headers.

Fields that may not appear in a trailer section (RFC 9110 6.5.1) — message framing such as Content-Length and Transfer-Encoding, routing, authentication, and content metadata such as Content-Type and Content-Encoding — are dropped, whether they come from the server or from a script. At most 32 fields are passed on.

Example

let headers = $response.headers;
headers['X-Modified-By'] = 'Surge';

$done({headers});

Reading the status of a gRPC call out of the trailer section, and answering with a different one. The script line needs requires-body=true:

let trailers = $response.trailers || {};
console.log('grpc-status: ' + trailers['grpc-status']);

$done({trailers: {'grpc-status': '0'}});

results matching ""

    No results matching ""