@pylonsync/functions 0.12.0 → 0.13.0

package/dist/index.d.ts

@@ -26,4 +26,4 @@ export type { WorkflowDefinition, WorkflowRun, WorkflowRunRequest, WorkflowRunne
 export { resetDb, installTestIsolation } from "./testing";
 export { slugifyName, availableSlug } from "./slugify";
 export type { SsrResponse, SsrCookieOptions, SsrMetadata, Sitemap, SitemapEntry, Robots, RobotsRule, } from "./ssr-runtime";
-export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, Shards, MemberRow, Workflows, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, TenantDomainDns, DomainAvailability, DomainContact, RegisterDomainOptions, RegisteredDomainResult, } from "./types";
+export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, Shards, ShardsReader, ShardInfo, MemberRow, Workflows, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, TenantDomainDns, DomainAvailability, DomainContact, RegisterDomainOptions, RegisteredDomainResult, } from "./types";

package/dist/production-build.d.ts

@@ -24,7 +24,7 @@ export interface ProductionBuildResult {
 export declare function buildProduction(opts: ProductionBuildOptions): Promise<ProductionBuildResult>;
 /** The artifact-relative path for one `build.include` entry. Throws when the
  *  entry cannot be copied into the artifact as-is. */
-export declare function checkInclude(path: any, cwd: string, outDir: string, inc: string, src: string): string;
+export declare function checkInclude(path: any, cwd: string, outDir: string, inc: string, src: string, label?: string): string;
 /**
  * Every app module the SSR runtime can import: files named by convention
  * anywhere under the app dir, plus every component and layout the manifest

package/dist/types.d.ts

@@ -766,6 +766,39 @@ export interface Shards {
         claims?: Record<string, unknown>;
         ttlSecs?: number;
     }): Promise<string>;
+    /**
+     * Start shard `shardId` of a kind declared with `shard({...})` in app.ts.
+     * `params` reach the module's `init`. Actions only: a mutation's
+     * rollback cannot undo it.
+     *
+     * Throws `SHARD_EXISTS` when the id is running, `SHARD_LIMIT_REACHED`
+     * at the kind's `maxInstances`, `SHARD_KIND_NOT_FOUND`,
+     * `SHARD_ID_INVALID`, or `SHARD_INIT_FAILED` when `init` refuses.
+     */
+    create(kind: string, shardId: string, params?: unknown): Promise<ShardInfo>;
+    /** Stop a shard and close its subscribers' connections. Resolves to
+     *  `false` when no shard has that id. Actions only. */
+    stop(shardId: string): Promise<boolean>;
+    /** A running shard, or `null`. */
+    get(shardId: string): Promise<ShardInfo | null>;
+    /** Every running shard. */
+    list(): Promise<ShardInfo[]>;
+}
+/** `ctx.shards` in a query or mutation: tickets and reads, no start or stop. */
+export type ShardsReader = Pick<Shards, "ticket" | "get" | "list">;
+/** A running shard, from `ctx.shards.create`, `get`, or `list`. */
+export interface ShardInfo {
+    id: string;
+    /** The shard kind's name. */
+    kind: string;
+    /** Ticks run so far. */
+    tick: number;
+    subscribers: number;
+    /** False once the shard stopped (finished, idle, or failed) and before
+     *  the host removes it. */
+    running: boolean;
+    /** Why the module stopped, when it trapped. */
+    error?: string;
 }
 /** Context for query handlers (read-only).
  *
@@ -792,8 +825,8 @@ export interface QueryCtx<R extends AuthRequirement = "optional"> {
     requireMember: RequireMember;
     /** Signed file-download URLs — see {@link Files}. */
     files: Files;
-    /** Shard tickets — see {@link Shards}. */
-    shards: Shards;
+    /** Shard tickets and reads — see {@link Shards}. */
+    shards: ShardsReader;
     /**
      * Fires when the host cancels this call (idle timeout exceeded).
      * Thread it into `fetch(url, { signal: ctx.signal })` or SDK calls so
@@ -821,8 +854,8 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
     workflows: Workflows;
     /** Signed file-download URLs — see {@link Files}. */
     files: Files;
-    /** Shard tickets — see {@link Shards}. */
-    shards: Shards;
+    /** Shard tickets and reads — see {@link Shards}. */
+    shards: ShardsReader;
     /** Create a typed error that triggers rollback. */
     error(code: string, message: string): Error;
     /** Assert org membership (optionally a role) — see {@link RequireMember}. */
@@ -992,7 +1025,7 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
     env: Record<string, string>;
     /** Signed file-download URLs — see {@link Files}. */
     files: Files;
