bunite-core 0.8.1 → 0.9.0

package/src/rpc/renderer.ts

@@ -0,0 +1,82 @@
+import {
+  createConnection,
+  createFrameTransport,
+  createWebSocketPipe,
+  type Connection,
+  type Schema,
+  type SchemaShape,
+  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>;
+      runtime(): Promise<ClientOf<typeof import("./framework").RuntimeCap>>;
+      releaseRef(proxy: unknown): Promise<void>;
+    };
+  }
+}
+
+export * from "./index";
+export { Stream } from "./stream";
+
+let _webConn: Connection | null = null;
+let _webConnPromise: Promise<Connection> | null = null;
+
+function isNative(): boolean {
+  return typeof (globalThis as { __buniteWebviewId?: number }).__buniteWebviewId === "number";
+}
+
+function ensureWebConnection(path = "/rpc"): Promise<Connection> {
+  if (_webConn) return Promise.resolve(_webConn);
+  if (_webConnPromise) return _webConnPromise;
+  const attempt = (async () => {
+    const proto = location.protocol === "https:" ? "wss:" : "ws:";
+    const ws = new WebSocket(`${proto}//${location.host}${path}`);
+    ws.binaryType = "arraybuffer";
+    await new Promise<void>((resolve, reject) => {
+      ws.addEventListener("open", () => resolve(), { once: true });
+      ws.addEventListener("error", () => reject(new Error("web RPC ws connect failed")), { once: true });
+    });
+    const conn = createConnection({
+      transport: createFrameTransport(createWebSocketPipe(ws as unknown as WebSocketLike)),
+      mode: "web",
+      origin: location.origin,
+    });
+    _webConn = conn;
+    return conn;
+  })();
+  _webConnPromise = attempt;
+  attempt.catch(() => {
+    if (_webConnPromise === attempt) _webConnPromise = null;
+  });
+  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]>> {
+  if (isNative()) {
+    if (!window.host?.bootstrap) throw new Error("host preload not ready");
+    return window.host.bootstrap(schema, name);
+  }
+  const conn = await ensureWebConnection();
+  return conn.bootstrap(schema, name);
+}
+
+export async function serve<S extends SchemaShape>(descriptor: ServerDescriptor<S>): Promise<void> {
+  if (isNative()) {
+    if (!window.host?.serve) throw new Error("host preload not ready");
+    return window.host.serve(descriptor);
+  }
+  const conn = await ensureWebConnection();
+  conn.serve(descriptor);
+}

package/src/rpc/schema.ts

