Skip to content

Handlers

Optional output fields whose value is null are treated as absent before validation when the declared field is optional and nonnullable. This tolerance applies to outputs only, as in the handler schema profile. Required fields still must satisfy their schema, and an explicitly nullable field retains null. SDK static types may require authors to omit optional values; they do not remove the host’s output tolerance.

A handler is a named verb in a namespace. Every other part of the realm names it as namespace.verb.

handlers: {
incidents: {
namespace: "oncall",
description: "Unresolved incidents for a batch of services, a page at a time.",
input: {
type: "object",
properties: {
serviceIds: { type: "array", items: { type: "string" } },
cursor: { type: "string" },
impact: { type: "array", items: { type: "string" } },
status: { type: "array", items: { type: "string" } },
},
required: ["serviceIds"],
},
output: { type: "object" },
},
sweep: { namespace: "oncall", schedule: "0 */15 * * * *" },
},

The code lives in the entry file as exported functions named after the verbs. Optional SDK handler types give each one its input, output and context. The reference snippets use illustrative aliases from an ordinary author-side handler-types.ts; these are editor aids, not generated realm declarations. The complete composition examples instead write their handler signatures directly:

wasm/handlers.ts
import type { SweepHandler } from "../handler-types";
export const sweep: SweepHandler = async (_input, ctx) => {
ctx.log("sweeping status pages");
return {};
};
  • The verb must be a JavaScript identifier.
  • input and output are JSON Schema fragments. Left out, each is {"type": "object"} in the declaration. The host holds them to the handler schema profile: a bounded subset of JSON Schema, checked before binding, with input validated before the handler runs and output validated before the result is released. $ref, pattern, format and uniqueItems refuse the binding.
  • schedule is a six-field cron expression (second, minute, hour, day of month, month, day of week). A scheduled handler is called with {}, so its input may list no required field. A schedule may not sit on a handler with onType, and may not also be declared with defineSchedule("<verb>", ...) in a TypeScript entry.
  • onType turns the handler into a method on a graph label, and may not be blank. className names the class the sandbox instantiates for that method: it needs onType, may not be blank, and is refused when host is "wasm".
  • Declaring a handler grants it nothing. The owner approves each handler at admission.