@pylonsync/functions 0.22.39 → 0.22.41

package/dist/index.d.ts

@@ -27,4 +27,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, ShardsReader, ShardsWriter, ShardInfo, ShardTransfer, MemberRow, Workflows, WorkflowRunSummary, WorkflowRunStatus, Audit, AuditLog, AuditEntry, Agents, AgentRunOptions, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, TenantDomainRecord, TenantDomainDns, DomainAvailability, DomainContact, RegisterDomainOptions, RegisteredDomainResult, Files, ActionFiles, StoreFileOptions, StoredFile, } from "./types";
+export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, Shards, ShardsReader, ShardsWriter, ShardInfo, ShardTransfer, MemberRow, Workflows, WorkflowRunSummary, WorkflowRunStatus, Audit, AuditLog, AuditEntry, Agents, AgentRunOptions, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, TenantDomainRecord, TenantDomainDns, DomainAvailability, DomainContact, RegisterDomainOptions, RegisteredDomainResult, Files, ActionFiles, Crdt, StoreFileOptions, StoredFile, } from "./types";

package/dist/types.d.ts

@@ -949,6 +949,29 @@ export type RequireMember = (orgId: string, opts?: RequireMemberOptions) => Prom
  * });
  * ```
  */
+/**
+ * `ctx.crdt` (actions only): read and change a row's live CRDT document, the
+ * one editors bind to with `@pylonsync/loro`. Bytes are Loro's own formats.
+ * `@pylonsync/loro/server` wraps this in a `LoroDoc` (`openLiveDoc`).
+ *
+ * Each `apply` is its own write: it merges, then reaches everyone editing at
+ * once, so it cannot roll back with a mutation (queries and mutations get
+ * CRDT_ACTIONS_ONLY). Policies follow the `ctx.db` rule: they apply under
+ * strict function policies (`PYLON_STRICT_FN_POLICIES=1`), except through
+ * `ctx.crdt.unsafe`. Without strict policies, check access yourself.
+ */
+export interface Crdt {
+    /** The row's whole document, or null when the row does not exist (or, under
+     *  strict policies, the caller may not read it). */
+    snapshot(entity: string, id: string): Promise<Uint8Array | null>;
+    /** The changes since `version` (a Loro version vector, `doc.oplogVersion().encode()`),
+     *  or null as for {@link Crdt.snapshot}. */
+    since(entity: string, id: string, version: Uint8Array): Promise<Uint8Array | null>;
+    /** Merge a Loro update into the row and broadcast it. */
+    apply(entity: string, id: string, update: Uint8Array): Promise<void>;
+    /** The same operations with server trust even under strict policies. */
+    unsafe: Omit<Crdt, "unsafe">;
+}
 export interface Files {
     /**
      * Mint a signed download path for a file id. `ttlSecs` defaults to 300
@@ -1422,6 +1445,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
     env: Record<string, string>;
     /** Signed file-download URLs — see {@link Files}. */
     files: ActionFiles;
+    /** A row's live CRDT document, as Loro bytes — see {@link Crdt}. */
+    crdt: Crdt;
     /** Shard tickets, reads, and start/stop — see {@link Shards}. */
     shards: Shards;
     /** Run a registered query within its own read transaction. */

package/package.json

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

package/src/index.ts

@@ -117,6 +117,7 @@ export type {
   // File storage from functions.
   Files,
   ActionFiles,
+  Crdt,
   StoreFileOptions,
   StoredFile,
 } from "./types";

package/src/runtime.ts

@@ -24,6 +24,7 @@ import type {
   EmailSender,
   Files,
   ActionFiles,
+  Crdt,
   StoredFile,
   Shards,
   ShardInfo,
@@ -673,6 +674,36 @@ function buildActionFiles(callId: string): ActionFiles {
  *  FILES_STORE_MAX_BYTES; `PYLON_MAX_UPLOAD_BYTES` can lower the host's. */
 const FILES_STORE_MAX_BYTES = 25 * 1024 * 1024;
 
+/** `ctx.crdt` — see {@link Crdt}. */
+function buildCrdt(callId: string): Crdt {
+  const ops = (unsafeOp: boolean): Omit<Crdt, "unsafe"> => {
+    const call = (entity: string, id: string, op: Record<string, unknown>) =>
+      rpcDb(callId, { type: "crdt_op", entity, id, unsafe_op: unsafeOp, ...op }) as Promise<
+        Record<string, string> | null
+      >;
+    return {
+      async snapshot(entity, id) {
+        const res = await call(entity, id, { op: "snapshot" });
+        return res ? fromBase64(res.snapshot) : null;
+      },
+      async since(entity, id, version) {
+        const res = await call(entity, id, { op: "since", version_base64: toBase64(version) });
+        return res ? fromBase64(res.update) : null;
+      },
+      async apply(entity, id, update) {
+        await call(entity, id, { op: "apply", update_base64: toBase64(update) });
+      },
+    };
+  };
+  return { ...ops(false), unsafe: ops(true) };
+}
+
+/** Bytes of a base64 string. */
+function fromBase64(data: string): Uint8Array {
+  const buf = Buffer.from(data, "base64");
+  return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+}
+
 /** Base64 of bytes, or of a string's UTF-8 encoding. */
 function toBase64(data: Uint8Array | ArrayBuffer | string): string {
   const bytes =
@@ -1445,6 +1476,7 @@ function buildActionCtx(
       return err;
     },
     files: buildActionFiles(callId),
+    crdt: buildCrdt(callId),
     shards: buildShards(callId),
     // Actions have no ctx.db; read membership via the built-in internal query.
     requireMember: makeRequireMember(auth.userId, (entity, filter) =>
@@ -1640,6 +1672,9 @@ async function handleCall(msg: CallMessage): Promise<void> {
         // so a call from a query or mutation gets the host's
         // FILES_WRITE_NOT_ALLOWED instead of a TypeError.
         files: buildActionFiles(msg.call_id),
+        // Not on the query or mutation type; present at runtime so a call
+        // gets the host's CRDT_ACTIONS_ONLY instead of a TypeError.
+        crdt: buildCrdt(msg.call_id),
         shards: buildShards(msg.call_id),
       };
       break;
@@ -1669,6 +1704,9 @@ async function handleCall(msg: CallMessage): Promise<void> {
         // so a call from a query or mutation gets the host's
         // FILES_WRITE_NOT_ALLOWED instead of a TypeError.
         files: buildActionFiles(msg.call_id),
+        // Not on the query or mutation type; present at runtime so a call
+        // gets the host's CRDT_ACTIONS_ONLY instead of a TypeError.
+        crdt: buildCrdt(msg.call_id),
         shards: buildShards(msg.call_id),
       };
       break;

package/src/ssr-client-bundler.test.ts

@@ -335,6 +335,93 @@ describe("ssr-client-bundler (Phase 1.5e)", () => {
 // inlines; the build test guards the boundary wiring + not-found.tsx entry.
 // ---------------------------------------------------------------------------
 
+describe("imported assets", () => {
+  // loro-crdt's browser build imports its .wasm; Bun turns that into a URL
+  // string. It must be absolute under the build prefix and name a file the
+  // build wrote, or the page fetches it relative to its own path and 404s.
+  test("an imported .wasm gets an absolute URL that exists in the build", async () => {
+    tempDir = makeFixture(
+      {
+        "page.tsx": PAGE_BODY("Home"),
+        "hello/page.tsx": PAGE_BODY("Hello"),
+        "docs/[id]/page.tsx": `
+import React from "react";
+import wasmUrl from "./engine.wasm";
+export default function Doc() {
+  return <div data-wasm={wasmUrl}>doc</div>;
+}
+`,
+      },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    fs.writeFileSync(path.join(tempDir, "app", "docs", "[id]", "engine.wasm"), new Uint8Array([0, 97, 115, 109, 1, 0, 0, 0]));
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+
+    const { outdir, manifestPath } = await buildClientBundle();
+
+    const built = [
+      ...fs.readdirSync(outdir).filter((n) => n.endsWith(".js")).map((n) => path.join(outdir, n)),
+      ...fs.readdirSync(path.join(outdir, "chunks")).map((n) => path.join(outdir, "chunks", n)),
+    ]
+      .map((f) => fs.readFileSync(f, "utf8"))
+      .join("\n");
+    const urls = built.match(/["'](\/_pylon\/build\/assets\/engine-[A-Za-z0-9]+\.wasm)["']/);
+    expect(urls).not.toBeNull();
+    const rel = urls![1].slice("/_pylon/build/".length);
+    expect(fs.existsSync(path.join(outdir, rel))).toBe(true);
+    // Every import between built files resolves to a file the build wrote,
+    // the way the browser resolves it (relative to the importing file).
+    const jsFiles = [
+      ...fs.readdirSync(outdir).filter((n) => n.endsWith(".js")).map((n) => path.join(outdir, n)),
+      ...fs.readdirSync(path.join(outdir, "chunks")).filter((n) => n.endsWith(".js")).map((n) => path.join(outdir, "chunks", n)),
+    ];
+    for (const file of jsFiles) {
+      const src = fs.readFileSync(file, "utf8");
+      for (const m of src.matchAll(/(?:from\s*|import\s*\(?\s*)["']([^"']+\.js)["']/g)) {
+        const spec = m[1];
+        const target = spec.startsWith("/_pylon/build/")
+          ? path.join(outdir, spec.slice("/_pylon/build/".length))
+          : path.resolve(path.dirname(file), spec);
+        expect(`${path.relative(outdir, file)} -> ${spec}: ${fs.existsSync(target)}`).toBe(`${path.relative(outdir, file)} -> ${spec}: true`);
+      }
+    }
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8")) as PylonBundleManifest;
+    expect(manifest.public_prefix).toBe("/_pylon/build/");
+    for (const route of Object.values(manifest.routes)) {
+      expect(route.imports.length).toBeGreaterThan(0);
+      for (const imp of route.imports) expect(fs.existsSync(path.join(outdir, imp))).toBe(true);
+    }
+  });
+});
+
+describe("assets a stylesheet references", () => {
+  // The asset plugin answers JavaScript imports with a JavaScript module; a
+  // stylesheet's url(...) must stay with Bun, or the build fails with
+  // "Cannot import a .js file into a CSS file".
+  test("a page importing CSS that uses url() still builds", async () => {
+    tempDir = makeFixture(
+      {
+        "page.tsx": `
+import React from "react";
+import "./look.css";
+export default function Home() {
+  return <div className="hero">home</div>;
+}
+`,
+      },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    fs.writeFileSync(path.join(tempDir, "app", "look.css"), ".hero { background: url(./bg.png); }\n");
+    fs.writeFileSync(path.join(tempDir, "app", "bg.png"), new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]));
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+
+    const { manifestPath } = await buildClientBundle();
+    expect(fs.existsSync(manifestPath)).toBe(true);
+  });
+});
+
 describe("nearestBoundaryComponent (client boundary resolution)", () => {
   const routes = new Set([
     "web/app/not-found",

package/src/ssr-client-bundler.ts

@@ -89,6 +89,18 @@ type BunBuildOutput = {
   logs?: Array<{ level: string; message: string }>;
 };
 
+/** The part of Bun's plugin builder the client build uses. */
+type BunPluginBuild = {
+  onResolve(
+    opts: { filter: RegExp; namespace?: string },
+    callback: (args: { path: string; importer: string }) => { path: string; namespace: string } | undefined | void,
+  ): void;
+  onLoad(
+    opts: { filter: RegExp; namespace?: string },
+    callback: (args: { path: string }) => { contents: string; loader: "js" },
+  ): void;
+};
+
 declare const Bun: {
   build(opts: {
     entrypoints: string[];
@@ -111,12 +123,7 @@ declare const Bun: {
     root?: string;
     plugins?: Array<{
       name: string;
-      setup(build: {
-        onResolve(
-          opts: { filter: RegExp; namespace?: string },
-          callback: (args: { path: string; importer: string }) => void,
-        ): void;
-      }): void;
+      setup(build: BunPluginBuild): void;
     }>;
   }): Promise<BunBuildOutput>;
   file(path: string): { exists(): Promise<boolean> };
@@ -1644,12 +1651,15 @@ export async function _doBuildInner(
       naming: {
         entry: "[name]-[hash].js",
         chunk: "chunks/[name]-[hash].js",
-        asset: "assets/[name]-[hash][ext]",
+        // Bun's `[ext]` has no leading dot.
+        asset: "assets/[name]-[hash].[ext]",
       },
+
       // Refuse to bundle a server-only module into a client-reachable page —
       // secrets / server config in a page's import graph would otherwise ship
       // to the browser.
       plugins: [
+        absoluteAssetPlugin(outdir, fs, path, (await import("node:crypto")).createHash),
         {
           name: "pylon-server-only",
           setup(build) {
@@ -1811,7 +1821,7 @@ export async function _doBuildInner(
     const manifest: PylonBundleManifest = {
       build_id: makeBuildId(),
       outdir: outdirRel,
-      public_prefix: "/_pylon/build/",
+      public_prefix: BUILD_PREFIX,
       routes: {},
       ...(polyfills ? { polyfills } : {}),
     };
@@ -2071,6 +2081,55 @@ function makeBuildId(): string {
   return `${process.pid.toString(36)}-${Date.now().toString(36)}-${_buildCounter}`;
 }
 
+/** Where the Rust host serves the client build (`/_pylon/build/<path>`): the
+ *  manifest's `public_prefix`, and the prefix of imported assets' URLs. */
+const BUILD_PREFIX = "/_pylon/build/";
+
+/** Files a page can import as a URL (Bun's `file` loader). */
+const ASSET_RE = /\.(wasm|png|jpe?g|gif|webp|avif|ico|svg|woff2?|ttf|otf|mp3|mp4|webm|wav|ogg)$/i;
+
+/**
+ * Assets JavaScript imports (a `.wasm`, an image) as absolute URLs under the
+ * build prefix. Bun's `file` loader exports a RELATIVE path ("assets/x.wasm"),
+ * and code that fetches it resolves it against the page: loro-crdt's browser
+ * build fetched /dashboard/orgs/acme/assets/loro_wasm_bg-….wasm and 404'd.
+ * Bun's `publicPath` would make it absolute, but it also rewrites imports
+ * between split chunks and drops their `chunks/` directory (Bun 1.3.14), so
+ * this plugin writes the file itself, named by its content hash, and exports
+ * the absolute URL. A stylesheet's `url(...)` is left to Bun: CSS cannot
+ * import a JavaScript module.
+ */
+function absoluteAssetPlugin(
+  outdir: string,
+  fs: typeof import("node:fs"),
+  path: typeof import("node:path"),
+  createHash: typeof import("node:crypto").createHash,
+): { name: string; setup(build: BunPluginBuild): void } {
+  const NAMESPACE = "pylon-asset";
+  return {
+    name: "pylon-absolute-assets",
+    setup(build) {
+      build.onResolve({ filter: ASSET_RE }, (args) => {
+        if (!args.importer || /\.css$/i.test(args.importer)) return undefined;
+        const from = path.dirname(args.importer);
+        const resolved = args.path.startsWith(".") || path.isAbsolute(args.path)
+          ? path.resolve(from, args.path)
+          : ((Bun as any).resolveSync(args.path, from) as string);
+        return { path: resolved, namespace: NAMESPACE };
+      });
+      build.onLoad({ filter: /.*/, namespace: NAMESPACE }, (args) => {
+        const bytes = fs.readFileSync(args.path);
+        const hash = createHash("sha256").update(bytes).digest("hex").slice(0, 12);
+        const ext = path.extname(args.path);
+        const rel = `assets/${path.basename(args.path, ext)}-${hash}${ext}`;
+        fs.mkdirSync(path.join(outdir, "assets"), { recursive: true });
+        fs.writeFileSync(path.join(outdir, rel), bytes);
+        return { contents: `export default ${JSON.stringify(BUILD_PREFIX + rel)};`, loader: "js" };
+      });
+    },
+  };
+}
+
 /**
  * Base URL/path prepended to every SSR-emitted asset reference (the entry
  * `<script type="module">`, `<link rel="stylesheet">`, and `modulepreload`s)

package/src/types.ts

@@ -1044,6 +1044,30 @@ export type RequireMember = (
  * });
  * ```
  */
