@pylonsync/functions 0.19.1 → 0.21.0

package/src/runtime.ts

@@ -33,6 +33,9 @@ import type {
   LlmStreamEvent,
   Rooms,
   Workflows,
+  WorkflowRunSummary,
+  Audit,
+  AuditEntry,
   Connections,
   Domains,
   TenantDomainResult,
@@ -47,6 +50,7 @@ import type {
 } from "./types";
 import { normalizeAuthClaims } from "./auth";
 import { makeRequireMember } from "./member";
+import { response } from "./response";
 import { isDevMode } from "./ssr-runtime";
 import { validateArgs } from "./validators";
 import { serverBundle } from "./server-bundle";
@@ -840,10 +844,10 @@ function buildScheduler(callId: string): Scheduler {
       return r.id || "";
     },
     async cancel(scheduleId) {
-      await rpc(callId, {
+      return (await rpc(callId, {
         type: "cancel_schedule",
         schedule_id: scheduleId,
-      });
+      })) as { cancelled: boolean };
     },
   };
 }
@@ -985,15 +989,47 @@ export function buildRooms(callId: string): Rooms {
  * takes it from there, so `start` returns the instance id immediately.
  * Uses the queued call_id-keyed `rpc` (the reply carries no op_id).
  */
+/** Build `ctx.audit` — round-trips `audit_op` frames to the host. */
+export function buildAudit(callId: string): Audit {
+  return {
+    async log(event) {
+      return (await rpc(callId, {
+        type: "audit_op",
+        op: "log",
+        action: event.action,
+        entity: event.entity ?? null,
+        entity_id: event.entityId ?? null,
+        subject: event.subject ?? null,
+        meta: event.meta ?? null,
+      })) as { id: string };
+    },
+    async list(filter) {
+      return (await rpc(callId, {
+        type: "audit_op",
+        op: "list",
+        action: filter?.action ?? null,
+        entity: filter?.entity ?? null,
+        entity_id: filter?.entityId ?? null,
+        actor: filter?.actor ?? null,
+        tenant: filter?.tenant ?? null,
+        before: filter?.before ?? null,
+        before_id: filter?.beforeId ?? null,
+        limit: filter?.limit ?? null,
+      })) as AuditEntry[];
+    },
+  };
+}
+
 export function buildWorkflows(callId: string): Workflows {
   return {
-    async start(name: string, input?: unknown) {
+    async start(name: string, input?: unknown, opts?: { key?: string }) {
       return (await rpc(callId, {
         type: "workflow_op",
         op: "start",
         name,
         input: input ?? null,
-      })) as { id: string };
+        key: opts?.key ?? null,
+      })) as { id: string; created: boolean };
     },
     async sendEvent(workflowId: string, event: string, data?: unknown) {
       return (await rpc(callId, {
@@ -1002,7 +1038,32 @@ export function buildWorkflows(callId: string): Workflows {
         workflow_id: workflowId,
         event,
         data: data ?? null,
-      })) as { delivered: boolean };
+      })) as { delivered: boolean; buffered: boolean };
+    },
+    async cancel(workflowId: string, opts?: { reason?: string }) {
+      return (await rpc(callId, {
+        type: "workflow_op",
+        op: "cancel",
+        workflow_id: workflowId,
+        reason: opts?.reason ?? null,
+      })) as { cancelled: boolean };
+    },
+    async get(workflowId: string) {
+      return (await rpc(callId, {
+        type: "workflow_op",
+        op: "get",
+        workflow_id: workflowId,
+      })) as WorkflowRunSummary | null;
+    },
+    async list(filter) {
+      return (await rpc(callId, {
+        type: "workflow_op",
+        op: "list",
+        name: filter?.name ?? null,
+        key: filter?.key ?? null,
+        status: filter?.status ?? null,
+        limit: filter?.limit ?? null,
+      })) as WorkflowRunSummary[];
     },
   };
 }
