@honua/react 0.1.2-beta.0 → 0.1.7-beta.0

package/realtime/reducer.js

@@ -0,0 +1,351 @@
+/**
+ * Pure reducer helpers for realtime feature state.
+ *
+ * @module
+ */
+const DEFAULT_MAX_SEEN_EVENT_IDS = 256;
+const DEFAULT_MAX_TOMBSTONES = 1024;
+export function emptyRealtimeFeatureState() {
+    return {
+        status: "idle",
+        records: {},
+        tombstones: {},
+        ignoredEventCount: 0,
+        seenEventIds: [],
+    };
+}
+export function realtimeFeatureKey(sourceId, id) {
+    return `${sourceId ?? ""}:${String(id)}`;
+}
+export function realtimeSubscriptionKey(request) {
+    return [
+        request.requestId ?? "",
+        request.sourceId,
+        request.layerId === undefined ? "" : String(request.layerId),
+        request.where ?? "",
+        request.fields?.join(",") ?? "",
+        encodeIdentityPart(request.spatialFilter),
+    ].join("\u0000");
+}
+export function realtimeResumeCheckpoint(state) {
+    if (!state.checkpoint)
+        return undefined;
+    return { ...state.checkpoint };
+}
+export function reduceRealtimeFeatureState(state, event, options = {}) {
+    if (isDuplicateOrOutOfOrder(state, event)) {
+        return {
+            ...state,
+            ignoredEventCount: state.ignoredEventCount + 1,
+        };
+    }
+    const receivedAt = event.receivedAt ?? options.now?.() ?? Date.now();
+    const base = withEventMetadata(state, event, receivedAt, options.maxSeenEventIds ?? DEFAULT_MAX_SEEN_EVENT_IDS);
+    const metadata = mutationMetadata(event, receivedAt);
+    switch (event.type) {
+        case "snapshot":
+            return applySnapshot(base, event.features, {
+                replace: event.replace ?? true,
+                ...metadata,
+            });
+        case "upsert":
+            return applyUpsert(base, event.feature, metadata);
+        case "delete":
+            return boundTombstones(applyDelete(base, {
+                id: event.id,
+                sourceId: event.sourceId,
+                cursor: metadata.cursor,
+                sequence: metadata.sequence,
+                version: event.version,
+                updatedAt: event.updatedAt,
+                deletedAt: event.deletedAt ?? receivedAt,
+            }), options, receivedAt);
+        case "delta":
+            return boundTombstones(applyDelta(base, event.upserts ?? [], event.deletes ?? [], metadata), options, receivedAt);
+        case "heartbeat":
+            return {
+                ...base,
+                status: base.status === "closed" || base.status === "error" ? base.status : "live",
+                lastHeartbeatAt: receivedAt,
+                staleSince: undefined,
+                error: base.status === "error" ? base.error : undefined,
+                statusReason: base.status === "error" ? base.statusReason : undefined,
+                retryAfterMs: base.status === "error" ? base.retryAfterMs : undefined,
+                reconnectAttempt: base.status === "error" ? base.reconnectAttempt : undefined,
+            };
+        case "status":
+            return {
+                ...base,
+                status: event.status,
+                lastStatusAt: receivedAt,
+                staleSince: event.status === "stale" ? (event.staleSince ?? receivedAt) : undefined,
+                error: event.status === "error" ? base.error : undefined,
+                statusReason: event.reason,
+                retryAfterMs: event.retryAfterMs,
+                reconnectAttempt: event.reconnectAttempt,
+                terminalError: event.status === "error" ? base.terminalError : undefined,
+            };
+        case "error":
+            return {
+                ...base,
+                status: event.terminal ? "error" : "reconnecting",
+                lastStatusAt: receivedAt,
+                error: event.error,
+                statusReason: event.code,
+                retryAfterMs: event.retryAfterMs,
+                terminalError: event.terminal === true,
+                staleSince: event.terminal ? base.staleSince : receivedAt,
+            };
+    }
+}
+export function reconcileRealtimeStaleness(state, options) {
+    const now = options.now ?? Date.now();
+    const lastLiveAt = state.lastHeartbeatAt ?? state.lastEventAt;
+    if (!lastLiveAt || now - lastLiveAt <= options.staleAfterMs)
+        return state;
+    if (state.status === "closed" || state.status === "error" || state.status === "offline")
+        return state;
+    return {
+        ...state,
+        status: "stale",
+        staleSince: state.staleSince ?? lastLiveAt + options.staleAfterMs,
+    };
+}
+function isDuplicateOrOutOfOrder(state, event) {
+    if (event.eventId && state.seenEventIds.includes(event.eventId))
+        return true;
+    const sequence = eventSequence(event);
+    return typeof sequence === "number" && typeof state.lastSequence === "number" && sequence <= state.lastSequence;
+}
+function withEventMetadata(state, event, receivedAt, maxSeenEventIds) {
+    const seenEventIds = event.eventId
+        ? [...state.seenEventIds, event.eventId].slice(-Math.max(1, maxSeenEventIds))
+        : state.seenEventIds;
+    const sequence = eventSequence(event);
+    const checkpoint = mergeCheckpoint(state.checkpoint, event);
+    const cursor = eventCursor(event) ?? state.cursor;
+    const watermark = eventWatermark(event) ?? state.watermark;
+    const timestamp = eventTimestamp(event) ?? state.timestamp;
+    const deltaToken = eventDeltaToken(event) ?? state.deltaToken;
+    const status = isRecoverableStatus(state.status) ? "live" : state.status;
+    return {
+        ...state,
+        status,
+        cursor,
+        watermark,
+        timestamp,
+        deltaToken,
+        checkpoint,
+        lastSequence: typeof sequence === "number" ? sequence : state.lastSequence,
+        lastEventAt: receivedAt,
+        staleSince: undefined,
+        error: status === "live" ? undefined : state.error,
+        seenEventIds,
+    };
+}
+function applySnapshot(state, features, metadata) {
+    const records = metadata.replace ? {} : { ...state.records };
+    const tombstones = metadata.replace ? {} : { ...state.tombstones };
+    for (const feature of features) {
+        const key = realtimeFeatureKey(feature.sourceId, feature.id);
+        records[key] = {
+            ...feature,
+            key,
+            cursor: metadata.cursor,
+            sequence: metadata.sequence,
+            receivedAt: metadata.receivedAt,
+        };
+        delete tombstones[key];
+    }
+    return {
+        ...state,
+        records,
+        tombstones,
+    };
+}
+function applyDelta(state, upserts, deletes, metadata) {
+    if (upserts.length === 0 && deletes.length === 0) {
+        return state;
+    }
+    // Build the next records/tombstones maps once and mutate them across every
+    // item in the batch. The previous implementation delegated to
+    // applyUpsert/applyDelete per item, each of which spread the entire records
+    // (and tombstones) dictionary — O(deltaSize x stateSize): a 100-mutation
+    // delta over a 10k-feature state copied ~1M entries.
+    const records = { ...state.records };
+    const tombstones = { ...state.tombstones };
+    for (const feature of upserts) {
+        const key = realtimeFeatureKey(feature.sourceId, feature.id);
+        delete tombstones[key];
+        records[key] = {
+            ...feature,
+            key,
+            cursor: metadata.cursor,
+            sequence: metadata.sequence,
+            receivedAt: metadata.receivedAt,
+        };
+    }
+    for (const tombstone of deletes) {
+        const key = realtimeFeatureKey(tombstone.sourceId, tombstone.id);
+        delete records[key];
+        tombstones[key] = {
+            id: tombstone.id,
+            sourceId: tombstone.sourceId,
+            cursor: metadata.cursor,
+            sequence: metadata.sequence,
+            version: tombstone.version,
+            updatedAt: tombstone.updatedAt,
+            deletedAt: tombstone.deletedAt ?? metadata.receivedAt,
+            key,
+        };
+    }
+    return {
+        ...state,
+        records,
+        tombstones,
+    };
+}
+/**
+ * Evict tombstones that exceed the configured age (`tombstoneTtlMs`) or count
+ * (`maxTombstones`, default {@link DEFAULT_MAX_TOMBSTONES}) bound. Returns the
+ * input state unchanged when nothing is pruned so reducers stay referentially
+ * stable on the common path.
+ */
+function boundTombstones(state, options, now) {
+    const maxTombstones = options.maxTombstones ?? DEFAULT_MAX_TOMBSTONES;
+    const ttlMs = options.tombstoneTtlMs;
+    const hasTtl = typeof ttlMs === "number" && ttlMs >= 0;
+    const entries = Object.values(state.tombstones);
+    const overCount = maxTombstones > 0 && entries.length > maxTombstones;
+    if (!overCount && !hasTtl) {
+        return state;
+    }
+    let kept = entries;
+    if (hasTtl) {
+        kept = kept.filter((tombstone) => now - (tombstone.deletedAt ?? 0) <= ttlMs);
+    }
+    if (maxTombstones > 0 && kept.length > maxTombstones) {
+        // Retain the most-recently-deleted entries.
+        kept = [...kept].sort((a, b) => (a.deletedAt ?? 0) - (b.deletedAt ?? 0)).slice(kept.length - maxTombstones);
+    }
+    if (kept.length === entries.length) {
+        return state;
+    }
+    const tombstones = {};
+    for (const tombstone of kept) {
+        tombstones[tombstone.key] = tombstone;
+    }
+    return { ...state, tombstones };
+}
+function applyUpsert(state, feature, metadata) {
+    const key = realtimeFeatureKey(feature.sourceId, feature.id);
+    const tombstones = { ...state.tombstones };
+    delete tombstones[key];
+    return {
+        ...state,
+        records: {
+            ...state.records,
+            [key]: {
+                ...feature,
+                key,
+                cursor: metadata.cursor,
+                sequence: metadata.sequence,
+                receivedAt: metadata.receivedAt,
+            },
+        },
+        tombstones,
+    };
+}
+function applyDelete(state, tombstone) {
+    const key = realtimeFeatureKey(tombstone.sourceId, tombstone.id);
+    const records = { ...state.records };
+    delete records[key];
+    return {
+        ...state,
+        records,
+        tombstones: {
+            ...state.tombstones,
+            [key]: {
+                ...tombstone,
+                key,
+            },
+        },
+    };
+}
+function eventCursor(event) {
+    return event.checkpoint?.cursor ?? event.cursor;
+}
+function eventWatermark(event) {
+    return event.checkpoint?.watermark ?? event.watermark;
+}
+function eventTimestamp(event) {
+    return event.checkpoint?.timestamp ?? event.timestamp;
+}
+function eventDeltaToken(event) {
+    return event.checkpoint?.deltaToken ?? event.deltaToken;
+}
+function eventSequence(event) {
+    return event.sequence ?? event.checkpoint?.sequence;
+}
+function mutationMetadata(event, receivedAt) {
+    return {
+        cursor: eventCursor(event),
+        sequence: eventSequence(event),
+        receivedAt,
+    };
+}
+function mergeCheckpoint(previous, event) {
+    const cursor = eventCursor(event);
+    const watermark = eventWatermark(event);
+    const timestamp = eventTimestamp(event);
+    const sequence = eventSequence(event);
+    const deltaToken = eventDeltaToken(event);
+    if (previous === undefined &&
+        cursor === undefined &&
+        watermark === undefined &&
+        timestamp === undefined &&
+        sequence === undefined &&
+        deltaToken === undefined) {
+        return undefined;
+    }
+    return {
+        ...(previous ?? {}),
+        ...(cursor !== undefined ? { cursor } : {}),
+        ...(watermark !== undefined ? { watermark } : {}),
+        ...(timestamp !== undefined ? { timestamp } : {}),
+        ...(sequence !== undefined ? { sequence } : {}),
+        ...(deltaToken !== undefined ? { deltaToken } : {}),
+    };
+}
+function isRecoverableStatus(status) {
+    return (status === "idle" ||
+        status === "connecting" ||
+        status === "reconnecting" ||
+        status === "stale" ||
+        status === "offline");
+}
+function encodeIdentityPart(value) {
+    if (value === undefined)
+        return "";
+    if (typeof value !== "object" || value === null)
+        return String(value);
+    try {
+        return JSON.stringify(sortIdentityValue(value));
+    }
+    catch {
+        return String(value);
+    }
+}
+function sortIdentityValue(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map(sortIdentityValue);
+    if (typeof value !== "object" || value === null)
+        return value;
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+        sorted[key] = sortIdentityValue(value[key]);
+    }
+    return sorted;
+}