-    /** Shard tickets — see {@link Shards}. */
+    /** Shard tickets, reads, and start/stop — see {@link Shards}. */
     shards: Shards;
     /** Run a registered query within its own read transaction. */
     runQuery<T = unknown>(fnName: string, args: Record<string, unknown>): Promise<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -74,6 +74,8 @@ export type {
   RequireMember,
   RequireMemberOptions,
   Shards,
+  ShardsReader,
+  ShardInfo,
   MemberRow,
   Workflows,
   VectorSearchQuery,

package/src/production-build.ts

@@ -234,6 +234,18 @@ export async function buildProduction(
     if (!fs.existsSync(src)) throw new Error(`build.include: "${inc}" does not exist`);
     fs.cpSync(src, path.join(outDir, rel), { recursive: true, dereference: true });
   }
+  // Shard modules, at the paths app.ts gives, which the runtime reads at boot.
+  for (const def of (manifest.shards ?? []) as Array<{ name: string; wasm: string }>) {
+    const src = path.resolve(cwd, def.wasm);
+    const rel = checkInclude(path, cwd, outDir, def.wasm, src, `shard "${def.name}" wasm`);
+    if (!fs.existsSync(src)) {
+      throw new Error(
+        `shard "${def.name}": ${def.wasm} does not exist; run \`pylon shards build\` first`,
+      );
+    }
+    fs.mkdirSync(path.dirname(path.join(outDir, rel)), { recursive: true });
+    fs.copyFileSync(src, path.join(outDir, rel));
+  }
 
   fs.writeFileSync(path.join(outDir, "pylon.manifest.json"), manifestRaw, "utf8");
   const pkg = JSON.parse(fs.readFileSync(path.join(here, "..", "package.json"), "utf8"));
@@ -317,21 +329,22 @@ export function checkInclude(
   outDir: string,
   inc: string,
   src: string,
+  label = "build.include",
 ): string {
   const rel = path.relative(cwd, src);
   const isOutside = (r: string) =>
     r === ".." || r.startsWith(`..${path.sep}`) || r.startsWith("../") || path.isAbsolute(r);
-  if (rel === "") throw new Error(`build.include: "${inc}" is the project directory`);
+  if (rel === "") throw new Error(`${label}: "${inc}" is the project directory`);
   if (isOutside(rel)) {
-    throw new Error(`build.include: "${inc}" is outside the project directory`);
+    throw new Error(`${label}: "${inc}" is outside the project directory`);
   }
   // Neither the output directory nor anything that contains it or is in it.
   if (!isOutside(path.relative(src, outDir)) || !isOutside(path.relative(outDir, src))) {
-    throw new Error(`build.include: "${inc}" overlaps the output directory`);
+    throw new Error(`${label}: "${inc}" overlaps the output directory`);
   }
   const top = rel.split(/[\\/]/)[0];
   if (RESERVED_INCLUDE_NAMES.has(top)) {
-    throw new Error(`build.include: "${inc}" would write into the artifact's own "${top}"`);
+    throw new Error(`${label}: "${inc}" would write into the artifact's own "${top}"`);
   }
   return rel;
 }

package/src/runtime-shard-ticket.test.ts

@@ -1,6 +1,6 @@
 /**
- * `ctx.shards.ticket` — the frame the runtime sends to the host, and the
- * ticket string it returns. The host signs (it holds the secret); this
+ * `ctx.shards` — the frames the runtime sends to the host (`ticket`,
+ * `create`, `stop`, `get`, `list`) and the values it returns. The host signs (it holds the secret); this
  * checks the TS half. Same child-process NDJSON harness as
  * runtime-email.test.ts.
  */
@@ -18,24 +18,16 @@ function parseFrames(text: string): Record<string, unknown>[] {
     .map((l) => JSON.parse(l) as Record<string, unknown>);
 }
 
-test("ctx.shards.ticket sends sign_shard_ticket and returns the host's ticket", async () => {
-  const dir = mkdtempSync(join(tmpdir(), "pylon-fn-ticket-"));
+/** Run one function in a real runtime child; `host` answers its frames. */
+async function runFunction(
+  source: string,
+  host: (frame: Record<string, unknown>) => unknown,
+  hostFrameTypes: string[],
+  fnType: "mutation" | "action" = "mutation",
+): Promise<{ value: unknown; hostFrames: Record<string, unknown>[] }> {
+  const dir = mkdtempSync(join(tmpdir(), "pylon-fn-shards-"));
   mkdirSync(join(dir, "functions"));
-  writeFileSync(
-    join(dir, "functions", "join.ts"),
-    `export default {
-  type: "mutation",
-  handler: async (ctx) => {
-    const ticket = await ctx.shards.ticket("zone-3", {
-      subscriberId: "char_12",
-      claims: { realm: "north" },
-      ttlSecs: 30,
-    });
-    return { ticket };
-  },
-};
-`,
-  );
+  writeFileSync(join(dir, "functions", "run.ts"), source);
   const proc = Bun.spawn([process.execPath, RUNTIME, "./functions"], {
     cwd: dir,
     stdin: "pipe",
@@ -45,43 +37,101 @@ test("ctx.shards.ticket sends sign_shard_ticket and returns the host's ticket",
   const reader = (proc.stdout as ReadableStream<Uint8Array>).getReader();
   const decoder = new TextDecoder();
   let buffered = "";
-  const readUntil = async (pred: (f: Record<string, unknown>[]) => boolean) => {
-    let frames = parseFrames(buffered);
-    while (!pred(frames)) {
+  let consumed = 0;
+  const next = async (): Promise<Record<string, unknown>> => {
+    for (;;) {
+      const frames = parseFrames(buffered);
+      if (frames.length > consumed) return frames[consumed++];
       const { done, value } = await reader.read();
-      if (done) break;
+      if (done) throw new Error("runtime exited");
       buffered += decoder.decode(value, { stream: true });
-      frames = parseFrames(buffered);
     }
-    return frames;
   };
   const send = (msg: Record<string, unknown>) =>
     (proc.stdin as import("bun").FileSink).write(JSON.stringify(msg) + "\n");
 
-  await readUntil((fs) => fs.some((f) => f.type === "ready"));
+  while ((await next()).type !== "ready");
   send({
     type: "call",
     call_id: "c_1",
-    fn_name: "join",
-    fn_type: "mutation",
+    fn_name: "run",
+    fn_type: fnType,
     args: {},
     auth: { user_id: "u1", is_admin: false, tenant_id: null },
   });
+  const hostFrames: Record<string, unknown>[] = [];
+  try {
+    for (;;) {
+      const frame = await next();
+      if (frame.type === "return") return { value: frame.value, hostFrames };
+      if (frame.type === "error") throw new Error(JSON.stringify(frame));
+      if (hostFrameTypes.includes(frame.type as string)) {
+        hostFrames.push(frame);
+        send({ type: "result", call_id: "c_1", data: host(frame) });
+      }
+    }
+  } finally {
+    proc.kill();
+  }
+}
 
-  let frames = await readUntil((fs) => fs.some((f) => f.type === "sign_shard_ticket"));
-  expect(frames.find((f) => f.type === "sign_shard_ticket")).toMatchObject({
+test("ctx.shards.ticket sends sign_shard_ticket and returns the host's ticket", async () => {
+  const { value, hostFrames } = await runFunction(
+    `export default {
+  type: "mutation",
+  handler: async (ctx) => {
+    const ticket = await ctx.shards.ticket("zone-3", {
+      subscriberId: "char_12",
+      claims: { realm: "north" },
+      ttlSecs: 30,
+    });
+    return { ticket };
+  },
+};
+`,
+    () => "v1.payload.sig",
+    ["sign_shard_ticket"],
+  );
+  expect(hostFrames[0]).toMatchObject({
     call_id: "c_1",
     shard: "zone-3",
     subscriber_id: "char_12",
     claims: { realm: "north" },
     ttl_secs: 30,
   });
-  send({ type: "result", call_id: "c_1", data: "v1.payload.sig" });
+  expect(value).toEqual({ ticket: "v1.payload.sig" });
+});
 
-  frames = await readUntil((fs) => fs.some((f) => f.type === "return"));
-  expect(frames.find((f) => f.type === "return")).toMatchObject({
-    call_id: "c_1",
-    value: { ticket: "v1.payload.sig" },
-  });
-  proc.kill();
+test("ctx.shards.create/get/list/stop in an action send shard_op frames", async () => {
+  const info = { id: "m1", kind: "arena", tick: 0, subscribers: 0, running: true };
+  const { value, hostFrames } = await runFunction(
+    `export default {
+  type: "action",
+  handler: async (ctx) => {
+    const created = await ctx.shards.create("arena", "m1", { fog: true });
+    const got = await ctx.shards.get("m1");
+    const all = await ctx.shards.list();
+    const stopped = await ctx.shards.stop("m1");
+    return { created, got, all, stopped };
+  },
+};
+`,
+    (frame) => {
+      switch (frame.op) {
+        case "create":
+        case "get":
+          return info;
+        case "list":
+          return [info];
+        default:
+          return true;
+      }
+    },
+    ["shard_op"],
+    "action",
+  );
+  expect(hostFrames.map((f) => f.op)).toEqual(["create", "get", "list", "stop"]);
+  expect(hostFrames[0]).toMatchObject({ kind: "arena", id: "m1", params: { fog: true } });
+  expect(hostFrames[3]).toMatchObject({ id: "m1" });
+  expect(value).toEqual({ created: info, got: info, all: [info], stopped: true });
 });

package/src/runtime.ts

@@ -23,6 +23,7 @@ import type {
   EmailSender,
   Files,
   Shards,
+  ShardInfo,
   Stream,
   Scheduler,
   Llm,
@@ -535,6 +536,24 @@ function buildShards(callId: string): Shards {
         ttl_secs: opts?.ttlSecs,
       }) as Promise<string>;
     },
+    async create(kind, shardId, params) {
+      return rpc(callId, {
+        type: "shard_op",
+        op: "create",
+        kind,
+        id: shardId,
+        params: params ?? {},
+      }) as Promise<ShardInfo>;
+    },
+    async stop(shardId) {
+      return rpc(callId, { type: "shard_op", op: "stop", id: shardId }) as Promise<boolean>;
+    },
+    async get(shardId) {
+      return rpc(callId, { type: "shard_op", op: "get", id: shardId }) as Promise<ShardInfo | null>;
+    },
+    async list() {
+      return rpc(callId, { type: "shard_op", op: "list" }) as Promise<ShardInfo[]>;
+    },
   };
 }
 

package/src/types.ts

@@ -861,6 +861,45 @@ export interface Shards {
     shardId: string,
     opts?: { subscriberId?: string; claims?: Record<string, unknown>; ttlSecs?: number },
   ): Promise<string>;
+
+  /**
+   * Start shard `shardId` of a kind declared with `shard({...})` in app.ts.
+   * `params` reach the module's `init`. Actions only: a mutation's
+   * rollback cannot undo it.
+   *
+   * Throws `SHARD_EXISTS` when the id is running, `SHARD_LIMIT_REACHED`
+   * at the kind's `maxInstances`, `SHARD_KIND_NOT_FOUND`,
+   * `SHARD_ID_INVALID`, or `SHARD_INIT_FAILED` when `init` refuses.
+   */
+  create(kind: string, shardId: string, params?: unknown): Promise<ShardInfo>;
+
+  /** Stop a shard and close its subscribers' connections. Resolves to
+   *  `false` when no shard has that id. Actions only. */
+  stop(shardId: string): Promise<boolean>;
+
+  /** A running shard, or `null`. */
+  get(shardId: string): Promise<ShardInfo | null>;
+
+  /** Every running shard. */
+  list(): Promise<ShardInfo[]>;
+}
+
+/** `ctx.shards` in a query or mutation: tickets and reads, no start or stop. */
+export type ShardsReader = Pick<Shards, "ticket" | "get" | "list">;
+
+/** A running shard, from `ctx.shards.create`, `get`, or `list`. */
+export interface ShardInfo {
+  id: string;
+  /** The shard kind's name. */
+  kind: string;
+  /** Ticks run so far. */
+  tick: number;
+  subscribers: number;
+  /** False once the shard stopped (finished, idle, or failed) and before
+   *  the host removes it. */
+  running: boolean;
+  /** Why the module stopped, when it trapped. */
+  error?: string;
 }
 
 /** Context for query handlers (read-only).
@@ -888,8 +927,8 @@ export interface QueryCtx<R extends AuthRequirement = "optional"> {
   requireMember: RequireMember;
   /** Signed file-download URLs — see {@link Files}. */
   files: Files;
-  /** Shard tickets — see {@link Shards}. */
-  shards: Shards;
+  /** Shard tickets and reads — see {@link Shards}. */
+  shards: ShardsReader;
   /**
    * Fires when the host cancels this call (idle timeout exceeded).
    * Thread it into `fetch(url, { signal: ctx.signal })` or SDK calls so
@@ -918,8 +957,8 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
   workflows: Workflows;
   /** Signed file-download URLs — see {@link Files}. */
   files: Files;
-  /** Shard tickets — see {@link Shards}. */
-  shards: Shards;
+  /** Shard tickets and reads — see {@link Shards}. */
+  shards: ShardsReader;
   /** Create a typed error that triggers rollback. */
   error(code: string, message: string): Error;
   /** Assert org membership (optionally a role) — see {@link RequireMember}. */
@@ -1093,7 +1132,7 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   env: Record<string, string>;
   /** Signed file-download URLs — see {@link Files}. */
   files: Files;
-  /** Shard tickets — see {@link Shards}. */
+  /** Shard tickets, reads, and start/stop — see {@link Shards}. */
   shards: Shards;
   /** Run a registered query within its own read transaction. */
   runQuery<T = unknown>(