@@ -0,0 +1,246 @@
+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");
+declare const EXPORTED_CAP_BRAND: unique symbol;
+
+export type ReturnsKind = "type" | "cap" | "capArray" | "capRecord";
+
+export type CapRefToken<C extends CapDef<any, any>> = {
+  readonly [CAP_REF_TAG]: true;
+  readonly cap: C;
+};
+
+export type CapArrayToken<C extends CapDef<any, any>> = {
+  readonly [CAP_ARRAY_TAG]: true;
+  readonly cap: C;
+};
+
+export type CapRecordToken<C extends CapDef<any, any>> = {
+  readonly [CAP_RECORD_TAG]: true;
+  readonly cap: C;
+};
+
+export type AnyCapToken<C extends CapDef<any, any> = CapDef<any, any>> =
+  | CapRefToken<C>
+  | CapArrayToken<C>
+  | CapRecordToken<C>;
+
+function _cap<C extends CapDef<any, any>>(c: C): CapRefToken<C> {
+  return { [CAP_REF_TAG]: true, cap: c };
+}
+_cap.array = <C extends CapDef<any, any>>(c: C): CapArrayToken<C> => ({ [CAP_ARRAY_TAG]: true, cap: c });
+_cap.record = <C extends CapDef<any, any>>(c: C): CapRecordToken<C> => ({ [CAP_RECORD_TAG]: true, cap: c });
+export const cap = _cap;
+
+export function isCapRef(v: unknown): v is CapRefToken<any> {
+  return typeof v === "object" && v !== null && (v as any)[CAP_REF_TAG] === true;
+}
+export function isCapArray(v: unknown): v is CapArrayToken<any> {
+  return typeof v === "object" && v !== null && (v as any)[CAP_ARRAY_TAG] === true;
+}
+export function isCapRecord(v: unknown): v is CapRecordToken<any> {
+  return typeof v === "object" && v !== null && (v as any)[CAP_RECORD_TAG] === true;
+}
+export function returnsKindOf(v: unknown): ReturnsKind {
+  if (isCapRef(v)) return "cap";
+  if (isCapArray(v)) return "capArray";
+  if (isCapRecord(v)) return "capRecord";
+  return "type";
+}
+
+export interface CallDef<P = unknown, R = unknown> {
+  readonly [CALL_TAG]: true;
+  readonly idempotent: boolean;
+  readonly returns?: AnyCapToken;
+  readonly _phantom?: (p: P) => R;
+}
+
+export interface StreamDef<P = unknown, Y = unknown> {
+  readonly [STREAM_TAG]: true;
+  readonly hint?: Record<string, unknown>;
+  readonly _phantom?: (p: P) => Y;
+}
+
+export type MethodDef = CallDef<any, any> | StreamDef<any, any>;
+
+export function isCallDef(v: unknown): v is CallDef {
+  return typeof v === "object" && v !== null && (v as any)[CALL_TAG] === true;
+}
+export function isStreamDef(v: unknown): v is StreamDef {
+  return typeof v === "object" && v !== null && (v as any)[STREAM_TAG] === true;
+}
+
+export function call<P, C extends CapDef<any, any>>(
+  opts: { returns: CapRefToken<C>; idempotent?: boolean }
+): CallDef<P, CapRefToken<C>>;
+export function call<P, C extends CapDef<any, any>>(
+  opts: { returns: CapArrayToken<C>; idempotent?: boolean }
+): CallDef<P, CapArrayToken<C>>;
+export function call<P, C extends CapDef<any, any>>(
+  opts: { returns: CapRecordToken<C>; idempotent?: boolean }
+): CallDef<P, CapRecordToken<C>>;
+export function call<P = void, R = void>(opts?: { idempotent?: boolean }): CallDef<P, R>;
+export function call(opts?: { idempotent?: boolean; returns?: AnyCapToken }): CallDef<any, any> {
+  return {
+    [CALL_TAG]: true,
+    idempotent: !!opts?.idempotent,
+    returns: opts?.returns,
+  };
+}
+
+export function stream<P = void, Y = unknown>(opts?: { hint?: Record<string, unknown> }): StreamDef<P, Y> {
+  return { [STREAM_TAG]: true, hint: opts?.hint };
+}
+
+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 methods: M;
+  readonly disposal: D;
+}
+
+export function defineCap<M extends MethodsRecord, D extends DisposalSpec<M> | undefined = undefined>(
+  methods: M,
+  opts?: { disposal?: D }
+): CapDef<M, D> {
+  return {
+    [CAP_TAG]: true,
+    methods,
+    disposal: (opts?.disposal as D) ?? (undefined as D),
+  };
+}
+
+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>[];
+}
+
+export interface Schema<S extends SchemaShape = SchemaShape> {
+  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;
+}
+
+let topologyHashImpl: (s: Schema<any>) => Promise<string> = () => {
+  throw new Error("schema.topologyHash bound after hash.ts import");
+};
+
+export function _bindTopologyHash(fn: (s: Schema<any>) => Promise<string>) {
+  topologyHashImpl = fn;
+}
+
+export function isSchema(v: unknown): v is Schema {
+  return typeof v === "object" && v !== null && (v as any)[SCHEMA_TAG] === true;
+}
+
+export interface ExportedCap<C extends CapDef<any, any>> {
+  readonly [EXPORTED_CAP_BRAND]: true;
+  readonly cap: C;
+  readonly capId: number;
+  readonly typeId: number;
+}
+
+export interface CallCtx {
+  callId: number;
+  peerId: string;
+  attestation: Attestation;
+  signal: AbortSignal;
+  deadline?: number;
+  context?: Record<string, string>;
+  exportCap<C extends CapDef<any, any>>(capDef: C, impl: ImplOf<C>): ExportedCap<C>;
+}
+
+export interface Attestation {
+  origin: string;
+  topOrigin: string;
+  partition: string;
+  isAppRes: boolean;
+  isMainFrame: boolean;
+  userGesture: boolean;
+  level: "app-internal" | "trusted-origin" | "untrusted";
+}
+
+type MaybePromise<T> = T | Promise<T>;
+
+type ServerReturn<R> =
+  R extends CapRefToken<infer C> ? ExportedCap<C> :
+  R extends CapArrayToken<infer C> ? ExportedCap<C>[] :
+  R extends CapRecordToken<infer C> ? Record<string, ExportedCap<C>> :
+  R;
+
+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
+      : ClientOf<C>[]
+    : ClientOf<C>[] :
+  R extends CapRecordToken<infer C> ? Record<string, ClientOf<C>> :
+  R;
+
+export type Stream<T> = AsyncIterable<T> & Disposable & { cancel(): void };
+
+export type ClientOf<T> = T extends CapDef<infer M, infer D>
+  ? {
+      [K in keyof M]: M[K] extends CallDef<infer P, infer R>
+        ? [P] extends [void] ? () => Promise<ClientReturn<R>>
+        : (params: P) => Promise<ClientReturn<R>>
+        : M[K] extends StreamDef<infer P, infer Y>
+          ? [P] extends [void] ? () => Stream<Y>
+          : (params: P) => Stream<Y>
+          : never;
+    } & ([D] extends [{ async: true }] ? AsyncDisposable : [D] extends [DisposalSpec] ? Disposable : {})
+  : never;
+
+export type ImplOf<T> = T extends CapDef<infer M, any>
+  ? {
+      [K in keyof M]: M[K] extends CallDef<infer P, infer R>
+        ? (params: P, ctx: CallCtx) => MaybePromise<ServerReturn<R>>
+        : M[K] extends StreamDef<infer P, infer Y>
+          ? (params: P, ctx: CallCtx) => Stream<Y>
+          : never;
+    }
+  : never;
+
+export function methodKeys(cap: CapDef<any, any>): string[] {
+  return Object.keys(cap.methods);
+}

