A handler is a source file whose first line is a shebang. In a site it owns the route derived from its path; by itself it becomes a function that owns every path. The sites guide defines path routing; this page defines handler metadata and the request contract.

#!/usr/bin/env bash
# kedge: methods=GET,POST memory=128MiB
printf 'Content-Type: application/json\r\n\r\n'
sqlite3 /shared.db \
  "SELECT json_object('now', datetime('now'))"

inline properties

Handler comments use the same bare configuration properties as the rest of Kedge. The compact form stays on one comment:

# kedge: route=/api/time methods=GET,POST apt=imagemagick memory=128MiB

For lists or longer declarations, use the structured form:

# /// kedge
# route = "/api/time"
# methods = ["GET", "POST"]
# apt = ["imagemagick"]
# memory = "128MiB"
# ///

The structured block changes value syntax only; it does not define another set of keys. The same central registry validates handler and shared properties; unknown or inapplicable properties fail the deploy.

The shebang chooses the interpreter; the extension is only a fallback hint. The warm runtimes include bash/sh, the tree's language, and common tools such as sqlite3, jq, and curl. Extra packages or mixed languages trigger a small image build.

request and response

Handlers use a CGI-shaped contract. The request arrives as environment variables (REQUEST_METHOD, SCRIPT_NAME, PATH_INFO, QUERY_STRING, CONTENT_TYPE, HTTP_*) and the body arrives on stdin.

Write optional headers, a blank line, then the body:

Status: 201
Content-Type: application/json

{"ok":true}

With no header block, stdout is returned as text/plain. A non-zero exit is a 500. Python, Ruby, JavaScript, and TypeScript may instead define handler(req) and return a string or {status, headers, body}.

state and instance identity

Handlers can read and write /shared.db and /shared/ like any service. Four trusted variables describe the instance serving the request: KEDGE_DC, KEDGE_INSTANCE, KEDGE_RESTORE, and KEDGE_RESTORE_MS. Client-supplied X-Kedge-* headers are stripped before a handler sees them.

The response reports the same restore facts to the client. Instant sandboxes & scale-out defines those values.

Each handler request runs in a hardware-isolated VM. Runtime & scaling covers snapshots and instance lifecycle.