bunite-core 0.9.0 → 0.10.0

package/src/rpc/renderer.ts

@@ -3,23 +3,22 @@ import {
   createFrameTransport,
   createWebSocketPipe,
   type Connection,
+  type CapDef,
   type Schema,
-  type SchemaShape,
+  type SchemaRoots,
   type ClientOf,
-  type ServerDescriptor,
   type WebSocketLike,
 } from "./index";
 
 declare global {
   interface Window {
     host?: {
-      bootstrap<S extends SchemaShape, K extends keyof S["roots"] & string>(
-        schema: Schema<S>,
-        name: K
-      ): Promise<ClientOf<S["roots"][K]>>;
-      serve<S extends SchemaShape>(descriptor: ServerDescriptor<S>): Promise<void>;
+      bootstrap<C extends CapDef<any, any>>(cap: C): Promise<ClientOf<C>>;
+      bootstrap<R extends SchemaRoots>(schema: Schema<R>): Promise<{ [K in keyof R]: ClientOf<R[K]> }>;
       runtime(): Promise<ClientOf<typeof import("./framework").RuntimeCap>>;
       releaseRef(proxy: unknown): Promise<void>;
+      /** Full Connection for renderer-as-server (serve / serveAll / unserve / replace / on). */
+      getConnection(): Promise<Connection>;
     };
   }
 }
@@ -60,23 +59,22 @@ function ensureWebConnection(path = "/rpc"): Promise<Connection> {
   return attempt;
 }
 
