@pylonsync/functions 0.11.6 → 0.13.0

package/src/types.ts

@@ -827,6 +827,81 @@ 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>;
+
+  /**
+   * 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).
  *
  * NOTE: `ctx.llm` is NOT exposed here. Queries are reactive: a
@@ -852,6 +927,8 @@ export interface QueryCtx<R extends AuthRequirement = "optional"> {
   requireMember: RequireMember;
   /** Signed file-download URLs — see {@link Files}. */
   files: Files;
+  /** 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
@@ -880,6 +957,8 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
   workflows: Workflows;
   /** Signed file-download URLs — see {@link Files}. */
   files: Files;
+  /** 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}. */
@@ -1053,6 +1132,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   env: Record<string, string>;
   /** Signed file-download URLs — see {@link Files}. */
   files: Files;
+  /** 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,