@pylonsync/functions 0.20.0 → 0.22.0

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 }>;
 }
 
 /**
@@ -494,10 +508,16 @@ export interface Llm {
    * if (res.stop_reason === "tool_use") { ...run tools, loop... }
    * ```
    *
-   * Streaming does NOT extend the function's call deadline — it is an
-   * absolute wall clock from invocation (PYLON_FN_CALL_TIMEOUT, 30s
-   * default). A long agent run must declare its own `timeout` on the
-   * function def.
+   * The function's call timeout (PYLON_FN_CALL_TIMEOUT, 30s default, or
+   * the function's own `timeout`) is an idle timeout. A running stream
+   * counts as activity, but no call outlives 10× its timeout, so a long
+   * agent run should still declare its own `timeout`.
+   *
+   * Pass `{ signal }` to stop a stream early. When the signal aborts,
+   * the promise rejects with `err.code === "LLM_CANCELLED"` and the
+   * server closes the provider connection, so the model stops
+   * generating (and billing) tokens. A stream still running when the
+   * function returns or times out is cancelled the same way.
    *
    * Same errors and same gating as {@link Llm.complete} — including
    * the model allowlist, so streaming can't be used to reach a model
@@ -506,6 +526,7 @@ export interface Llm {
   stream(
     request: LlmCompleteRequest,
     onEvent: (event: LlmStreamEvent) => void,
+    options?: { signal?: AbortSignal },
   ): Promise<LlmCompleteResponse>;
 
   /**
@@ -604,18 +625,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 +1194,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 +1230,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 +1250,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.
@@ -1185,6 +1370,48 @@ export interface Domains {
   ): Promise<RegisteredDomainResult>;
 }
 
+/** Options for {@link Agents.run}. */
+export interface AgentRunOptions {
+  /** The message for this turn. */
+  input: string;
+  /** Continue this run. It must belong to `as.userId` and this agent. */
+  runId?: string;
+  /** Display title, stored on a new run. */
+  title?: string;
+  /**
+   * The user the run belongs to and runs as. The run shows up in that
+   * user's synced `AgentRun`/`AgentMessage` rows. `admin: true` also
+   * gives the run admin rights (needed for an agent declared
+   * `auth: "admin"`), and is allowed only when the caller is an admin.
+   */
+  as: { userId: string; admin?: boolean };
+  /**
+   * JSON the agent's tool handlers receive as `run.context` (their third
+   * argument), for example the conversation a webhook turn belongs to.
+   * Stored on the run as `AgentRun.context`, so later turns of the run
+   * see it too. The run's owner can read it; do not put secrets in it.
+   */
+  context?: Record<string, unknown>;
+}
+
+/**
+ * Run an `agent()` from server code. See {@link ActionCtx.agents}.
+ */
+export interface Agents {
+  /**
+   * Run agent `name` (its file name in `functions/`) as `options.as`.
+   * Resolves with the agent's result once the turn finishes, like a
+   * `streamFn` call's final `result` event. The agent's tokens are not
+   * streamed to this caller; they are in the run's `AgentMessage` rows.
+   *
+   * Only server code can do this: the calling action must be
+   * `internal: true` (jobs, workflows, scheduled work) or run with admin
+   * rights (an admin session, or a webhook after `ctx.auth.elevate`).
+   * Otherwise it throws `AGENT_RUN_FORBIDDEN`.
+   */
+  run(name: string, options: AgentRunOptions): Promise<import("./agent").AgentResult>;
+}
+
 export interface ActionCtx<R extends AuthRequirement = "optional"> {
   auth: AuthInfo<R>;
   stream: Stream;
@@ -1199,6 +1426,10 @@ 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;
+  /** Run an `agent()` as a named user from server code — see {@link Agents}. */
+  agents: Agents;
   /** Attach / register custom domains for your app's OWN end-customers
    *  (platform domains) — see {@link Domains}. Cloud-only. */
   domains: Domains;
@@ -1249,13 +1480,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 () => {