package/src/rpc/stream.ts

@@ -0,0 +1,72 @@
+import type { Stream as StreamType } from "./schema";
+
+type Setup<T> = (emit: (chunk: T) => void, signal: AbortSignal) => void | (() => void);
+
+class ServerStream<T> implements AsyncIterable<T>, Disposable {
+  private readonly buffer: T[] = [];
+  private readonly waiters: Array<{ resolve: (r: IteratorResult<T>) => void; reject: (e: unknown) => void }> = [];
+  private readonly ctrl = new AbortController();
+  private cleanup?: () => void;
+  private ended = false;
+  private failure: unknown = null;
+
+  constructor(setup: Setup<T>) {
+    const emit = (chunk: T) => {
+      if (this.ended || this.failure) return;
+      const w = this.waiters.shift();
+      if (w) {
+        w.resolve({ value: chunk, done: false });
+        return;
+      }
+      this.buffer.push(chunk);
+    };
+    try {
+      const ret = setup(emit, this.ctrl.signal);
+      if (typeof ret === "function") this.cleanup = ret;
+    } catch (err) {
+      this.failure = err;
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    return {
+      next: async (): Promise<IteratorResult<T>> => {
+        if (this.buffer.length > 0) {
+          return { value: this.buffer.shift()!, done: false };
+        }
+        if (this.failure) throw this.failure;
+        if (this.ended) return { value: undefined as unknown as T, done: true };
+        return new Promise<IteratorResult<T>>((resolve, reject) => this.waiters.push({ resolve, reject }));
+      },
+      return: async (): Promise<IteratorResult<T>> => {
+        this.dispose();
+        return { value: undefined as unknown as T, done: true };
+      },
+    };
+  }
+
+  cancel(): void {
+    this.dispose();
+  }
+
+  [Symbol.dispose](): void {
+    this.dispose();
+  }
+
+  private dispose(): void {
+    if (this.ended) return;
+    this.ended = true;
+    this.ctrl.abort();
+    try { this.cleanup?.(); } catch { /* swallow */ }
+    while (this.waiters.length > 0) {
+      const w = this.waiters.shift()!;
+      w.resolve({ value: undefined as unknown as T, done: true });
+    }
+  }
+}
+
+export const Stream = {
+  from<T>(setup: Setup<T>): StreamType<T> {
+    return new ServerStream(setup) as unknown as StreamType<T>;
+  },
+};

package/src/rpc/transport.ts

@@ -0,0 +1,81 @@
+import { type Frame, createCodec, isFrame } from "./wire";
+import type { Transport } from "./peer";
+
+export interface BytesPipe {
+  send(bytes: Uint8Array): void;
+  setReceive(handler: (bytes: Uint8Array) => void): void;
+  close(): void;
+}
+
+export interface FrameTransportOptions {
+  onProtocolError?(reason: string): void;
+}
+
+export function createFrameTransport(pipe: BytesPipe, opts: FrameTransportOptions = {}): Transport {
+  const codec = createCodec();
+  let handler: ((frame: Frame) => void) | undefined;
+
+  pipe.setReceive((bytes) => {
+    let frame: unknown;
+    try {
+      frame = codec.unpackr.unpack(bytes);
+    } catch (err) {
+      opts.onProtocolError?.(`unpack failed: ${err instanceof Error ? err.message : String(err)}`);
+      pipe.close();
+      return;
+    }
+    if (!isFrame(frame)) {
+      opts.onProtocolError?.("malformed frame");
+      pipe.close();
+      return;
+    }
+    handler?.(frame);
+  });
+
+  return {
+    send(frame) {
+      const bytes = codec.packr.pack(frame);
+      pipe.send(bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes));
+    },
+    setReceive(h) {
+      handler = h;
+    },
+    close() {
+      pipe.close();
+    },
+  };
+}
+
+export interface WebSocketLike {
+  send(data: Uint8Array | ArrayBuffer): unknown;
+  addEventListener(type: "message", listener: (event: { data: ArrayBuffer | Uint8Array | Blob | string }) => void): void;
+  removeEventListener?(type: "message", listener: (event: { data: ArrayBuffer | Uint8Array | Blob | string }) => void): void;
+  close?(): void;
+}
+
+export function createWebSocketPipe(ws: WebSocketLike): BytesPipe {
+  if ("binaryType" in ws) {
+    try { (ws as { binaryType?: string }).binaryType = "arraybuffer"; } catch { /* readonly in some envs */ }
+  }
+  let handler: ((bytes: Uint8Array) => void) | undefined;
+  const onMessage = (event: { data: ArrayBuffer | Uint8Array | Blob | string }) => {
+    if (!handler) return;
+    const d = event.data;
+    if (d instanceof Uint8Array) { handler(d); return; }
+    if (d instanceof ArrayBuffer) { handler(new Uint8Array(d)); return; }
+    if (typeof Blob !== "undefined" && d instanceof Blob) {
+      void d.arrayBuffer().then((buf) => handler?.(new Uint8Array(buf)));
+      return;
+    }
+  };
+  ws.addEventListener("message", onMessage);
+  return {
+    send(bytes) { ws.send(bytes); },
+    setReceive(h) { handler = h; },
+    close() {
+      ws.removeEventListener?.("message", onMessage);
+      ws.close?.();
+    },
+  };
+}
+

