@net-mesh/core 0.21.0 → 0.23.0

package/aggregator.d.ts

@@ -0,0 +1,56 @@
+export type RegistryErrorKind = 'transport' | 'codec' | 'unknown-template' | 'duplicate-group-name' | 'spawn-rejected' | 'spawn-not-supported' | 'invalid-args';
+export type FoldQueryErrorKind = 'transport' | 'codec' | 'unknown-kind' | 'invalid-args';
+export declare class RegistryClientError extends Error {
+    readonly kind: RegistryErrorKind;
+    readonly serverDetail?: string;
+    constructor(kind: RegistryErrorKind, detail: string);
+}
+export declare class FoldQueryClientError extends Error {
+    readonly kind: FoldQueryErrorKind;
+    readonly serverDetail?: string;
+    constructor(kind: FoldQueryErrorKind, detail: string);
+}
+/**
+ * Inspect an error message for the `agg:` prefix and return the
+ * structured `{kind, detail}` if it matches. Returns `null` when
+ * the message is missing the prefix or is malformed.
+ */
+export declare function parseAggregatorError(e: unknown): {
+    kind: string;
+    detail: string;
+} | null;
+/**
+ * Re-throw a typed error for the given raw error if it carries the
+ * `agg:` prefix. Non-matching errors pass through unchanged so
+ * `throw classifyAggregatorError(e)` is safe at any catch site.
+ *
+ * Routes to `RegistryClientError` for registry-shaped kinds and
+ * `FoldQueryClientError` for fold-query-shaped kinds. Both surfaces
+ * share `transport` / `codec` / `invalid-args`; we route by the
+ * caller's typing — pass an explicit `surface` if you know which
+ * client raised it, otherwise the default routing biases to
+ * `RegistryClientError` for shared kinds (the substrate's primary
+ * surface).
+ */
+export declare function classifyAggregatorError(e: unknown, surface?: 'registry' | 'fold-query'): unknown;
+export interface RegistryReplicaRow {
+    generation: bigint;
+    healthy: boolean;
+    diagnostic?: string;
+    placementNodeId?: bigint;
+}
+export interface RegistryGroupSummary {
+    name: string;
+    groupSeedHex: string;
+    replicas: RegistryReplicaRow[];
+}
+export interface SummaryBucket {
+    name: string;
+    count: bigint;
+}
+export interface SummaryAnnouncement {
+    foldKind: number;
+    sourceSubnet: string;
+    generation: bigint;
+    buckets: SummaryBucket[];
+}

package/aggregator.js

@@ -0,0 +1,130 @@
+"use strict";
+// Typed error classes + classifier for the `aggregator.registry`
+// / `fold.query` RPC clients.
+//
+// The napi binding throws plain Error with the stable `agg:`
+// prefix (`agg:<kind>: <detail>`); `classifyAggregatorError`
+// re-throws as a typed `RegistryClientError` /
+// `FoldQueryClientError`. Prefix locked against
+// `ERR_AGG_PREFIX` in `bindings/node/src/aggregator.rs`;
+// `tests/error_kind_mirror.rs` is the cross-language pin.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FoldQueryClientError = exports.RegistryClientError = void 0;
+exports.parseAggregatorError = parseAggregatorError;
+exports.classifyAggregatorError = classifyAggregatorError;
+const ERR_AGG_PREFIX = 'agg:';
+class RegistryClientError extends Error {
+    kind;
+    serverDetail;
+    constructor(kind, detail) {
+        super(`${kind}: ${detail}`);
+        this.name = 'RegistryClientError';
+        this.kind = kind;
+        this.serverDetail = detail;
+        Object.setPrototypeOf(this, RegistryClientError.prototype);
+    }
+}
+exports.RegistryClientError = RegistryClientError;
+class FoldQueryClientError extends Error {
+    kind;
+    serverDetail;
+    constructor(kind, detail) {
+        super(`${kind}: ${detail}`);
+        this.name = 'FoldQueryClientError';
+        this.kind = kind;
+        this.serverDetail = detail;
+        Object.setPrototypeOf(this, FoldQueryClientError.prototype);
+    }
+}
+exports.FoldQueryClientError = FoldQueryClientError;
+const REGISTRY_KINDS = new Set([
+    'transport',
+    'codec',
+    'unknown-template',
+    'duplicate-group-name',
+    'spawn-rejected',
+    'spawn-not-supported',
+    'invalid-args',
+]);
+const FOLD_KINDS = new Set([
+    'transport',
+    'codec',
+    'unknown-kind',
+    'invalid-args',
+]);
+/**
+ * Inspect an error message for the `agg:` prefix and return the
+ * structured `{kind, detail}` if it matches. Returns `null` when
+ * the message is missing the prefix or is malformed.
+ */
+function parseAggregatorError(e) {
+    const msg = extractMessage(e);
+    if (!msg.startsWith(ERR_AGG_PREFIX))
+        return null;
+    const after = msg.slice(ERR_AGG_PREFIX.length);
+    // Find the FIRST `: ` separator — kinds are stable kebab-case
+    // identifiers with no colons; the detail may contain colons.
+    const sepIdx = after.indexOf(': ');
+    if (sepIdx === -1) {
+        // No detail, just the kind (defensive — substrate always emits
+        // a detail string today).
+        return { kind: after, detail: '' };
+    }
+    return {
+        kind: after.slice(0, sepIdx),
+        detail: after.slice(sepIdx + 2),
+    };
+}
+/**
+ * Re-throw a typed error for the given raw error if it carries the
+ * `agg:` prefix. Non-matching errors pass through unchanged so
+ * `throw classifyAggregatorError(e)` is safe at any catch site.
+ *
+ * Routes to `RegistryClientError` for registry-shaped kinds and
+ * `FoldQueryClientError` for fold-query-shaped kinds. Both surfaces
+ * share `transport` / `codec` / `invalid-args`; we route by the
+ * caller's typing — pass an explicit `surface` if you know which
+ * client raised it, otherwise the default routing biases to
+ * `RegistryClientError` for shared kinds (the substrate's primary
+ * surface).
+ */
+function classifyAggregatorError(e, surface) {
+    const parsed = parseAggregatorError(e);
+    if (!parsed)
+        return e;
+    // Surface-specific kinds take priority — they are unambiguous.
+    if (parsed.kind === 'unknown-kind') {
+        return new FoldQueryClientError('unknown-kind', parsed.detail);
+    }
+    if (parsed.kind === 'unknown-template' ||
+        parsed.kind === 'duplicate-group-name' ||
+        parsed.kind === 'spawn-rejected' ||
+        parsed.kind === 'spawn-not-supported') {
+        return new RegistryClientError(parsed.kind, parsed.detail);
+    }
+    // Shared kinds — route by caller hint, default to registry.
+    if (parsed.kind === 'transport' ||
+        parsed.kind === 'codec' ||
+        parsed.kind === 'invalid-args') {
+        if (surface === 'fold-query') {
+            return new FoldQueryClientError(parsed.kind, parsed.detail);
+        }
+        return new RegistryClientError(parsed.kind, parsed.detail);
+    }
+    // Unknown kind under the `agg:` umbrella — keep the original
+    // error so callers see the full string instead of a synthetic
+    // typed wrapper that drops information.
+    void REGISTRY_KINDS;
+    void FOLD_KINDS;
+    return e;
+}
+function extractMessage(e) {
+    if (e === null || e === undefined)
+        return '';
+    if (typeof e === 'string')
+        return e;
+    if (typeof e !== 'object')
+        return '';
+    const msg = e.message;
+    return typeof msg === 'string' ? msg : '';
+}