Handlers

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. The generated types (--types) give each one its input, output and context:

wasm/handlers.ts

import type { SweepHandler } from "../.embabel/realm.d.ts";

export const sweep: SweepHandler = async (_input, ctx) => {
  ctx.log("sweeping status pages");
  return {};
};

• The verb must be a JavaScript identifier. Two verbs whose generated aliases collide (FooHandler) are refused.
• input and output are JSON Schema fragments. Left out, each is {"type": "object"} in the manifest. 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.
• The generated types name each verb three times: <Verb>Input, <Verb>Output and <Verb>Handler, where <Verb> is the verb with its first letter upper-cased. An input schema with no properties types as Record<string, never>, and an output schema with no properties as unknown. <Verb>Handler is (input, ctx: HandlerContext) => Promise<Output>.
• 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.