package/realtime/resumable-transport.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Bounded, resumable SSE and WebSocket transports for `@honua/sdk-js/realtime`
+ * (issue #557), built on the #556 snapshot/delta/cursor/resume/plan-identity
+ * contract.
+ *
+ * `resumable.ts` deliberately never reconnects a transport — that ownership
+ * is explicitly deferred to this module (see
+ * `docs/decisions/realtime-snapshot-delta-cursor-resume-plan-identity-contract.md`,
+ * "the gate never reconnects a transport itself"). This module closes that
+ * gap by wrapping any raw {@link RealtimeFeatureTransport} (the SSE adapter
+ * in `sse.ts`, the WebSocket adapter in `websocket.ts`, or a custom one) with:
+ *
+ * - the bounded delivery gate from `resumable.ts` (`maxPendingEvents`,
+ *   duplicate/gap detection, cross-scope checkpoint rejection);
+ * - reconnect ownership with exponential-backoff-and-jitter retry, bounded by
+ *   `reconnect.maxAttempts` — exhausting attempts fails closed rather than
+ *   retrying forever;
+ * - a heartbeat/liveness timeout that treats prolonged silence as a
+ *   transport-detected gap;
+ * - resume-vs-resnapshot selection driven entirely by the gate's own
+ *   `phase`: a reconnect resumes from the last accepted checkpoint's cursor
+ *   only while the gate considers it valid, and requests a fresh snapshot
+ *   the moment the gate (or this module, via `requireResnapshot`) decides
+ *   otherwise — REQ-003's "resume only with a valid scoped cursor";
+ * - idempotent disposal that stops timers, the active connection, and the
+ *   delivery gate exactly once, however disposal was triggered
+ *   (caller `close()`, external `AbortSignal`, or an unrecoverable failure);
+ * - redacted telemetry (`onTelemetry`) built on `contract.ts`'s
+ *   `deriveRealtimeContractAuthority` / `redactRealtimeCheckpoint`, so a raw
+ *   cursor, watermark, or delta-token never reaches a log or metrics sink.
+ *
+ * The result still satisfies `RealtimeFeatureTransport`, so it composes with
+ * `createRealtimeFeatureStore` exactly like any other transport.
+ *
+ * @module
+ */
+import type { RealtimeContractAuthority, RedactedRealtimeCheckpointV1 } from "./contract.js";
+import { type RealtimeCheckpointStore, type RealtimeDurableCheckpointV1, type RealtimeResumeContextV1 } from "./resumable.js";
+import type { RealtimeServerSentEventsTransportOptions } from "./sse.js";
+import type { RealtimeFeatureTransport } from "./types.js";
+import type { RealtimeWebSocketTransportOptions } from "./websocket.js";
+export interface RealtimeReconnectPolicy {
+    /** Consecutive reconnect attempts allowed before failing closed. `0` disables reconnect entirely. @default 8 */
+    readonly maxAttempts?: number;
+    /** Delay before the first reconnect attempt. @default 250 */
+    readonly baseDelayMs?: number;
+    /** Upper bound on the exponential backoff delay, before jitter. @default 30000 */
+    readonly maxDelayMs?: number;
+    /** How long a connection must stay live before a subsequent failure resets the attempt counter. @default 15000 */
+    readonly resetAfterMs?: number;
+}
+export interface RealtimeResumableTransportTelemetry {
+    readonly authority: RealtimeContractAuthority;
+    readonly reconnectAttempt: number;
+    readonly acceptedEventCount: number;
+    readonly duplicateEventCount: number;
+    readonly gapCount: number;
+    readonly overflowCount: number;
+    /** Never a raw cursor, watermark, or delta-token value. */
+    readonly checkpoint?: RedactedRealtimeCheckpointV1;
+}
+export interface RealtimeResumableTransportOptions<TFeature = unknown> {
+    readonly context: RealtimeResumeContextV1;
+    readonly checkpointStore?: RealtimeCheckpointStore;
+    /**
+     * Seed resume position for the very first connection, validated the same
+     * way a loaded `checkpointStore` checkpoint is (`evaluateRealtimeCheckpoint`).
+     * This is the only supported way to seed a resume position: `subscribe()`'s
+     * `request.cursor` / `resumeFrom` and similar fields are ignored by this
+     * wrapper so a stale or unscoped caller-supplied position can never bypass
+     * checkpoint compatibility validation.
+     */
+    readonly initialCheckpoint?: RealtimeDurableCheckpointV1;
+    /** Includes the currently applying event. @default 64 */
+    readonly maxPendingEvents?: number;
+    /** Bounded event-id history persisted with each checkpoint. @default 256 */
+    readonly maxRecentEventIds?: number;
+    readonly reconnect?: RealtimeReconnectPolicy;
+    /** No event (including heartbeats) within this window is treated as a transport-detected gap. Disabled when omitted. */
+    readonly heartbeatTimeoutMs?: number;
+    /** Forwarded to {@link deriveRealtimeContractAuthority} for telemetry. */
+    readonly staleAfterMs?: number;
+    readonly onTelemetry?: (telemetry: RealtimeResumableTransportTelemetry) => void;
+    readonly now?: () => number;
+}
+/**
+ * Exponential backoff with jitter in the [0.5x, 1x] band for the given
+ * zero-based reconnect attempt — the same shape as
+ * `core/request-pipeline.ts`'s `resolveRetryDelayMs`, reimplemented locally
+ * so `@honua/sdk-js/realtime` does not pull in the HTTP request pipeline's
+ * error/type graph for one small helper. Exported so the schedule can be
+ * asserted deterministically without driving a fake transport end-to-end.
+ */
+export declare function computeReconnectDelayMs(policy: RealtimeReconnectPolicy | undefined, attempt: number): number;
+/**
+ * Wrap a raw {@link RealtimeFeatureTransport} with bounded, resumable
+ * delivery: the #556 delivery gate, reconnect/backoff, heartbeat timeout,
+ * and redacted telemetry. See the module doc for the full behavior.
+ */
+export declare function createResumableRealtimeTransport<TFeature = unknown>(transport: RealtimeFeatureTransport<TFeature>, options: RealtimeResumableTransportOptions<TFeature>): RealtimeFeatureTransport<TFeature>;
+/**
+ * Convenience factory combining {@link createRealtimeServerSentEventsTransport}
+ * with {@link createResumableRealtimeTransport}.
+ */
+export declare function createResumableServerSentEventsTransport<TFeature = unknown>(sseOptions: RealtimeServerSentEventsTransportOptions<TFeature>, resumableOptions: RealtimeResumableTransportOptions<TFeature>): RealtimeFeatureTransport<TFeature>;
+/**
+ * Convenience factory combining {@link createRealtimeWebSocketTransport}
+ * with {@link createResumableRealtimeTransport}.
+ */
+export declare function createResumableWebSocketTransport<TFeature = unknown>(webSocketOptions: RealtimeWebSocketTransportOptions<TFeature>, resumableOptions: RealtimeResumableTransportOptions<TFeature>): RealtimeFeatureTransport<TFeature>;
+//# sourceMappingURL=resumable-transport.d.ts.map

package/realtime/resumable-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resumable-transport.d.ts","sourceRoot":"","sources":["../../../src/realtime/resumable-transport.ts"],"names":[],"mappings":"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"}