package/src/rpc/wire.ts

@@ -0,0 +1,150 @@
+import { Packr, Unpackr, addExtension } from "msgpackr";
+import type { IpcStatus } from "./error";
+
+export type u32 = number;
+export type u53 = number;
+
+export const CAP_REF_EXT = 0x50;
+
+export class CapRef {
+  constructor(public readonly capId: u32) {}
+}
+
+export type Target = { kind: "cap"; id: u32 };
+
+export interface CallMeta {
+  parentCallId?: u53;
+  deadlineMs?: u32;
+  context?: Record<string, string>;
+  topologyHash?: string;
+}
+
+export type StreamEvent =
+  | { ev: "next"; value: unknown }
+  | { ev: "credit"; credit: { messages?: u32 } }
+  | { ev: "end" }
+  | { ev: "error"; error: IpcStatus };
+
+export type Frame =
+  | {
+      op: "hello";
+      v: 1;
+      mode: "native" | "web";
+      features: string[];
+      maxBytes: number;
+      origin: string;
+    }
+  | { op: "goaway"; reason?: string; error?: IpcStatus }
+  | {
+      op: "call";
+      id: u53;
+      target: Target;
+      method: u32;
+      args: unknown;
+      meta?: CallMeta;
+    }
+  | { op: "result"; id: u53; ok: true; value: unknown }
+  | { 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 }[] };
+
+export type CallFrame = Extract<Frame, { op: "call" }>;
+export type ResultFrame = Extract<Frame, { op: "result" }>;
+export type StreamFrame = Extract<Frame, { op: "stream" }>;
+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" }>;
+
+const OPS = new Set<Frame["op"]>([
+  "hello",
+  "goaway",
+  "call",
+  "result",
+  "cancel",
+  "stream",
+  "drop",
+]);
+
+export function isFrame(value: unknown): value is Frame {
+  if (typeof value !== "object" || value === null) return false;
+  const f = value as Record<string, unknown>;
+  const op = f.op;
+  if (typeof op !== "string" || !OPS.has(op as Frame["op"])) return false;
+  switch (op as Frame["op"]) {
+    case "hello":
+      return f.v === 1 && (f.mode === "native" || f.mode === "web")
+        && Array.isArray(f.features) && typeof f.maxBytes === "number" && typeof f.origin === "string";
+    case "goaway":
+      return f.reason === undefined || typeof f.reason === "string";
+    case "call":
+      return typeof f.id === "number" && typeof f.method === "number"
+        && typeof f.target === "object" && f.target !== null
+        && (f.target as { kind?: unknown }).kind === "cap"
+        && typeof (f.target as { id?: unknown }).id === "number";
+    case "result":
+      return typeof f.id === "number" && (f.ok === true || f.ok === false);
+    case "cancel":
+      return typeof f.id === "number";
+    case "stream":
+      return typeof f.id === "number" && typeof f.ev === "string"
+        && (f.ev === "next" || f.ev === "credit" || f.ev === "end" || f.ev === "error");
+    case "drop":
+      return Array.isArray(f.caps);
+  }
+}
+
+let extensionsRegistered = false;
+function registerExtensions() {
+  if (extensionsRegistered) return;
+  extensionsRegistered = true;
+  addExtension({
+    Class: CapRef,
+    type: CAP_REF_EXT,
+    pack: (cap: CapRef) => packCapId(cap.capId),
+    unpack: (buf: Buffer | Uint8Array) => new CapRef(readVarUint(buf)),
+  });
+}
+
+export interface CodecPair {
+  packr: Packr;
+  unpackr: Unpackr;
+}
+
+export function createCodec(): CodecPair {
+  registerExtensions();
+  return {
+    packr: new Packr({ useRecords: true, sequential: true, moreTypes: true }),
+    unpackr: new Unpackr({ useRecords: true, sequential: true, moreTypes: true }),
+  };
+}
+
+function packCapId(capId: number): Uint8Array {
+  const buf = new Uint8Array(5);
+  let n = capId >>> 0;
+  let i = 0;
+  while (n >= 0x80) {
+    buf[i++] = (n & 0x7f) | 0x80;
+    n >>>= 7;
+  }
+  buf[i++] = n & 0x7f;
+  return buf.subarray(0, i);
+}
+
+const MAX_VARUINT_BYTES = 5;
+function readVarUint(buf: Buffer | Uint8Array): number {
+  let result = 0;
+  let shift = 0;
+  const limit = Math.min(buf.length, MAX_VARUINT_BYTES);
+  for (let i = 0; i < limit; i++) {
+    const byte = buf[i];
+    result |= (byte & 0x7f) << shift;
+    if ((byte & 0x80) === 0) return result >>> 0;
+    shift += 7;
+  }
+  throw new Error("Truncated or oversize varuint");
+}
+
+export const DEFAULT_MAX_BYTES = 64 * 1024 * 1024;
+export const PROTOCOL_VERSION = 1;