Handler API

Site code is a JavaScript ES module. This page is the reference for the handler contract and the Web-style globals available to it. The capabilities on ctx (database, storage, secrets, mail, network) are in Context, the optional modules in SDK modules. Editor types are in sdk/microhost.d.ts.

Status. The SDK surface is shared by all three engines (Wasm, native, Linux worker). The cross-engine conformance suite (crates/engine-api/conformance, 48 scenario files) covers the handler contract, Request, Response, status and redirect rules, header rules, URL, TextEncoder, crypto.getRandomValues, import rules, limits and capability absence. It does not exercise microhost/sql, microhost/db or microhost/session, and not fetch or mail. microhost serve --dev serves static files only; handlers answer 501 there.

The handler

export default async function handle(request, ctx) {
  return Response.json({ method: request.method, path: new URL(request.url).pathname });
}

• The module's default export must be a function. Declare it async (or return a promise). It must resolve to a Response.
• Resolving to anything else (a string, a plain object, undefined) is an invalid response: HTTP 502.
• A thrown exception or rejected promise is HTTP 500. The message and stack never reach the visitor.
• The engine creates a fresh runtime for each execution. Module-level variables are not shared between requests.
• Await all work before returning. There is no waitUntil, no background job, no timers.
• A timeout terminates execution without running catch or finally.

Request

request is created by the host. Request cannot be constructed by site code.

Bodies are fully buffered and limited to 1 MiB by default (oversize requests are answered 413 by the edge and never reach your code). Methods without a body give an empty string.

Headers your code sees: the edge removes hop-by-hop headers, content-length, x-forwarded-*, forwarded and x-real-ip. There is no way to read the client IP. host and cookie are present. Header values that are not plain visible ASCII are dropped.

Request has no path or query members. Use new URL(request.url) (pathname, search).

Response

new Response(body?, { status?, headers? })
Response.json(value, init?)
Response.html(html, init?)
Response.redirect(url, status)

• body is a string, a Uint8Array, null or omitted. Any other type throws TypeError.
• status defaults to 200 and must be an integer from 200 to 599; otherwise RangeError.
• A string body gets content-type: text/plain;charset=UTF-8 unless you set one. A Uint8Array body gets no content type.
• Response.json serializes with JSON.stringify and always sets content-type: application/json (it throws TypeError for a value that cannot be serialized, such as undefined).
• Response.html always sets content-type: text/html; charset=utf-8 and x-content-type-options: nosniff. It does not sanitize anything: escape untrusted text yourself.
• Response.redirect(url, status) sets Location. url may be a string or URL. status is required and must be 301, 302, 303, 307 or 308 (otherwise RangeError).
• The only readable member is response.headers, a mutable Headers. There are no status, body, ok or body-reader members on a site Response.

Host-side response checks (a violation is an invalid response, HTTP 502): header names must be legal tokens, values must not contain CR or LF, a Set-Cookie value is at most 4096 bytes, and the body must fit the response limit (4 MiB by default; above it the execution fails with HTTP 500). The host drops hop-by-hop headers (connection, keep-alive, proxy-*, te, trailer, transfer-encoding, upgrade) and content-length and recomputes framing.

Headers

new Headers(init?) accepts another Headers, an array of [name, value] pairs, or a plain object. Methods: get, has, set, append, delete. Names are case-insensitive. Values are converted with String().

• append on an existing header joins values with ", ", except Set-Cookie.
• Set-Cookie is kept as separate values. Each append("Set-Cookie", value) becomes its own header on the wire. get("set-cookie") returns the values joined with ", " for convenience only.
• set replaces all values of a name.
• There is no iteration (entries, forEach, keys) and no getSetCookie.

const response = Response.redirect("/account", 303);
response.headers.append("Set-Cookie", "a=1; Path=/; Secure; HttpOnly");
response.headers.append("Set-Cookie", "b=2; Path=/; Secure; HttpOnly");

URL

new URL(input, base?) parses an absolute URL, or a relative one against base. It throws TypeError for an invalid URL. Read-only properties: href, origin, protocol, host, hostname, pathname, search, hash; toString() returns href. There is no URLSearchParams and no searchParams: search is the raw query string. If you parse queries yourself, decide how to treat repeated keys, +, and malformed percent escapes.

Text and bytes

• new TextEncoder().encode(string?) returns a Uint8Array (UTF-8).
• new TextDecoder().decode(bytes?) takes a Uint8Array or ArrayBuffer. UTF-8 only; no options.

Randomness and time

• crypto.getRandomValues(typedArray) fills Uint8Array, Uint16Array, Uint32Array, Int8Array, Int16Array or Int32Array, at most 65,536 bytes per call (RangeError above that, TypeError for other types). It uses host randomness.
• There is no crypto.subtle and no crypto.randomUUID. microhost/db exports id(), which builds a UUID v4 from getRandomValues.
• Math.random() on the Wasm engine is served from host randomness. Do not rely on it for secrets on any engine; use getRandomValues.
• Date works with the host clock. microhost/db exports now() (an ISO UTC string). Database-side expiry (sessions) uses the database clock instead.

Console

console.log, info, warn, error write to the site log, never to the visitor. Strings print as is, Error objects as Name: message, other objects as JSON, arguments joined by spaces. Output is capped at 64 KiB per execution; later lines are dropped. Values your code obtained from ctx.env.get are redacted from console output. Do not log request bodies or credentials.

Modules

Handlers are ES modules with static imports:

import { escapeHtml } from "../lib/html.js";   // relative, ends in .js, stays in the release
import { users } from "microhost/db";          // reserved SDK module

Rules (details in Site layout): relative specifiers only (./ or ../), they must end in .js, and they must stay inside the release outside public/. Importing a public/ file fails with HTTP 403. Dynamic import(), eval and new Function are not available (a dynamic import fails with HTTP 500). Bare specifiers other than the four reserved SDK names fail. At most 256 modules and 8 MiB of module source per execution.

Not available

These are absent. Using them gives ReferenceError or undefined; do not polyfill them.

• Node and browser objects: process, Buffer, require, module, global, window, document, localStorage.
• Timers: setTimeout, setInterval, setImmediate.
• Network primitives other than fetch: XMLHttpRequest, WebSocket, EventSource, raw sockets.
• AbortController, AbortSignal.
• Streams: ReadableStream, WritableStream, streaming bodies.
• URLSearchParams, FormData, Blob, File; no automatic multipart or form parsing (send JSON and use request.json(), or parse text() yourself).
• crypto.subtle, crypto.randomUUID.
• eval, new Function and every other source-string evaluator; dynamic import().
• A built-in cookie parser, template engine or authentication layer. microhost/session provides sessions explicitly.
• Interactive database transactions across calls (use ctx.db.transaction).

Errors thrown by host calls

Host calls (ctx.db, ctx.storage, ctx.env, ctx.mail, fetch) reject with an Error whose code is one of CAPABILITY_DENIED, QUOTA_EXCEEDED, INVALID_INPUT (a TypeError), HOST_UNAVAILABLE, HOST_INTERNAL. Messages are generic. SDK modules add their own lowercase codes. Full tables are in Limits and errors.