@pylonsync/functions 0.11.5 → 0.12.0

package/src/stdout-fence.ts

@@ -0,0 +1,69 @@
+// Keeps stdout for the host protocol. See `fenceStdout`.
+
+// Bun global used here. Declared locally so apps that type-check this source
+// without bun-types still pass `tsc` (same pattern as runtime.ts).
+declare const Bun: {
+  write(dest: unknown, data: string): unknown;
+  stderr: unknown;
+};
+
+/**
+ * Redirect console.* from user code to stderr so handlers can't accidentally
+ * emit a line that looks like a protocol frame and confuse the Rust reader.
+ *
+ * Before this guard, a handler calling `console.log('{"type":"return",...}')`
+ * — either intentionally or by logging an object shaped that way — would be
+ * parsed by the host as a real protocol message. Moving all console output
+ * to stderr keeps stdout reserved for NDJSON protocol frames only.
+ *
+ * The original console methods are saved on the console object as
+ * `__stdoutLog` etc. in case the runtime itself needs to write diagnostics
+ * to stdout for some reason (it currently doesn't).
+ *
+ * Safe to call more than once. A production server bundle calls it from its
+ * entry, before the app modules load, and the runtime's `main()` calls it
+ * again.
+ */
+export function fenceStdout(): void {
+  const c = globalThis.console as unknown as Record<string, unknown>;
+  if (c.__pylonFenced) return;
+  c.__pylonFenced = true;
+  const toStderr = (prefix: string) => (...args: unknown[]) => {
+    const line = args
+      .map((a) => {
+        if (typeof a === "string") return a;
+        // Error: JSON.stringify yields `{}` because message/stack are
+        // non-enumerable. That made `console.error("x:", err)` log as `x: {}`,
+        // hiding the real failure from operators. Unwrap by hand.
+        if (a instanceof Error) {
+          const parts = [a.stack || `${a.name}: ${a.message}`];
+          const code = (a as { code?: unknown }).code;
+          if (code !== undefined) parts.push(`code=${String(code)}`);
+          const cause = (a as { cause?: unknown }).cause;
+          if (cause !== undefined) {
+            try {
+              parts.push(`cause=${cause instanceof Error ? cause.stack || cause.message : JSON.stringify(cause)}`);
+            } catch {
+              parts.push(`cause=${String(cause)}`);
+            }
+          }
+          return parts.join(" ");
+        }
+        try {
+          return JSON.stringify(a);
+        } catch {
+          return String(a);
+        }
+      })
+      .join(" ");
+    Bun.write(Bun.stderr, `${prefix}${line}\n`);
+  };
+  // Intentional: we want console.* for user handlers to go to stderr.
+  // Overwrite the globals before any user code is loaded.
+  c.__stdoutLog = c.log;
+  c.log = toStderr("");
+  c.info = toStderr("");
+  c.warn = toStderr("[warn] ");
+  c.error = toStderr("[error] ");
+  c.debug = toStderr("[debug] ");
+}

package/src/types.ts

@@ -827,6 +827,42 @@ export interface Files {
   signedUrl(fileId: string, opts?: { ttlSecs?: number }): Promise<string>;
 }
 
+/**
+ * Shard tickets: short-lived, signed permission to join one realtime shard,
+ * with claims the shard's authorization hooks read without a database
+ * call. Check what the user may do here, then mint:
+ *
+ * ```ts
+ * export default mutation({
+ *   args: { characterId: v.id("Character") },
+ *   async handler(ctx, args) {
+ *     const c = await ctx.db.get("Character", args.characterId);
+ *     if (c?.ownerId !== ctx.auth.userId) throw ctx.error("FORBIDDEN", "not your character");
+ *     const shard = `zone-${c.zone}`;
+ *     const ticket = await ctx.shards.ticket(shard, {
+ *       subscriberId: c.id,
+ *       claims: { character: c.id, realm: c.realm },
+ *     });
+ *     return { shard, ticket };
+ *   },
+ * });
+ * ```
+ *
+ * The client passes the ticket when it connects (`connectShard(shard, {
+ * ticket })`). The shard rejects a ticket for another shard, another
+ * subscriber id, or past its expiry.
+ */
+export interface Shards {
+  /**
+   * Mint a ticket for `shardId`. `subscriberId` defaults to the calling
+   * user's id; `ttlSecs` defaults to 60 and is capped at 3600 by the host.
+   */
+  ticket(
+    shardId: string,
+    opts?: { subscriberId?: string; claims?: Record<string, unknown>; ttlSecs?: number },
+  ): Promise<string>;
+}
+
 /** Context for query handlers (read-only).
  *
  * NOTE: `ctx.llm` is NOT exposed here. Queries are reactive: a
@@ -852,6 +888,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;
   /**
    * Fires when the host cancels this call (idle timeout exceeded).
    * Thread it into `fetch(url, { signal: ctx.signal })` or SDK calls so
@@ -880,6 +918,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;
   /** Create a typed error that triggers rollback. */
   error(code: string, message: string): Error;
   /** Assert org membership (optionally a role) — see {@link RequireMember}. */
@@ -1053,6 +1093,8 @@ 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}. */
+  shards: Shards;
   /** Run a registered query within its own read transaction. */
   runQuery<T = unknown>(
     fnName: string,