Other SDK capabilities

Request URLs and query parameters

SDK 0.5.0 provides request-target helpers that avoid parsing request.url manually:

Property	Behavior
request.path	Gets the path without the query string. Setting it preserves the existing query string.
request.query	Gets the query string without ?. The setter accepts a value with or without a leading ?.
request.queryParams	Returns a cached URLSearchParams. Mutations update request.url. Reassigning request.url resets the cached value.

URLSearchParams stores repeated parameters in order. It provides get(), getAll(), has(), set(), append(), delete(), sort(), keys(), values(), entries(), forEach(), and toString(). Names and values use application/x-www-form-urlencoded encoding: + represents a space, valid %XX sequences are decoded, and toString() re-encodes the result.

Use request.path when matching a route that should ignore arbitrary query strings. Mutating request.queryParams before cache lookup can remove tracking parameters or normalize their order, which also changes the request target used by subsequent processing.

Cookies and redirects

request.cookies provides a read-only Cookies view of the request’s Cookie header. Cookie names are case-sensitive, values are returned without percent-decoding, and the first value wins when a name is repeated. The parsed view is cached while the Cookie header remains unchanged.

Use response.headers.append('set-cookie', value) to set cookies. Headers.getSetCookie() returns every Set-Cookie value separately instead of joining them.

Call request.respondRedirect(location, status) to return a redirect from a request handler, or use Response.redirect(location, status) when constructing a response. The status defaults to 302; supported redirect statuses are 301, 302, 303, 307, and 308.

Read the SDK 0.5.0 references for Request, URLSearchParams, and Cookies for the complete interfaces.

Request and response bodies

Request and response bodies are not buffered by default; body is null. To read a body in a phase, export that phase’s body marker alongside its entrypoint:

Phase	Body marker
Client request	client_request_body
Origin request	origin_request_body
Origin response	origin_response_body
Client response	client_response_body

Use text() for UTF-8 text, bytes() for raw bytes, and setBodyText() to replace a text body. Body buffering consumes memory; enable it only for phases that require it. Read Body access for the export pattern.

In response handlers, response.request provides a read-only request snapshot for the corresponding socket. It reflects the request before that socket’s request handlers changed it; its body is always null. Changes belong on the response itself. This feature requires compatible host runtime support.

Outbound requests

SDK fetch() makes a synchronous outbound HTTP request and returns a Response. It is available only in the client-request phase. Calling it from another phase reports phase_not_allowed.

Check response.isError() for transport failures, then check the HTTP status for application errors. A service returning an error status is different from a connection failure. Avoid forwarding credentials or incoming headers to an external destination unless the integration requires them.

The SDK documents a 2 s end-to-end timeout and limits of 10 MiB each for outbound request and response bodies. A concurrency limit also applies; its numeric value is not specified in the SDK. Read the fetch reference for supported options and error values.

HTML rewriting

HtmlRules describes changes using CSS selectors and actions such as replacing text, removing elements, or changing attributes. Call install() from a response handler. The host applies the rules while streaming HTML, so the worker does not need a response-body marker for this operation.

Rules apply to text/html and application/xhtml+xml responses. Rules registered in request phases are ignored. The SDK documents limits of 256 rules and 64 KiB of payload per call.

HTML insertion methods accept literal HTML. Escape untrusted values before insertion, or use setText() when adding text; it escapes the value. Read HTML rewriting for supported actions.

Rate limiting

RateLimit.register(name, rps) creates a named limiter, and RateLimit.check(name, key) checks whether a key is allowed. If the check returns false, worker code must return an appropriate response, such as HTTP status 429.

The first registration sets the rate. Repeating registration for the same name does not change it, even if the new rps differs. Changing a constant in source alone is therefore not a reliable way to reconfigure an existing limiter.

The SDK documents a maximum of 1,000 named limiters per site, names up to 64 UTF-8 bytes, and a positive requests-per-second value. Choose bucket keys from a bounded or verified identity scheme. Use request.path instead of request.url when the query string should not create separate buckets. An attacker-controlled query string or arbitrary header can create separate buckets and defeat the intended limit. Confirm the platform’s trusted client-identity source before using an address header.

Read RateLimit for the available methods. Rate limiting and KV share host facilities but are distinct SDK interfaces; a KV counter alone does not implement a timed rate limit.

Runtime configuration and cryptography

getenv(name) reads a host-provided environment variable and returns null if it is absent. Runtime variables avoid embedding secrets in source, but worker code must still prevent accidental disclosure through responses, logs, or outbound requests. Do not assume that the origin application’s environment variables are automatically available at the edge.

The SDK includes hashing, message authentication, constant-time comparison, random-value generation, and HS256 JSON Web Token (JWT) verification helpers. Consult Crypto before implementing authentication. jwtVerifyHs256() does not enforce the nbf or iat claims; application-specific claim and authorization checks remain the worker’s responsibility.

getRandomValues(array) fills a Uint8Array from host-provided operating-system entropy and returns the same array. A call can request at most 64 KiB. Use it for values whose unpredictability matters, including Content Security Policy nonces, tokens, session identifiers, and keys. Do not use Math.random() for those values. Its output is predictable and is not suitable for security controls.

AssemblyScript’s standard library also exposes a browser-style crypto.getRandomValues(). That binding is not provided at the edge, and importing it causes validation to fail. Import getRandomValues from @automattic/vip-edge-workers-sdk instead.