@@ -1166,6 +1227,7 @@ function buildActionCtx(
     normalizedRequest = {
       method: String(r.method ?? ""),
       path: String(r.path ?? ""),
+      url: String(r.url ?? ""),
       headers: (r.headers as Record<string, string>) ?? {},
       rawBody: String(r.raw_body ?? r.rawBody ?? ""),
     };
@@ -1179,6 +1241,7 @@ function buildActionCtx(
     rooms,
     connections,
     workflows: buildWorkflows(callId),
+    audit: buildAudit(callId),
     domains: buildDomains(),
     env: process.env as Record<string, string>,
     async runQuery(fnName, args) {
@@ -1214,6 +1277,7 @@ function buildActionCtx(
       }) as Promise<any[]>,
     ),
     request: normalizedRequest,
+    response,
   };
 }
 
@@ -1372,6 +1436,7 @@ async function handleCall(msg: CallMessage): Promise<void> {
         rooms,
         connections,
         workflows: buildWorkflows(msg.call_id),
+        audit: buildAudit(msg.call_id),
         error(code, message) {
           const err = new Error(message);
           (err as any).code = code;

package/src/ssr-runtime.test.ts

@@ -20,6 +20,7 @@ import {
   makeReadTrackingProxy,
   makeRevocableReadTrackingProxy,
   jsonClone,
+  isLoopbackHost,
 } from "./ssr-runtime";
 
 describe("resolveOrigin — Host-header allowlist (cache-poisoning fence)", () => {
@@ -904,3 +905,27 @@ describe("script-escaping + secure cookies", () => {
     }
   });
 });
+
+describe("isLoopbackHost — exact loopback match", () => {
+  test("accepts loopback names and addresses with an optional port", () => {
+    for (const h of ["localhost", "localhost:4321", "127.0.0.1", "127.1.2.3:80", "0.0.0.0:4321", "::1", "[::1]", "[::1]:4321"]) {
+      expect(isLoopbackHost(h)).toBe(true);
+    }
+  });
+
+  test("rejects hosts that only start like loopback", () => {
+    for (const h of ["localhost.attacker.io", "127.attacker.test", "0.0.0.0.attacker.net", "localhostx", "[::1].evil.com", "localhost:80x", "128.0.0.1", "127.0.0.256", "127.000.000.001", "0:0:0:0:0:0:0:1", "localhost.", ""]) {
+      expect(isLoopbackHost(h)).toBe(false);
+    }
+  });
+
+  test("a look-alike Host is not trusted for the origin or a redirect", () => {
+    expect(
+      resolveOrigin({ host: "localhost.attacker.io", publicUrl: "https://app.example.com" }),
+    ).toBe("https://app.example.com");
+    expect(
+      isSafeRedirect("https://localhost.attacker.io/phish", { publicUrl: "https://app.example.com" }),
+    ).toBe(false);
+    expect(isSafeRedirect("http://localhost:4321/ok", {})).toBe(true);
+  });
+});

package/src/ssr-runtime.ts

@@ -1092,7 +1092,39 @@ function readSocialImageMeta(relPath: string): {
   return { type, width, height, v };
 }
 
-const LOOPBACK_HOST = /^(localhost|127\.|\[?::1|0\.0\.0\.0)/;
+/** Loopback host? `host` is a lowercase authority (`host[:port]`,
+ *  `[ipv6]:port`). True for exactly `localhost`, dotted 127.0.0.0/8
+ *  without leading zeros, `::1`, or `0.0.0.0`, with an optional numeric
+ *  port. The match is exact, so
+ *  `localhost.example.com` is not loopback. Mirrors `is_loopback_host` in
+ *  crates/router/src/public_url.rs. Exported for tests. */
+export function isLoopbackHost(host: string): boolean {
+  let name: string;
+  const bracketed = /^\[([^\]]*)\](?::(\d{1,5}))?$/.exec(host);
+  if (bracketed) {
+    name = bracketed[1];
+  } else if (host.startsWith("[")) {
+    return false;
+  } else {
+    const colons = host.split(":").length - 1;
+    if (colons === 1) {
+      const [h, port] = host.split(":");
+      if (!/^\d{1,5}$/.test(port)) return false;
+      name = h;
+    } else {
+      name = host;
+    }
+  }
+  if (name === "localhost" || name === "::1" || name === "0.0.0.0") return true;
+  // Dotted IPv4 without leading zeros (matches Rust's Ipv4Addr parser).
+  const octet = "(0|[1-9]\\d{0,2})";
+  const v4 = new RegExp(`^${octet}\\.${octet}\\.${octet}\\.${octet}$`).exec(name);
+  if (v4) {
+    const octets = v4.slice(1).map(Number);
+    return octets.every((o) => o <= 255) && octets[0] === 127;
+  }
+  return false;
+}
 
 /** Normalize a bare host or a full URL down to a lowercase `host` (host:port).
  *  Returns "" for unparseable input. */
@@ -1135,7 +1167,7 @@ export function resolveOrigin(opts: {
     add(opts.publicUrl || "");
     add(opts.canonicalHost || "");
     for (const x of (opts.trustedHostsCsv || "").split(",")) add(x);
-    const isLoopback = LOOPBACK_HOST.test(host);
+    const isLoopback = isLoopbackHost(host);
     if (isLoopback || allow.has(host)) {
       // Off-loopback (prod) we ALWAYS use https and never honor the request's
       // X-Forwarded-Proto. The SSR cache is keyed only by host (not proto), so
@@ -1201,7 +1233,7 @@ export function isSafeRedirect(
   }
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
   const host = parsed.host.toLowerCase();
-  if (LOOPBACK_HOST.test(host)) return true;
+  if (isLoopbackHost(host)) return true;
   const allow = new Set<string>();
   const add = (v: string) => {
     const h = hostOf(v);

package/src/types.ts

@@ -1,6 +1,7 @@
 /**
  * Type definitions for the function system.
  */
+import type { RawResponse, RawResponseInit } from "./response";
 
 // ---------------------------------------------------------------------------
 // Auth
@@ -370,8 +371,21 @@ export interface Scheduler {
     args: Record<string, unknown>
   ): Promise<string>;
 
-  /** Cancel a previously scheduled function. */
-  cancel(scheduleId: string): Promise<void>;
+  /**
+   * Cancel a scheduled function that has not started. Pass the id
+   * `runAfter` or `runAt` returned.
+   *
+   * Resolves `{ cancelled: true }` when the job will not run, and
+   * `{ cancelled: false }` when the id is unknown or the job already
+   * started or finished (a running job is not interrupted). Rejects with
+   * `SCHEDULE_CANCEL_FAILED` when the cancel could not be saved; the job
+   * then still runs.
+   *
+   * Inside a mutation, the cancel commits or rolls back with the
+   * mutation: if the mutation throws, the job stays scheduled. From an
+   * action, it takes effect at once.
+   */
+  cancel(scheduleId: string): Promise<{ cancelled: boolean }>;
 }
 
 /**
@@ -604,18 +618,162 @@ export interface Workflows {
   /**
    * Start a workflow instance by name. Returns immediately with the
    * instance id — the engine's background driver executes the steps.
+   *
+   * With `key` (for example a lead id), at most one non-terminal run
+   * exists per workflow name and key. If one exists, no new run starts
+   * and its id is returned with `created: false`. A finished run frees
+   * the key.
    */
-  start(name: string, input?: unknown): Promise<{ id: string }>;
+  start(
+    name: string,
+    input?: unknown,
+    opts?: { key?: string },
+  ): Promise<{ id: string; created: boolean }>;
   /**
-   * Deliver an event to an instance paused on
-   * `wf.waitForEvent(event)`. Rejects when the instance isn't waiting
-   * for that event.
+   * Send an event to a run. If the run is waiting for it
+   * (`wf.waitForEvent(event)`), the run resumes and `delivered` is true.
+   * Otherwise the event is buffered (`buffered: true`) and the run's next
+   * `waitForEvent(event)` consumes it. Rejects when the run has finished
+   * or already holds 100 buffered events. Events sent without data
+   * arrive as `{}`.
    */
   sendEvent(
     workflowId: string,
     event: string,
     data?: unknown,
-  ): Promise<{ delivered: boolean }>;
+  ): Promise<{ delivered: boolean; buffered: boolean }>;
+  /**
+   * Cancel a run. No further step runs. A step already in progress may
+   * finish, but its result is discarded. Resolves `cancelled: false` when
+   * the run had already finished. Rejects for an unknown id.
+   */
+  cancel(
+    workflowId: string,
+    opts?: { reason?: string },
+  ): Promise<{ cancelled: boolean }>;
+  /** Read one run, or null if the id is unknown. */
+  get(workflowId: string): Promise<WorkflowRunSummary | null>;
+  /**
+   * List runs, newest first. `status: "active"` matches every
+   * non-terminal status. `limit` defaults to 100 (max 1000).
+   *
+   * ```ts
+   * // Seller texted STOP: end every cadence for the lead.
+   * const runs = await ctx.workflows.list({ key: leadId, status: "active" });
+   * for (const run of runs) {
+   *   await ctx.workflows.cancel(run.id, { reason: "STOP" });
+   * }
+   * ```
+   */
+  list(filter?: {
+    name?: string;
+    key?: string;
+    status?: WorkflowRunStatus | "active";
+    limit?: number;
+  }): Promise<WorkflowRunSummary[]>;
+}
+
+/**
+ * The application audit log (`ctx.audit` on mutations and actions).
+ * Append-only, stored with the auth audit events.
+ */
+export interface AuditLog {
+  /**
+   * Record an event. The actor and tenant come from the caller's session.
+   * `action` is a short dotted name (`lead.export`, `script.update`) and
+   * is stored as `app.<action>`. `meta` values are stored as strings
+   * (non-strings as JSON text); keep secrets out of it.
+   *
+   * Inside a mutation the event is written after the mutation commits and
+   * dropped if it rolls back. Rejects with `AUDIT_WRITE_FAILED` when an
+   * action's event could not be stored.
+   */
+  log(event: {
+    action: string;
+    entity?: string;
+    entityId?: string;
+    /** The user the event is about, when not the actor. */
+    subject?: string;
+    meta?: Record<string, unknown>;
+  }): Promise<{ id: string }>;
+}
+
+/**
+ * `ctx.audit` on actions: {@link AuditLog.log} plus reads. Mutations get
+ * only `log`: in a Postgres mutation the transaction holds a connection,
+ * and a read would need a second.
+ */
+export interface Audit extends AuditLog {
+  /**
+   * Read events, newest first. A caller with a tenant reads that tenant's
+   * events; a caller without one reads only events it performed. Admin
+   * callers may pass `tenant` or read all tenants. `action` matches
+   * `lead.export` as `app.lead.export`; framework actions
+   * (`entity.update`, `retention.delete`) and auth action names match as
+   * given. `limit` defaults to 100 (max 1000). To page,
+   * pass `beforeId` set to the last event's `id`. `before` (unix seconds)
+   * limits by time.
+   */
+  list(filter?: {
+    entity?: string;
+    entityId?: string;
+    actor?: string;
+    action?: string;
+    tenant?: string;
+    before?: number;
+    beforeId?: string;
+    limit?: number;
+  }): Promise<AuditEntry[]>;
+}
+
+export interface AuditEntry {
+  id: string;
+  /** Unix seconds. */
+  createdAt: number;
+  /** `app.<action>`, `entity.insert|update|delete`, `retention.delete`, or an auth action. */
+  action: string;
+  actor: string | null;
+  subject: string | null;
+  tenant: string | null;
+  entity: string | null;
+  entityId: string | null;
+  ip: string | null;
+  success: boolean;
+  reason: string | null;
+  /** For `entity.*` events, `fields` lists the changed field names. */
+  meta: Record<string, string>;
+}
+
+export type WorkflowRunStatus =
+  | "pending"
+  | "running"
+  | "sleeping"
+  | "waiting"
+  | "completed"
+  | "failed"
+  | "cancelled";
+
+/** A workflow run without its step history. Times are unix seconds. */
+export interface WorkflowRunSummary {
+  id: string;
+  name: string;
+  key: string | null;
+  status: WorkflowRunStatus;
+  input: unknown;
+  output: unknown;
+  error: string | null;
+  cancelReason: string | null;
+  /** Event name the run is waiting for, when `status` is "waiting". */
+  waitingFor: string | null;
+  /** When the current wait times out, if it has a timeout. */
+  waitDeadline: number | null;
+  /** When the current sleep ends. */
+  wakeAt: number | null;
+  /** Events sent but not yet consumed by a `waitForEvent`. */
+  bufferedEvents: number;
+  createdAt: number | null;
+  startedAt: number | null;
+  completedAt: number | null;
 }
 
 export interface LlmMessage {
@@ -1029,6 +1187,8 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
   connections: Connections;
   /** Durable workflows: start / deliver events — see {@link Workflows}. */
   workflows: Workflows;
+  /** Application audit log (write only in mutations) — see {@link AuditLog}. */
+  audit: AuditLog;
   /** Signed file-download URLs — see {@link Files}. */
   files: Files;
   /** Shard tickets, reads, and inputs after the commit — see {@link Shards}. */
@@ -1063,8 +1223,18 @@ export interface TenantDomainResult {
   status: string;
   /** Whether the hostname + TLS certificate are both active. */
   active?: boolean;
-  /** The single CNAME the customer points their hostname at. */
-  cnameTarget: string;
+  /**
+   * True for an apex domain (`acme.com`). An apex cannot be a CNAME, so the
+   * customer adds A/AAAA records pointing at the app instead.
+   */
+  apex?: boolean;
+  /**
+   * Every DNS record the customer adds, for both kinds of domain: a CNAME
+   * (subdomain) or A/AAAA (apex), plus ownership and certificate records.
+   */
+  records?: TenantDomainRecord[];
+  /** The CNAME the customer points a subdomain at; null for an apex. */
+  cnameTarget: string | null;
   /** TXT record proving domain ownership before DNS cutover (or null). */
   ownership: TenantDomainDns | null;
   /** TXT records that issue the DV certificate. */
@@ -1073,6 +1243,14 @@ export interface TenantDomainResult {
   errors: string[];
 }
 
+export interface TenantDomainRecord {
+  type: "A" | "AAAA" | "CNAME" | "TXT";
+  name: string;
+  value: string;
+  /** What the record is for, to show the customer. */
+  purpose: string;
+}
+
 /**
  * Platform domains: attach / register / detach custom domains for your app's
  * OWN end-customers, so each tenant can reach your app on their own hostname.
@@ -1199,6 +1377,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   connections: Connections;
   /** Durable workflows: start / deliver events — see {@link Workflows}. */
   workflows: Workflows;
+  /** Application audit log — see {@link Audit}. */
+  audit: Audit;
   /** Attach / register custom domains for your app's OWN end-customers
    *  (platform domains) — see {@link Domains}. Cloud-only. */
   domains: Domains;
@@ -1249,13 +1429,35 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
    * ```
    */
   request?: RequestInfo;
+  /**
+   * Build a raw HTTP response. When an action called through
+   * `/api/webhooks/<name>` returns it, the route sends this status,
+   * content type, headers, and body instead of JSON. Other routes return
+   * it as ordinary JSON data. Throws on an invalid status or header.
+   *
+   * ```ts
+   * // Twilio expects TwiML, not JSON.
+   * return ctx.response({ contentType: "text/xml", body: "<Response/>" });
+   * ```
+   */
+  response(init?: RawResponseInit): RawResponse;
 }
 
 /** HTTP request metadata available on an action's ctx when invoked via an
  *  HTTP route binding. Header names are lowercased. */
 export interface RequestInfo {
   method: string;
+  /** Request path with the query string, as received. */
   path: string;
+  /**
+   * The full URL the client requested: scheme, host, path, and query.
+   * Behind a proxy, the host comes from `X-Forwarded-Host` or `Host`
+   * only when it is trusted (loopback, the `PYLON_PUBLIC_URL` host,
+   * `PYLON_CANONICAL_HOST`, a `PYLON_TRUSTED_HOSTS` entry, or one of the
+   * app's domains); otherwise the `PYLON_PUBLIC_URL` origin is used. Use
+   * it to verify providers that sign the whole URL, such as Twilio.
+   */
+  url: string;
   headers: Record<string, string>;
   rawBody: string;
 }

package/src/workflows.test.ts

@@ -177,18 +177,85 @@ describe("executeWorkflowSlice", () => {
     expect((res as { error: string }).error).toContain("duplicate step name");
   });
 
-  test("duplicate waitForEvent names fail loudly too", async () => {
-    const dup = workflow("dup-ev", async (wf) => {
-      await wf.waitForEvent("go");
-      await wf.waitForEvent("go");
+  test("the same event name can be awaited repeatedly; each wait replays in order", async () => {
+    const cadence = workflow("cadence", async (wf) => {
+      const first = await wf.waitForEvent<{ n: number }>("reply");
+      const second = await wf.waitForEvent<{ n: number }>("reply");
+      return { first: first.n, second: second.n };
     });
+    const paused = await executeWorkflowSlice(
+      cadence,
+      req(1, [done("event:reply", { n: 1 })]),
+      ctx,
+    );
+    expect(paused).toEqual({ action: "wait_event", event: "reply" });
     const res = await executeWorkflowSlice(
-      dup,
-      req(1, [done("event:go", { n: 1 })]),
+      cadence,
+      req(2, [done("event:reply", { n: 1 }), done("event:reply", { n: 2 })]),
       ctx,
     );
+    expect(res).toEqual({ action: "complete", output: { first: 1, second: 2 } });
+  });
+
+  test("waitForEvent with a timeout sends the timeout and resolves null on timeout", async () => {
+    const lead = workflow("lead", async (wf) => {
+      await wf.step("send-sms", () => "sent");
+      const reply = await wf.waitForEvent("seller_replied", { timeout: "60s" });
+      if (reply === null) {
+        await wf.step("call", () => "called");
+        return "called";
+      }
+      return "replied";
+    });
+    const paused = await executeWorkflowSlice(lead, req(1, [done("send-sms", "sent")]), ctx);
+    expect(paused).toEqual({ action: "wait_event", event: "seller_replied", timeout: "60s" });
+
+    const timedOut = await executeWorkflowSlice(
+      lead,
+      req(2, [done("send-sms", "sent"), done("timeout:seller_replied", null)]),
+      ctx,
+    );
+    expect(timedOut).toMatchObject({ action: "step_complete", step_name: "call" });
+
+    const replied = await executeWorkflowSlice(
+      lead,
+      req(2, [done("send-sms", "sent"), done("event:seller_replied", { body: "hi" })]),
+      ctx,
+    );
+    expect(replied).toEqual({ action: "complete", output: "replied" });
+  });
+
+  test("an invalid timeout or sleep duration fails the slice", async () => {
+    const badWait = workflow("bad-wait", async (wf) => {
+      await wf.waitForEvent("x", { timeout: "soon" });
+    });
+    const res = await executeWorkflowSlice(badWait, req(0, []), ctx);
+    expect(res.action).toBe("fail");
+    expect((res as { error: string }).error).toContain("invalid duration");
+
+    const badSleep = workflow("bad-sleep", async (wf) => {
+      await wf.sleep("5 minutes");
+    });
+    const res2 = await executeWorkflowSlice(badSleep, req(0, []), ctx);
+    expect(res2.action).toBe("fail");
+  });
+
+  test("a replayed wait with no record fails loudly", async () => {
+    const w = workflow("w", async (wf) => {
+      await wf.waitForEvent("x");
+    });
+    const res = await executeWorkflowSlice(w, req(1, [done("other", 1)]), ctx);
+    expect(res.action).toBe("fail");
+    expect((res as { error: string }).error).toContain("replay mismatch");
+  });
+
+  test("step names that collide with event records are rejected", async () => {
+    const w = workflow("w", async (wf) => {
+      await wf.step("event:x", () => 1);
+    });
+    const res = await executeWorkflowSlice(w, req(0, []), ctx);
     expect(res.action).toBe("fail");
-    expect((res as { error: string }).error).toContain("duplicate event name");
+    expect((res as { error: string }).error).toContain("reserved");
   });
 
   test("a stepless workflow completes on its first slice", async () => {