SnowLuma v2.4.2 source snapshot

packages/protocol/src/oidb-service.ts

@@ -0,0 +1,225 @@
+// OIDB service layer — the next architectural revision on top of the
+// area-grouped Api facade pattern (InteractionApi / ProfileApi / …).
+//
+// Each OIDB cmd is modelled as a TypeScript namespace whose exported
+// members ARE the `OidbCallSpec` shape (structural typing makes this
+// implicit — no `implements` clause needed). The namespace also exports
+// a thin `invoke()` that hands itself to `invokeOidb` for dispatch.
+//
+// Why namespace-as-spec instead of class:
+//   - stateless: no `new` overhead at the call site
+//   - no `this` binding, no implicit lifecycle
+//   - tree-shakes per-export (unused services drop out of the bundle)
+//   - spec ↔ code 1:1 (one file = one (cmd, subcmd) tuple)
+//
+// Why Pick-style minimal `Deps` per service:
+//   - Interface Segregation: a wire-only cmd doesn't see identity/events
+//   - tests mock only what's used (typically just `sendRawPacket`)
+//   - changes to BridgeContext don't bleed into services
+//   - the dep list IS the documentation of side-effects
+//
+// Why `ctx` threads into serialize/deserialize:
+//   - the namespace is then genuinely self-contained — "what does this
+//     cmd do on the wire + what state does it touch" lives in one file
+//   - earlier shape forced an `invoke = { ...Self, serialize: p =>
+//     localSerialize(p, await ctx.resolveUserUid(...)) }` rewrite for
+//     every cmd that needed identity/uid resolution; ctx-aware
+//     serialize collapses that to a single async serialize.
+//   - serialize is now `TReq | Promise<TReq>` so async lookups
+//     (resolveUserUid, identity reads) happen in place.
+
+import { protobuf_decode } from '@snowluma/proton';
+import type { OidbBase, OidbBaseMeta } from '@snowluma/proto-defs/oidb';
+import type { SendPacketResult } from '@snowluma/common/packet-sender';
+
+import { makeOidbEnvelope } from './bridge-oidb';
+
+/**
+ * Capability narrow enough for any wire-only OIDB call. Anything that
+ * also needs identity / event bus / upload cache declares those via
+ * `Pick<BridgeContext, 'identity' | …>` and intersects with this.
+ */
+export interface OidbSender {
+    sendRawPacket(
+        serviceCmd: string,
+        body: Uint8Array,
+        timeoutMs?: number,
+    ): Promise<SendPacketResult>;
+}
+
+/**
+ * The shape every cmd namespace exports. Structural typing means a
+ * namespace whose top-level exports match these names + types IS an
+ * `OidbCallSpec` — no `implements` clause needed.
+ *
+ * `TCtx` is the namespace's capability surface — always at least
+ * `OidbSender` (so `invokeOidb` can dispatch through it) plus any
+ * `Pick<BridgeContext, ...>` slices the cmd actually needs.
+ *
+ * One of `subCommand` (static) or `resolveSubCommand` (dynamic from
+ * params and context) must be present. `resolveSubCommand` wins if both
+ * are given. `resolveCommand` likewise wins over static `command`.
+ */
+export interface OidbCallSpec<TCtx extends OidbSender, TReq, TResp, TParams, TResult> {
+    command: number;
+    resolveCommand?(params: TParams, ctx: TCtx): number;
+    subCommand?: number;
+    resolveSubCommand?(params: TParams, ctx: TCtx): number;
+    /** Packet and body envelope codes treated as success in addition to 0. */
+    acceptedEnvelopeCodes?: readonly number[];
+    /** Set OIDB envelope `reserved = 1` (UIN-form variant, see makeOidbEnvelope's isUid). */
+    uinForm?: boolean;
+    /** Override the default `OidbSvcTrpcTcp.0xNNNN_N` wire name. A few
+     *  cmds route through different SSO names (e.g. 0xE17_0 lives at
+     *  `MQUpdateSvc_com_qq_ti.web.OidbSvc.0xe17_0`); supply a function
+     *  that takes the resolved `(cmd, subCmd)` and returns the actual
+     *  wire name. Omit for the default scheme. */
+    wireName?(command: number, subCommand: number): string;
+    /** Business params → wire-shaped request body. May be async (e.g.
+     *  when ctx.resolveUserUid hits the cache or the network). */
+    serialize(ctx: TCtx, params: TParams): TReq | Promise<TReq>;
+    /** Wire-shaped response body → business result. */
+    deserialize(ctx: TCtx, body: TResp): TResult;
+    /** Per-type protobuf encoder — concrete generic call so the Vite plugin can monomorphize. */
+    encode(env: OidbBase<TReq>): Uint8Array;
+    /** Per-type protobuf decoder. */
+    decode(bytes: Uint8Array): OidbBase<TResp>;
+}
+
+function resolveOidbCall<TCtx extends OidbSender, TReq, TResp, TParams, TResult>(
+    spec: OidbCallSpec<TCtx, TReq, TResp, TParams, TResult>,
+    params: TParams,
+    ctx: TCtx,
+): { command: number; subCommand: number } {
+    const command = spec.resolveCommand ? spec.resolveCommand(params, ctx) : spec.command;
+    const subCommand = spec.resolveSubCommand
+        ? spec.resolveSubCommand(params, ctx)
+        : spec.subCommand!;
+    return { command, subCommand };
+}
+
+function isAcceptedEnvelopeCode<TCtx extends OidbSender, TReq, TResp, TParams, TResult>(
+    spec: OidbCallSpec<TCtx, TReq, TResp, TParams, TResult>,
+    code: number | null | undefined,
+): boolean {
+    if (code == null || code === 0) {
+        return true;
+    }
+
+    return spec.acceptedEnvelopeCodes?.includes(code) === true;
+}
+
+export class OidbError extends Error {
+    constructor(
+        readonly code: number,
+        readonly serverMsg: string,
+        readonly command: number,
+        readonly subCommand: number,
+    ) {
+        super(`OIDB error ${code} on 0x${command.toString(16)}_${subCommand}: ${serverMsg}`);
+        this.name = 'OidbError';
+    }
+}
+
+/**
+ * Template method for every OIDB call. Builds the envelope, encodes it,
+ * sends through the ctx's `sendRawPacket`, validates the envelope's
+ * `errorCode`, decodes the body, and hands the wire-shaped response to
+ * the spec's `deserialize` for transformation into the business result.
+ *
+ * `ctx` is threaded into both `serialize` and `deserialize` so the
+ * namespace can do uid resolution / identity reads in-place rather
+ * than forcing the caller to pre-bake values into the params.
+ */
+export async function invokeOidb<TCtx extends OidbSender, TReq, TResp, TParams, TResult>(
+    ctx: TCtx,
+    spec: OidbCallSpec<TCtx, TReq, TResp, TParams, TResult>,
+    params: TParams,
+    timeoutMs?: number,
+): Promise<TResult> {
+    const { command, subCommand } = resolveOidbCall(spec, params, ctx);
+    const reqBody = await spec.serialize(ctx, params);
+    const env = makeOidbEnvelope(command, subCommand, reqBody, spec.uinForm ?? false);
+    const reqBytes = spec.encode(env);
+    const wireName = spec.wireName
+        ? spec.wireName(command, subCommand)
+        : `OidbSvcTrpcTcp.0x${command.toString(16)}_${subCommand}`;
+
+    const result =
+        timeoutMs === undefined
+            ? await ctx.sendRawPacket(wireName, reqBytes)
+            : await ctx.sendRawPacket(wireName, reqBytes, timeoutMs);
+
+    if (!result.gotResponse) {
+        throw new Error(result.errorMessage || 'no response');
+    }
+
+    if (!result.success) {
+        if (result.errorCode && result.errorCode !== 0) {
+            if (!isAcceptedEnvelopeCode(spec, result.errorCode)) {
+                throw new OidbError(
+                    result.errorCode,
+                    result.errorMessage || '',
+                    command,
+                    subCommand,
+                );
+            }
+        } else {
+            // success=false without an OIDB error code = the packet send itself failed;
+            // surface it instead of silently resolving with an undecoded response.
+            throw new Error(result.errorMessage || 'packet send failed');
+        }
+    }
+
+    const respBytes = result.responseData ?? new Uint8Array(0);
+
+    if (respBytes.length > 0) {
+        const meta = protobuf_decode<OidbBaseMeta>(respBytes);
+        const code = meta?.errorCode;
+
+        if (code && code !== 0 && !isAcceptedEnvelopeCode(spec, code)) {
+            throw new OidbError(code, meta?.errorMsg ?? '', command, subCommand);
+        }
+    }
+
+    // Server may legitimately respond with an empty envelope (ack-only
+    // cmds like 0x9082_1 — the response carries only `errorCode = 0`
+    // and no body). Substitute an empty placeholder so `deserialize`
+    // always receives a defined object; specs that read fields off the
+    // body must already guard with `?? []` etc.
+    const respBody = spec.decode(respBytes).body ?? ({} as TResp);
+    return spec.deserialize(ctx, respBody);
+}
+
+/**
+ * Build the request wire bytes for a spec without sending — useful for
+ * wire dump debugging, capability probing, and unit tests of the
+ * encode path. Threads `ctx` because `serialize` may want it (and
+ * because matching `invokeOidb`'s shape avoids two call patterns).
+ */
+export async function buildOidbRequest<TCtx extends OidbSender, TReq, TResp, TParams, TResult>(
+    ctx: TCtx,
+    spec: OidbCallSpec<TCtx, TReq, TResp, TParams, TResult>,
+    params: TParams,
+): Promise<{ wireName: string; bytes: Uint8Array }> {
+    const { command, subCommand } = resolveOidbCall(spec, params, ctx);
+    const reqBody = await spec.serialize(ctx, params);
+    const env = makeOidbEnvelope(command, subCommand, reqBody, spec.uinForm ?? false);
+    const bytes = spec.encode(env);
+    const wireName = spec.wireName
+        ? spec.wireName(command, subCommand)
+        : `OidbSvcTrpcTcp.0x${command.toString(16)}_${subCommand}`;
+    return { wireName, bytes };
+}
+
+/**
+ * Decode raw wire bytes into the business result via a spec's
+ * deserialize path — symmetric debug helper for buildOidbRequest.
+ */
+export function parseOidbResponse<TCtx extends OidbSender, TReq, TResp, TParams, TResult>(
+    ctx: TCtx,
+    spec: OidbCallSpec<TCtx, TReq, TResp, TParams, TResult>,
+    bytes: Uint8Array,
+): TResult {
+    return spec.deserialize(ctx, spec.decode(bytes).body ?? ({} as TResp));
+}