@pylonsync/sdk 0.11.6 → 0.13.0

package/dist/index.d.ts

@@ -684,7 +684,120 @@ export interface AppManifest {
      *  `pylon deploy` refuses to ship when one is missing from the
      *  project's secrets. */
     requiredEnv?: ManifestRequiredEnv[];
+    /** Production build settings (`pylon build`). */
+    build?: BuildConfig;
+    /** Realtime shard kinds whose simulation is a WebAssembly module. */
+    shards?: ManifestShard[];
 }
+/**
+ * Production build settings for `pylon build`. Dev (`pylon dev`) ignores the
+ * browser settings; they apply to the artifact and to `pylon start` builds.
+ *
+ * ```ts
+ * buildManifest({
+ *   // ...
+ *   build: {
+ *     target: ["chrome >= 90", "safari >= 14", "firefox >= 90"],
+ *     polyfill: "usage",
+ *     server: { external: ["sharp"] },
+ *   },
+ * });
+ * ```
+ */
+export interface BuildConfig {
+    /** Browser target for client JavaScript: an ECMAScript edition
+     *  (`"es2018"` to `"es2022"`) or browserslist queries. Unset: modern
+     *  output, no lowering. Needs `@swc/core` and `browserslist` in the app's
+     *  devDependencies. The client runtime needs ES modules and dynamic
+     *  `import()`, so browsers older than Chrome 63, Firefox 67, and Safari
+     *  11.1 cannot run it at any target. */
+    target?: string | string[];
+    /** core-js polyfills for `target`. `"usage"` adds the features the bundle
+     *  uses; `"entry"` adds every feature the target lacks. Needs `core-js` in
+     *  the app's dependencies. Default `false`. */
+    polyfill?: false | "usage" | "entry";
+    css?: {
+        /** CSS target (prefixes, nesting, color syntax), same forms as
+         *  `target`. Default: `target`. Needs `lightningcss` and `browserslist`. */
+        target?: string | string[];
+    };
+    /** Emit source maps for the client and server bundles. Default `false`. */
+    sourcemap?: boolean;
+    server?: {
+        /** Bundle npm packages into the server output. `false` ships every
+         *  dependency in `server/node_modules`. Default `true`. */
+        bundle?: boolean;
+        /** Packages to leave out of the server bundle and ship in
+         *  `server/node_modules` with their dependencies: native modules and
+         *  packages that read their own files at run time. */
+        external?: string[];
+    };
+    /** Project files or directories to copy into the artifact, for files the
+     *  app reads from disk at run time (content/, data/). `public/` and image
+     *  files under `app/` are always copied. */
+    include?: string[];
+}
+/** One realtime shard kind. See {@link shard}. */
+export interface ManifestShard {
+    /** The kind name `ctx.shards.create(kind, id)` takes. */
+    name: string;
+    /** The compiled module, relative to the app root. */
+    wasm: string;
+    /** A Cargo crate, relative to the app root, that `pylon shards build`
+     *  compiles to `wasm`. `pylon dev` runs that build at start. */
+    crate?: string;
+    /** Snapshot and input codec. Default `"json"`. */
+    codec?: "json" | "msgpack";
+    /** Ticks per second. `0` ticks only when inputs arrive. Default 20. */
+    tickRate?: number;
+    /** Pass `tick` a constant `1 / tickRate` instead of the measured time,
+     *  so a replay gives the same result. Default `true`. */
+    fixedTimestep?: boolean;
+    /** Subscribers one shard admits. Default 256. */
+    maxSubscribers?: number;
+    /** Shards of this kind that may run at once. Default 64. */
+    maxInstances?: number;
+    /** Memory cap per shard, in MiB. Default 64. */
+    memoryMb?: number;
+    /** Time budget for one tick (its inputs, `tick`, and the snapshots) or
+     *  one authorize call, in milliseconds. A tick that runs longer stops the
+     *  shard. Default 100. */
+    tickBudgetMs?: number;
+    /** Stop a shard after this many seconds with no subscribers and no
+     *  inputs. `0` never stops it. Default 90. */
+    idleShutdownSecs?: number;
+    /** Per-subscriber input limits. */
+    input?: {
+        /** Sustained inputs per second. Default 120. */
+        ratePerSec?: number;
+        /** Inputs above the rate a subscriber may send in a burst. Default 240. */
+        burst?: number;
+        /** Inputs one subscriber may have queued. Default 256. */
+        maxQueued?: number;
+        /** Inputs applied per subscriber per tick. Default 32. */
+        maxPerTick?: number;
+    };
+}
+/**
+ * Declare a realtime shard kind whose simulation is a WebAssembly module.
+ * Build the module with the `pylon-shard-guest` Rust crate (or any
+ * toolchain that implements its ABI). The stock `pylon` binary runs it, on
+ * Pylon Cloud too.
+ *
+ * ```ts
+ * buildManifest({
+ *   // ...
+ *   shards: [
+ *     shard({ name: "arena", wasm: "shards/arena.wasm", crate: "shards/arena", tickRate: 30 }),
+ *   ],
+ * });
+ * ```
+ *
+ * A function starts a shard with `ctx.shards.create("arena", matchId, params)`
+ * and mints tickets with `ctx.shards.ticket(matchId)`. Clients connect with
+ * `useShard(matchId, { ticket })`.
+ */
+export declare function shard(def: ManifestShard): ManifestShard;
 /** One environment variable the app declares it needs. */
 export interface ManifestRequiredEnv {
     name: string;
@@ -1121,6 +1234,10 @@ export declare function buildManifest(options: {
      *  ```
      */
     requiredEnv?: ManifestRequiredEnv[];
+    /** Production build settings for `pylon build`. See `BuildConfig`. */
+    build?: BuildConfig;
+    /** Realtime shard kinds. See `shard`. */
+    shards?: ManifestShard[];
     /** Set by `discoverFunctions()` (spread its result into this call).
      *  When true, the framework's AgentRun/AgentMessage entities and
      *  their owner-scoping policies are appended to the manifest —

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.11.6",
+  "version": "0.13.0",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",

package/src/build-config.test.ts

@@ -0,0 +1,47 @@
+/**
+ * `buildManifest({ build })`: the production build block reaches the
+ * manifest as written, and a value `pylon build` cannot use fails when app.ts
+ * runs, not at build time.
+ */
+import { expect, test } from "bun:test";
+import { buildManifest, entity, field } from "./index";
+
+const base = {
+  name: "t",
+  version: "0",
+  entities: [entity("Doc", { title: field.string() })],
+  routes: [],
+};
+
+test("the build block is copied into the manifest", () => {
+  const build = {
+    target: ["chrome >= 90", "safari >= 14"],
+    polyfill: "usage" as const,
+    css: { target: "es2019" },
+    server: { external: ["sharp"] },
+    include: ["content"],
+  };
+  expect(buildManifest({ ...base, build }).build).toEqual(build);
+});
+
+test("no build block, or an empty one, adds nothing", () => {
+  expect("build" in buildManifest(base)).toBe(false);
+  expect("build" in buildManifest({ ...base, build: {} })).toBe(false);
+});
+
+test("invalid values throw with the field name", () => {
+  const bad: Array<[unknown, string]> = [
+    [{ target: [] }, "build.target"],
+    [{ target: [""] }, "build.target"],
+    [{ polyfill: "all" }, "build.polyfill"],
+    [{ polyfill: "usage" }, "polyfill needs build.target"],
+    [{ css: { target: 5 } }, "build.css.target"],
+    [{ sourcemap: "yes" }, "build.sourcemap"],
+    [{ server: { bundle: "no" } }, "build.server.bundle"],
+    [{ server: { external: [""] } }, "build.server.external"],
+    [{ include: "content" }, "build.include"],
+  ];
+  for (const [build, msg] of bad) {
+    expect(() => buildManifest({ ...base, build: build as any })).toThrow(msg);
+  }
+});

package/src/index.ts

@@ -873,6 +873,207 @@ export interface AppManifest {
    *  `pylon deploy` refuses to ship when one is missing from the
    *  project's secrets. */
   requiredEnv?: ManifestRequiredEnv[];
+  /** Production build settings (`pylon build`). */
+  build?: BuildConfig;
+  /** Realtime shard kinds whose simulation is a WebAssembly module. */
+  shards?: ManifestShard[];
+}
+
+/**
+ * Production build settings for `pylon build`. Dev (`pylon dev`) ignores the
+ * browser settings; they apply to the artifact and to `pylon start` builds.
+ *
+ * ```ts
+ * buildManifest({
+ *   // ...
+ *   build: {
+ *     target: ["chrome >= 90", "safari >= 14", "firefox >= 90"],
+ *     polyfill: "usage",
+ *     server: { external: ["sharp"] },
+ *   },
+ * });
+ * ```
+ */
+export interface BuildConfig {
+  /** Browser target for client JavaScript: an ECMAScript edition
+   *  (`"es2018"` to `"es2022"`) or browserslist queries. Unset: modern
+   *  output, no lowering. Needs `@swc/core` and `browserslist` in the app's
+   *  devDependencies. The client runtime needs ES modules and dynamic
+   *  `import()`, so browsers older than Chrome 63, Firefox 67, and Safari
+   *  11.1 cannot run it at any target. */
+  target?: string | string[];
+  /** core-js polyfills for `target`. `"usage"` adds the features the bundle
+   *  uses; `"entry"` adds every feature the target lacks. Needs `core-js` in
+   *  the app's dependencies. Default `false`. */
+  polyfill?: false | "usage" | "entry";
+  css?: {
+    /** CSS target (prefixes, nesting, color syntax), same forms as
+     *  `target`. Default: `target`. Needs `lightningcss` and `browserslist`. */
+    target?: string | string[];
+  };
+  /** Emit source maps for the client and server bundles. Default `false`. */
+  sourcemap?: boolean;
+  server?: {
+    /** Bundle npm packages into the server output. `false` ships every
+     *  dependency in `server/node_modules`. Default `true`. */
+    bundle?: boolean;
+    /** Packages to leave out of the server bundle and ship in
+     *  `server/node_modules` with their dependencies: native modules and
+     *  packages that read their own files at run time. */
+    external?: string[];
+  };
+  /** Project files or directories to copy into the artifact, for files the
+   *  app reads from disk at run time (content/, data/). `public/` and image
+   *  files under `app/` are always copied. */
+  include?: string[];
+}
+
+/** Throws when `build` has a value `pylon build` cannot use. */
+function validateBuildConfig(build: BuildConfig): void {
+  const fail = (msg: string): never => {
+    throw new Error(`buildManifest: build.${msg}`);
+  };
+  const checkTarget = (t: unknown, field: string) => {
+    if (t === undefined) return;
+    const list = Array.isArray(t) ? t : [t];
+    if (list.length === 0 || list.some((x) => typeof x !== "string" || x.trim() === "")) {
+      fail(`${field} must be a non-empty string or a list of non-empty strings`);
+    }
+  };
+  checkTarget(build.target, "target");
+  checkTarget(build.css?.target, "css.target");
+  const pf = build.polyfill;
+  if (pf !== undefined && pf !== false && pf !== "usage" && pf !== "entry") {
+    fail(`polyfill must be false, "usage", or "entry"`);
+  }
+  if (pf && build.target === undefined) {
+    fail(`polyfill needs build.target (the browsers to polyfill for)`);
+  }
+  if (build.sourcemap !== undefined && typeof build.sourcemap !== "boolean") {
+    fail(`sourcemap must be a boolean`);
+  }
+  if (build.server?.bundle !== undefined && typeof build.server.bundle !== "boolean") {
+    fail(`server.bundle must be a boolean`);
+  }
+  for (const [field, list] of [
+    ["server.external", build.server?.external],
+    ["include", build.include],
+  ] as const) {
+    if (list === undefined) continue;
+    if (!Array.isArray(list) || list.some((x) => typeof x !== "string" || x === "")) {
+      fail(`${field} must be a list of non-empty strings`);
+    }
+  }
+}
+
+/** One realtime shard kind. See {@link shard}. */
+export interface ManifestShard {
+  /** The kind name `ctx.shards.create(kind, id)` takes. */
+  name: string;
+  /** The compiled module, relative to the app root. */
+  wasm: string;
+  /** A Cargo crate, relative to the app root, that `pylon shards build`
+   *  compiles to `wasm`. `pylon dev` runs that build at start. */
+  crate?: string;
+  /** Snapshot and input codec. Default `"json"`. */
+  codec?: "json" | "msgpack";
+  /** Ticks per second. `0` ticks only when inputs arrive. Default 20. */
+  tickRate?: number;
+  /** Pass `tick` a constant `1 / tickRate` instead of the measured time,
+   *  so a replay gives the same result. Default `true`. */
+  fixedTimestep?: boolean;
+  /** Subscribers one shard admits. Default 256. */
+  maxSubscribers?: number;
+  /** Shards of this kind that may run at once. Default 64. */
+  maxInstances?: number;
+  /** Memory cap per shard, in MiB. Default 64. */
+  memoryMb?: number;
+  /** Time budget for one tick (its inputs, `tick`, and the snapshots) or
+   *  one authorize call, in milliseconds. A tick that runs longer stops the
+   *  shard. Default 100. */
+  tickBudgetMs?: number;
+  /** Stop a shard after this many seconds with no subscribers and no
+   *  inputs. `0` never stops it. Default 90. */
+  idleShutdownSecs?: number;
+  /** Per-subscriber input limits. */
+  input?: {
+    /** Sustained inputs per second. Default 120. */
+    ratePerSec?: number;
+    /** Inputs above the rate a subscriber may send in a burst. Default 240. */
+    burst?: number;
+    /** Inputs one subscriber may have queued. Default 256. */
+    maxQueued?: number;
+    /** Inputs applied per subscriber per tick. Default 32. */
+    maxPerTick?: number;
+  };
+}
+
+/**
+ * Declare a realtime shard kind whose simulation is a WebAssembly module.
+ * Build the module with the `pylon-shard-guest` Rust crate (or any
+ * toolchain that implements its ABI). The stock `pylon` binary runs it, on
+ * Pylon Cloud too.
+ *
+ * ```ts
+ * buildManifest({
+ *   // ...
+ *   shards: [
+ *     shard({ name: "arena", wasm: "shards/arena.wasm", crate: "shards/arena", tickRate: 30 }),
+ *   ],
+ * });
+ * ```
+ *
+ * A function starts a shard with `ctx.shards.create("arena", matchId, params)`
+ * and mints tickets with `ctx.shards.ticket(matchId)`. Clients connect with
+ * `useShard(matchId, { ticket })`.
+ */
+export function shard(def: ManifestShard): ManifestShard {
+  validateShard(def);
+  return def;
+}
+
+const SHARD_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+
+/** Throws when a shard kind has a value the runtime cannot use. */
+function validateShard(def: ManifestShard): void {
+  const fail = (msg: string): never => {
+    throw new Error(`shard(${JSON.stringify(def?.name ?? "")}): ${msg}`);
+  };
+  if (typeof def?.name !== "string" || !SHARD_NAME.test(def.name)) {
+    fail("name must start with a letter and hold up to 64 letters, digits, '_', '-'");
+  }
+  const checkPath = (value: unknown, field: string) => {
+    if (typeof value !== "string" || value === "") fail(`${field} must be a non-empty path`);
+    const p = (value as string).replace(/\\/g, "/");
+    if (p.startsWith("/") || /^[A-Za-z]:/.test(p) || p.split("/").includes("..")) {
+      fail(`${field} must be relative to the app root, without ".."`);
+    }
+  };
+  checkPath(def.wasm, "wasm");
+  if (!def.wasm.endsWith(".wasm")) fail(`wasm must name a .wasm file`);
+  if (def.crate !== undefined) checkPath(def.crate, "crate");
+  if (def.codec !== undefined && def.codec !== "json" && def.codec !== "msgpack") {
+    fail(`codec must be "json" or "msgpack"`);
+  }
+  if (def.fixedTimestep !== undefined && typeof def.fixedTimestep !== "boolean") {
+    fail("fixedTimestep must be a boolean");
+  }
+  const checkInt = (value: unknown, field: string, min: number, max: number) => {
+    if (value === undefined) return;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) {
+      fail(`${field} must be an integer from ${min} to ${max}`);
+    }
+  };
+  checkInt(def.tickRate, "tickRate", 0, 1000);
+  checkInt(def.maxSubscribers, "maxSubscribers", 1, 1_000_000);
+  checkInt(def.maxInstances, "maxInstances", 1, 100_000);
+  checkInt(def.memoryMb, "memoryMb", 1, 4096);
+  checkInt(def.tickBudgetMs, "tickBudgetMs", 1, 60_000);
+  checkInt(def.idleShutdownSecs, "idleShutdownSecs", 0, 31_536_000);
+  checkInt(def.input?.ratePerSec, "input.ratePerSec", 1, 100_000);
+  checkInt(def.input?.burst, "input.burst", 1, 100_000);
+  checkInt(def.input?.maxQueued, "input.maxQueued", 1, 100_000);
+  checkInt(def.input?.maxPerTick, "input.maxPerTick", 1, 100_000);
 }
 
 /** One environment variable the app declares it needs. */
@@ -2150,6 +2351,10 @@ export function buildManifest(options: {
    *  ```
    */
   requiredEnv?: ManifestRequiredEnv[];
+  /** Production build settings for `pylon build`. See `BuildConfig`. */
+  build?: BuildConfig;
+  /** Realtime shard kinds. See `shard`. */
+  shards?: ManifestShard[];
   /** Set by `discoverFunctions()` (spread its result into this call).
    *  When true, the framework's AgentRun/AgentMessage entities and
    *  their owner-scoping policies are appended to the manifest —
@@ -2170,6 +2375,15 @@ export function buildManifest(options: {
   // can `.policies(policy({ allowRead: "..." }))` without one. Auto-
   // derive from the entity + a counter so two attached policies
   // don't collide.
+  if (options.build) validateBuildConfig(options.build);
+  const shardNames = new Set<string>();
+  for (const def of options.shards ?? []) {
+    validateShard(def);
+    if (shardNames.has(def.name)) {
+      throw new Error(`buildManifest: two shard kinds are named "${def.name}"`);
+    }
+    shardNames.add(def.name);
+  }
   const attached: PolicyDefinition[] = [];
   for (const ent of options.entities) {
     const extracted = extractAttachedPolicies(ent);
@@ -2233,6 +2447,12 @@ export function buildManifest(options: {
     ...(options.requiredEnv && options.requiredEnv.length > 0
       ? { requiredEnv: options.requiredEnv }
       : {}),
+    ...(options.build && Object.keys(options.build).length > 0
+      ? { build: options.build }
+      : {}),
+    ...(options.shards && options.shards.length > 0
+      ? { shards: options.shards }
+      : {}),
   };
 }
 

package/src/shard-config.test.ts

@@ -0,0 +1,40 @@
+/**
+ * `shard({...})` and `buildManifest({ shards })`: shard kinds reach the
+ * manifest as written, and a value the runtime cannot use fails when app.ts
+ * runs.
+ */
+import { expect, test } from "bun:test";
+import { buildManifest, entity, field, shard } from "./index";
+
+const base = {
+  name: "t",
+  version: "0",
+  entities: [entity("Doc", { title: field.string() })],
+  routes: [],
+};
+
+test("shard kinds are copied into the manifest", () => {
+  const arena = shard({
+    name: "arena",
+    wasm: "shards/arena.wasm",
+    crate: "shards/arena",
+    codec: "msgpack",
+    tickRate: 30,
+    maxInstances: 8,
+    input: { ratePerSec: 60 },
+  });
+  expect(buildManifest({ ...base, shards: [arena] }).shards).toEqual([arena]);
+  expect("shards" in buildManifest(base)).toBe(false);
+});
+
+test("bad shard kinds throw", () => {
+  expect(() => shard({ name: "1bad", wasm: "a.wasm" })).toThrow("name must start");
+  expect(() => shard({ name: "a", wasm: "../a.wasm" })).toThrow("relative to the app root");
+  expect(() => shard({ name: "a", wasm: "/abs/a.wasm" })).toThrow("relative to the app root");
+  expect(() => shard({ name: "a", wasm: "a.js" })).toThrow(".wasm file");
+  expect(() => shard({ name: "a", wasm: "a.wasm", codec: "bincode" as never })).toThrow("codec");
+  expect(() => shard({ name: "a", wasm: "a.wasm", tickRate: 1.5 })).toThrow("tickRate");
+  expect(() => shard({ name: "a", wasm: "a.wasm", memoryMb: 0 })).toThrow("memoryMb");
+  const a = { name: "a", wasm: "a.wasm" };
+  expect(() => buildManifest({ ...base, shards: [a, a] })).toThrow('two shard kinds are named "a"');
+});