+/**
+ * `ctx.crdt` (actions only): read and change a row's live CRDT document, the
+ * one editors bind to with `@pylonsync/loro`. Bytes are Loro's own formats.
+ * `@pylonsync/loro/server` wraps this in a `LoroDoc` (`openLiveDoc`).
+ *
+ * Each `apply` is its own write: it merges, then reaches everyone editing at
+ * once, so it cannot roll back with a mutation (queries and mutations get
+ * CRDT_ACTIONS_ONLY). Policies follow the `ctx.db` rule: they apply under
+ * strict function policies (`PYLON_STRICT_FN_POLICIES=1`), except through
+ * `ctx.crdt.unsafe`. Without strict policies, check access yourself.
+ */
+export interface Crdt {
+  /** The row's whole document, or null when the row does not exist (or, under
+   *  strict policies, the caller may not read it). */
+  snapshot(entity: string, id: string): Promise<Uint8Array | null>;
+  /** The changes since `version` (a Loro version vector, `doc.oplogVersion().encode()`),
+   *  or null as for {@link Crdt.snapshot}. */
+  since(entity: string, id: string, version: Uint8Array): Promise<Uint8Array | null>;
+  /** Merge a Loro update into the row and broadcast it. */
+  apply(entity: string, id: string, update: Uint8Array): Promise<void>;
+  /** The same operations with server trust even under strict policies. */
+  unsafe: Omit<Crdt, "unsafe">;
+}
+
 export interface Files {
   /**
    * Mint a signed download path for a file id. `ttlSecs` defaults to 300
@@ -1542,6 +1566,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   env: Record<string, string>;
   /** Signed file-download URLs — see {@link Files}. */
   files: ActionFiles;
+  /** A row's live CRDT document, as Loro bytes — see {@link Crdt}. */
+  crdt: Crdt;
   /** Shard tickets, reads, and start/stop — see {@link Shards}. */
   shards: Shards;
   /** Run a registered query within its own read transaction. */