-export async function bootstrap<S extends SchemaShape, K extends keyof S["roots"] & string>(
-  schema: Schema<S>,
-  name: K
-): Promise<ClientOf<S["roots"][K]>> {
+export function bootstrap<C extends CapDef<any, any>>(cap: C): Promise<ClientOf<C>>;
+export function bootstrap<R extends SchemaRoots>(schema: Schema<R>): Promise<{ [K in keyof R]: ClientOf<R[K]> }>;
+export async function bootstrap(target: CapDef<any, any> | Schema<any>): Promise<unknown> {
   if (isNative()) {
     if (!window.host?.bootstrap) throw new Error("host preload not ready");
-    return window.host.bootstrap(schema, name);
+    return (window.host.bootstrap as (t: unknown) => Promise<unknown>)(target);
   }
   const conn = await ensureWebConnection();
-  return conn.bootstrap(schema, name);
+  return (conn.bootstrap as (t: unknown) => Promise<unknown>)(target);
 }
 
-export async function serve<S extends SchemaShape>(descriptor: ServerDescriptor<S>): Promise<void> {
+/** Returns the underlying Connection — for renderer-as-server (`conn.serve(cap, impl)`), observability hooks (`conn.on(...)`), etc. */
+export async function getConnection(): Promise<Connection> {
   if (isNative()) {
-    if (!window.host?.serve) throw new Error("host preload not ready");
-    return window.host.serve(descriptor);
+    if (!window.host?.getConnection) throw new Error("host preload not ready");
+    return window.host.getConnection();
   }
-  const conn = await ensureWebConnection();
-  conn.serve(descriptor);
+  return ensureWebConnection();
 }

package/src/rpc/schema.ts

@@ -1,10 +1,11 @@
-const CALL_TAG = Symbol("CallDef");
-const STREAM_TAG = Symbol("StreamDef");
-const CAP_TAG = Symbol("CapDef");
-const CAP_REF_TAG = Symbol("CapRefToken");
-const CAP_ARRAY_TAG = Symbol("CapArrayToken");
-const CAP_RECORD_TAG = Symbol("CapRecordToken");
-const SCHEMA_TAG = Symbol("Schema");
+// Symbol.for() — shared identity across separately-built bundles (preload vs renderer).
+const CALL_TAG = Symbol.for("bunite.rpc.CallDef");
+const STREAM_TAG = Symbol.for("bunite.rpc.StreamDef");
+const CAP_TAG = Symbol.for("bunite.rpc.CapDef");
+const CAP_REF_TAG = Symbol.for("bunite.rpc.CapRefToken");
+const CAP_ARRAY_TAG = Symbol.for("bunite.rpc.CapArrayToken");
+const CAP_RECORD_TAG = Symbol.for("bunite.rpc.CapRecordToken");
+const SCHEMA_TAG = Symbol.for("bunite.rpc.Schema");
 declare const EXPORTED_CAP_BRAND: unique symbol;
 
 export type ReturnsKind = "type" | "cap" | "capArray" | "capRecord";
@@ -96,25 +97,35 @@ export function stream<P = void, Y = unknown>(opts?: { hint?: Record<string, unk
   return { [STREAM_TAG]: true, hint: opts?.hint };
 }
 
+// Disposal: method only. Sync Disposable — wire drop is fire-and-forget.
 export interface DisposalSpec<M extends MethodsRecord = MethodsRecord> {
   method: keyof M & string;
-  async?: boolean;
 }
 
 export type MethodsRecord = Record<string, MethodDef>;
 
 export interface CapDef<M extends MethodsRecord = MethodsRecord, D extends DisposalSpec<M> | undefined = undefined> {
   readonly [CAP_TAG]: true;
+  readonly name: string;
+  readonly version?: string;
   readonly methods: M;
   readonly disposal: D;
 }
 
+export interface DefineCapOpts<M extends MethodsRecord, D extends DisposalSpec<M> | undefined> {
+  version?: string | number;
+  disposal?: D;
+}
+
 export function defineCap<M extends MethodsRecord, D extends DisposalSpec<M> | undefined = undefined>(
+  name: string,
   methods: M,
-  opts?: { disposal?: D }
+  opts?: DefineCapOpts<M, D>
 ): CapDef<M, D> {
   return {
     [CAP_TAG]: true,
+    name,
+    version: opts?.version != null ? String(opts.version) : undefined,
     methods,
     disposal: (opts?.disposal as D) ?? (undefined as D),
   };
@@ -124,47 +135,20 @@ export function isCapDef(v: unknown): v is CapDef {
   return typeof v === "object" && v !== null && (v as any)[CAP_TAG] === true;
 }
 
-export interface SchemaShape {
-  roots: Record<string, CapDef<any, any>>;
-  caps?: readonly CapDef<any, any>[];
-}
+// Schema = grouping sugar (Record<rootName, CapDef>). TS atomicity for serveAll.
+export type SchemaRoots = Record<string, CapDef<any, any>>;
 
-export interface Schema<S extends SchemaShape = SchemaShape> {
+export interface Schema<R extends SchemaRoots = SchemaRoots> {
   readonly [SCHEMA_TAG]: true;
-  readonly roots: S["roots"];
-  readonly caps: readonly CapDef<any, any>[];
-  topologyHash(): Promise<string>;
-  serve(impls: ImplsOf<S>): ServerDescriptor<S>;
-}
-
-export type ImplsOf<S extends SchemaShape> = {
-  [K in keyof S["roots"]]: ImplOf<S["roots"][K]>;
-};
-
-export interface ServerDescriptor<S extends SchemaShape = SchemaShape> {
-  readonly schema: Schema<S>;
-  readonly impls: ImplsOf<S>;
-}
-
-export function defineSchema<S extends SchemaShape>(shape: S): Schema<S> {
-  const schema: Schema<S> = {
-    [SCHEMA_TAG]: true,
-    roots: shape.roots,
-    caps: shape.caps ?? [],
-    topologyHash: () => topologyHashImpl(schema),
-    serve(impls) {
-      return { schema, impls };
-    },
-  };
-  return schema;
+  readonly roots: R;
 }
 
-let topologyHashImpl: (s: Schema<any>) => Promise<string> = () => {
-  throw new Error("schema.topologyHash bound after hash.ts import");
+export type ImplsOf<R extends SchemaRoots> = {
+  [K in keyof R]: ImplOf<R[K]>;
 };
 
-export function _bindTopologyHash(fn: (s: Schema<any>) => Promise<string>) {
-  topologyHashImpl = fn;
+export function defineSchema<R extends SchemaRoots>(roots: R): Schema<R> {
+  return { [SCHEMA_TAG]: true, roots };
 }
 
 export function isSchema(v: unknown): v is Schema {
@@ -210,8 +194,7 @@ export type ClientReturn<R> =
   R extends CapRefToken<infer C> ? ClientOf<C> :
   R extends CapArrayToken<infer C> ?
     C extends CapDef<any, infer D>
-      ? [D] extends [{ async: true }] ? ClientOf<C>[] & AsyncDisposable
-      : [D] extends [DisposalSpec] ? ClientOf<C>[] & Disposable
+      ? [D] extends [DisposalSpec] ? ClientOf<C>[] & Disposable
       : ClientOf<C>[]
     : ClientOf<C>[] :
   R extends CapRecordToken<infer C> ? Record<string, ClientOf<C>> :
@@ -228,7 +211,7 @@ export type ClientOf<T> = T extends CapDef<infer M, infer D>
           ? [P] extends [void] ? () => Stream<Y>
           : (params: P) => Stream<Y>
           : never;
-    } & ([D] extends [{ async: true }] ? AsyncDisposable : [D] extends [DisposalSpec] ? Disposable : {})
+    } & ([D] extends [DisposalSpec] ? Disposable : {})
   : never;
 
 export type ImplOf<T> = T extends CapDef<infer M, any>

package/src/rpc/wire.ts

@@ -16,7 +16,6 @@ export interface CallMeta {
   parentCallId?: u53;
   deadlineMs?: u32;
   context?: Record<string, string>;
-  topologyHash?: string;
 }
 
 export type StreamEvent =
@@ -39,7 +38,7 @@ export type Frame =
       op: "call";
       id: u53;
       target: Target;
-      method: u32;
+      method: string;
       args: unknown;
       meta?: CallMeta;
     }
@@ -47,7 +46,8 @@ export type Frame =
   | { op: "result"; id: u53; ok: false; error: IpcStatus }
   | { op: "cancel"; id: u53; reason?: string }
   | ({ op: "stream"; id: u53 } & StreamEvent)
-  | { op: "drop"; caps: { id: u32; delta: u32 }[] };
+  | { op: "drop"; caps: { id: u32; delta: u32 }[] }
+  | { op: "cap_revoked"; capIds: u32[] };
 
 export type CallFrame = Extract<Frame, { op: "call" }>;
 export type ResultFrame = Extract<Frame, { op: "result" }>;
@@ -56,6 +56,7 @@ export type CancelFrame = Extract<Frame, { op: "cancel" }>;
 export type DropFrame = Extract<Frame, { op: "drop" }>;
 export type HelloFrame = Extract<Frame, { op: "hello" }>;
 export type GoAwayFrame = Extract<Frame, { op: "goaway" }>;
+export type CapRevokedFrame = Extract<Frame, { op: "cap_revoked" }>;
 
 const OPS = new Set<Frame["op"]>([
   "hello",
@@ -65,6 +66,7 @@ const OPS = new Set<Frame["op"]>([
   "cancel",
   "stream",
   "drop",
+  "cap_revoked",
 ]);
 
 export function isFrame(value: unknown): value is Frame {
@@ -79,7 +81,7 @@ export function isFrame(value: unknown): value is Frame {
     case "goaway":
       return f.reason === undefined || typeof f.reason === "string";
     case "call":
-      return typeof f.id === "number" && typeof f.method === "number"
+      return typeof f.id === "number" && typeof f.method === "string"
         && typeof f.target === "object" && f.target !== null
         && (f.target as { kind?: unknown }).kind === "cap"
         && typeof (f.target as { id?: unknown }).id === "number";
@@ -92,6 +94,12 @@ export function isFrame(value: unknown): value is Frame {
         && (f.ev === "next" || f.ev === "credit" || f.ev === "end" || f.ev === "error");
     case "drop":
       return Array.isArray(f.caps);
+    case "cap_revoked":
+      if (!Array.isArray(f.capIds)) return false;
+      for (const id of f.capIds) {
+        if (typeof id !== "number" || !Number.isInteger(id) || id < 0 || id > 0xFFFFFFFF) return false;
+      }
+      return true;
   }
 }
 
@@ -148,3 +156,9 @@ function readVarUint(buf: Buffer | Uint8Array): number {
 
 export const DEFAULT_MAX_BYTES = 64 * 1024 * 1024;
 export const PROTOCOL_VERSION = 1;
+
+/** Reserved cap-name prefix for framework caps. User caps starting with this prefix are rejected. */
+export const FRAMEWORK_NAME_PREFIX = "bunite.";
+
+/** Synthetic method on cap-id 0 — dispatches to the bootstrap registry. */
+export const BOOTSTRAP_METHOD = "bootstrap";

package/src/rpc/hash.ts

@@ -1,142 +0,0 @@
-import {
-  type Schema,
-  type CapDef,
-  type MethodDef,
-  type DisposalSpec,
-  type AnyCapToken,
-  type ReturnsKind,
-  isCallDef,
-  isStreamDef,
-  isCapRef,
-  isCapArray,
-  isCapRecord,
-  _bindTopologyHash,
-} from "./schema";
-
-type CanonicalReturns =
-  | { kind: "type" }
-  | { kind: "cap" | "capArray" | "capRecord"; capIndex: number };
-
-type CanonicalMethod =
-  | { name: string; kind: "call"; idempotent: boolean; returns: CanonicalReturns }
-  | { name: string; kind: "stream" };
-
-type CanonicalCap = {
-  methods: CanonicalMethod[];
-  disposal?: { method: string; async: boolean };
-};
-
-type CanonicalRoot = {
-  name: string;
-  capIndex: number;
-};
-
-type CanonicalSchema = {
-  v: 1;
-  roots: CanonicalRoot[];
-  caps: CanonicalCap[];
-};
-
-export function canonicalize(schema: Schema<any>): CanonicalSchema {
-  const capIndex = new Map<CapDef<any, any>, number>();
-  const caps: CanonicalCap[] = [];
-
-  for (const declared of schema.caps) {
-    if (capIndex.has(declared)) continue;
-    capIndex.set(declared, caps.length);
-    caps.push(null as unknown as CanonicalCap);
-  }
-
-  const intern = (c: CapDef<any, any>): number => {
-    const existing = capIndex.get(c);
-    if (existing !== undefined) return existing;
-    const idx = caps.length;
-    capIndex.set(c, idx);
-    caps.push(null as unknown as CanonicalCap);
-    return idx;
-  };
-
-  for (let i = 0; i < caps.length; i++) {
-    if (caps[i] !== null) continue;
-    const declared = schema.caps[i];
-    caps[i] = capToCanonical(declared, intern);
-  }
-
-  const roots: CanonicalRoot[] = Object.keys(schema.roots).map((name) => ({
-    name,
-    capIndex: intern(schema.roots[name]),
-  }));
-
-  for (let i = 0; i < caps.length; i++) {
-    if (caps[i] !== null) continue;
-    const cap = [...capIndex.keys()][i];
-    caps[i] = capToCanonical(cap, intern);
-  }
-
-  return { v: 1, roots, caps };
-}
-
-function capToCanonical(c: CapDef<any, any>, intern: (c: CapDef<any, any>) => number): CanonicalCap {
-  const methods: CanonicalMethod[] = Object.keys(c.methods).map((name) => {
-    const m = c.methods[name] as MethodDef;
-    if (isCallDef(m)) {
-      return {
-        name,
-        kind: "call",
-        idempotent: m.idempotent,
-        returns: returnsToCanonical(m.returns, intern),
-      };
-    }
-    if (isStreamDef(m)) {
-      return { name, kind: "stream" };
-    }
-    throw new Error(`Unknown method def for "${name}"`);
-  });
-
-  const result: CanonicalCap = { methods };
-  const disposal = c.disposal as DisposalSpec | undefined;
-  if (disposal) {
-    result.disposal = { method: disposal.method, async: !!disposal.async };
-  }
-  return result;
-}
-
-function returnsToCanonical(
-  ret: AnyCapToken | undefined,
-  intern: (c: CapDef<any, any>) => number
-): CanonicalReturns {
-  if (!ret) return { kind: "type" };
-  if (isCapRef(ret)) return { kind: "cap", capIndex: intern(ret.cap) };
-  if (isCapArray(ret)) return { kind: "capArray", capIndex: intern(ret.cap) };
-  if (isCapRecord(ret)) return { kind: "capRecord", capIndex: intern(ret.cap) };
-  return { kind: "type" };
-}
-
-function canonicalJSON(value: unknown): string {
-  if (Array.isArray(value)) {
-    return "[" + value.map(canonicalJSON).join(",") + "]";
-  }
-  if (value && typeof value === "object") {
-    const keys = Object.keys(value as object).sort();
-    return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalJSON((value as Record<string, unknown>)[k])).join(",") + "}";
-  }
-  return JSON.stringify(value);
-}
-
-export async function topologyHash(schema: Schema<any>): Promise<string> {
-  const canonical = canonicalize(schema);
-  const json = canonicalJSON(canonical);
-  const bytes = new TextEncoder().encode(json);
-  const digest = await crypto.subtle.digest("SHA-256", bytes);
-  return toHex(new Uint8Array(digest));
-}
-
-function toHex(bytes: Uint8Array): string {
-  let out = "";
-  for (let i = 0; i < bytes.length; i++) {
-    out += bytes[i].toString(16).padStart(2, "0");
-  }
-  return out;
-}
-
-_bindTopologyHash(topologyHash);