@hashxltd/liveframe-vue 0.0.1

package/src/protocol/codec.ts

@@ -0,0 +1,177 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Encodes outbound envelopes and decodes + validates inbound frames.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import {
+  PROTOCOL_VERSION,
+  MAX_FRAME_BYTES,
+  MAX_EVENT_NAME_LENGTH,
+} from "./constants";
+import type { Envelope } from "./types";
+import { FrameError, FrameErrorCode } from "../errors";
+
+const EVENT_RE = /^[a-z][a-z0-9._-]{0,127}$/;
+
+// ─── Encode ───────────────────────────────────────────────────────────────────
+
+/**
+ * Serialises an outbound envelope to a JSON string.
+ * Throws FrameError.PAYLOAD_TOO_LARGE if the result exceeds MAX_FRAME_BYTES.
+ */
+export function encode<P>(env: Envelope<P>): string {
+  const raw = JSON.stringify(env);
+  if (raw.length > MAX_FRAME_BYTES) {
+    throw new FrameError(
+      FrameErrorCode.PAYLOAD_TOO_LARGE,
+      `Frame size ${raw.length} B exceeds limit of ${MAX_FRAME_BYTES} B (event: ${env.event})`,
+    );
+  }
+  return raw;
+}
+
+// ─── Decode ───────────────────────────────────────────────────────────────────
+
+/**
+ * Parses and structurally validates an inbound frame.
+ * Returns the typed envelope or throws FrameError.
+ */
+export function decode(raw: string): Envelope {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new FrameError(
+      FrameErrorCode.MALFORMED_JSON,
+      "Frame is not valid JSON",
+    );
+  }
+
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new FrameError(
+      FrameErrorCode.INVALID_SHAPE,
+      "Frame must be a JSON object",
+    );
+  }
+
+  const obj = parsed as Record<string, unknown>;
+
+  // ── Version ──────────────────────────────────────────────────────────────
+  if (obj["v"] !== PROTOCOL_VERSION) {
+    throw new FrameError(
+      FrameErrorCode.VERSION_MISMATCH,
+      `Unsupported protocol version: ${obj["v"]} (expected ${PROTOCOL_VERSION})`,
+    );
+  }
+
+  // ── Required fields ───────────────────────────────────────────────────────
+  assertString(obj, "id", FrameErrorCode.MISSING_FIELD);
+  assertString(obj, "event", FrameErrorCode.MISSING_FIELD);
+  assertNumber(obj, "ts", FrameErrorCode.MISSING_FIELD);
+
+  // ── Event name format ─────────────────────────────────────────────────────
+  const event = obj["event"] as string;
+  if (event.length > MAX_EVENT_NAME_LENGTH || !EVENT_RE.test(event)) {
+    throw new FrameError(
+      FrameErrorCode.INVALID_EVENT,
+      `Invalid event name: "${event}"`,
+    );
+  }
+
+  // ── Payload type ──────────────────────────────────────────────────────────
+  if ("payload" in obj && obj["payload"] !== undefined) {
+    const p = obj["payload"];
+    if (typeof p !== "object" || p === null || Array.isArray(p)) {
+      throw new FrameError(
+        FrameErrorCode.INVALID_SHAPE,
+        `payload must be a JSON object (event: ${event})`,
+      );
+    }
+  }
+
+  return obj as unknown as Envelope;
+}
+
+/**
+ * Parses and structurally validates an inbound frame.
+ * Returns the typed envelope.
+ */
+export function decode_as<T = unknown>(raw: string): Envelope<T> {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new FrameError(
+      FrameErrorCode.MALFORMED_JSON,
+      "Frame is not valid JSON",
+    );
+  }
+
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new FrameError(
+      FrameErrorCode.INVALID_SHAPE,
+      "Frame must be a JSON object",
+    );
+  }
+
+  const obj = parsed as Record<string, unknown>;
+
+  // ── Version ─────────────────────────────────────────────
+  if (obj["v"] !== PROTOCOL_VERSION) {
+    throw new FrameError(
+      FrameErrorCode.VERSION_MISMATCH,
+      `Unsupported protocol version: ${obj["v"]} (expected ${PROTOCOL_VERSION})`,
+    );
+  }
+
+  // ── Required fields ──────────────────────────────────────
+  assertString(obj, "id", FrameErrorCode.MISSING_FIELD);
+  assertString(obj, "event", FrameErrorCode.MISSING_FIELD);
+  assertNumber(obj, "ts", FrameErrorCode.MISSING_FIELD);
+
+  // ── Event validation ─────────────────────────────────────
+  const event = obj["event"] as string;
+
+  if (event.length > MAX_EVENT_NAME_LENGTH || !EVENT_RE.test(event)) {
+    throw new FrameError(
+      FrameErrorCode.INVALID_EVENT,
+      `Invalid event name: "${event}"`,
+    );
+  }
+
+  // ── Payload validation ───────────────────────────────────
+  if ("payload" in obj && obj["payload"] !== undefined) {
+    const p = obj["payload"];
+
+    if (typeof p !== "object" || p === null || Array.isArray(p)) {
+      throw new FrameError(
+        FrameErrorCode.INVALID_SHAPE,
+        `payload must be a JSON object (event: ${event})`,
+      );
+    }
+  }
+
+  return obj as unknown as Envelope<T>;
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function assertString(
+  obj: Record<string, unknown>,
+  key: string,
+  code: FrameErrorCode,
+): void {
+  if (typeof obj[key] !== "string" || (obj[key] as string).length === 0) {
+    throw new FrameError(code, `Missing or invalid field: "${key}"`);
+  }
+}
+
+function assertNumber(
+  obj: Record<string, unknown>,
+  key: string,
+  code: FrameErrorCode,
+): void {
+  if (typeof obj[key] !== "number" || !Number.isFinite(obj[key] as number)) {
+    throw new FrameError(code, `Missing or invalid field: "${key}"`);
+  }
+}

package/src/protocol/constants.ts

@@ -0,0 +1,125 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Single source of truth for every magic number in the protocol.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const PROTOCOL_VERSION = 1 as const
+export const MAX_FRAME_BYTES = 64 * 1024 // 64 KB
+export const MAX_EVENT_NAME_LENGTH = 128
+export const MAX_PENDING_ACKS = 512
+export const DEFAULT_ACK_TIMEOUT_MS = 5_000
+export const DEFAULT_AUTH_TIMEOUT_MS = 10_000
+export const DEFAULT_PING_INTERVAL_MS = 25_000
+export const DEFAULT_PING_TIMEOUT_MS = 10_000
+export const DEFAULT_RECONNECT_BASE_MS = 250
+export const DEFAULT_RECONNECT_CAP_MS = 30_000
+export const TOKEN_REFRESH_LEAD_MS = 60_000 // refresh 60 s before expiry
+export const RATE_LIMIT_CAPACITY = 100
+export const RATE_LIMIT_WINDOW_MS = 10_000
+
+// ─── WebSocket sub-protocol ───────────────────────────────────────────────────
+export const WS_SUBPROTOCOL = 'liveframe.v1'
+
+// ─── WebSocket close codes ────────────────────────────────────────────────────
+export const CloseCodes = {
+  NORMAL: 1000,
+  GOING_AWAY: 1001,
+  POLICY_VIOLATION: 1008,
+  PROTOCOL_ERROR: 4000,
+  HEARTBEAT_TIMEOUT: 4001,
+  AUTH_TIMEOUT: 4002,
+  AUTH_FAILED: 4003,
+  RATE_LIMITED: 4004,
+  MESSAGE_TOO_LARGE: 4005,
+} as const
+
+export type CloseCode = (typeof CloseCodes)[keyof typeof CloseCodes]
+
+/** Close codes that MUST NOT trigger automatic reconnection. */
+export const NO_RECONNECT_CODES = new Set<number>([
+  CloseCodes.AUTH_FAILED,
+  CloseCodes.POLICY_VIOLATION,
+])
+
+// ─── System event names ───────────────────────────────────────────────────────
+export const SystemEvents = {
+  // Server → Client
+  CONNECTED: 'sys.connected',
+  PING: 'sys.ping',
+  PONG: 'sys.pong',
+  DISCONNECT: 'sys.disconnect',
+  RATE_LIMITED: 'sys.rate_limited',
+
+  // Auth
+  AUTH_LOGIN: 'auth.login',
+  AUTH_OK: 'auth.ok',
+  AUTH_REFRESH: 'auth.refresh',
+  AUTH_REVOKED: 'auth.revoked',
+
+  // Ack
+  ACK_OK: 'ack.ok',
+  ACK_ERROR: 'ack.error',
+
+  // Presence
+  PRESENCE_JOINED: 'presence.joined',
+  PRESENCE_LEFT: 'presence.left',
+  PRESENCE_UPDATE: 'presence.update',
+  PRESENCE_LIST: 'presence.list',
+  PRESENCE_SNAPSHOT: 'presence.snapshot',
+
+  // Errors
+  ERROR_AUTH: 'error.auth',
+  ERROR_VALIDATION: 'error.validation',
+  ERROR_ROUTING: 'error.routing',
+  ERROR_RATE_LIMIT: 'error.rate_limit',
+  ERROR_INTERNAL: 'error.internal',
+} as const
+
+export type SystemEvent = (typeof SystemEvents)[keyof typeof SystemEvents]
+
+// Create a runtime set
+const systemEventSet = new Set<string>(Object.values(SystemEvents))
+
+export function isSystemEvent(event: string): event is SystemEvent {
+  return systemEventSet.has(event)
+}
+
+// ─── Application-level error codes ───────────────────────────────────────────
+export const ErrorCodes = {
+  // Auth
+  TOKEN_EXPIRED: 'token_expired',
+  TOKEN_INVALID: 'token_invalid',
+  TOKEN_REVOKED: 'token_revoked',
+  NOT_AUTHENTICATED: 'not_authenticated',
+  SESSION_EXPIRED: 'session_expired',
+
+  // Validation
+  VALIDATION_FAILED: 'validation_failed',
+  PAYLOAD_TOO_LARGE: 'payload_too_large',
+  INVALID_EVENT: 'invalid_event',
+  MISSING_FIELD: 'missing_field',
+
+  // Routing
+  NOT_FOUND: 'not_found',
+  NOT_ALLOWED: 'not_allowed',
+
+  // Rate limiting
+  RATE_EXCEEDED: 'rate_exceeded',
+
+  // Server
+  INTERNAL: 'internal',
+  SERVICE_UNAVAILABLE: 'service_unavailable',
+} as const
+
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes]
+
+// ─── Connection states ────────────────────────────────────────────────────────
+export const ConnectionStates = {
+  DISCONNECTED: 'DISCONNECTED',
+  CONNECTING: 'CONNECTING',
+  CONNECTED: 'CONNECTED', // WS open; sys.connected received
+  AUTHENTICATING: 'AUTHENTICATING', // auth.login sent
+  READY: 'READY', // auth.ok received; app events may flow
+  RECONNECTING: 'RECONNECTING', // backing off before retry
+} as const
+
+export type ConnectionState = (typeof ConnectionStates)[keyof typeof ConnectionStates]

package/src/protocol/index.ts

@@ -0,0 +1,3 @@
+export * from './constants'
+export * from './types'
+export * from './codec'

package/src/protocol/types.ts

@@ -0,0 +1,255 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// protocol/types.ts
+// Every message shape the protocol defines, in one place.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import type { PROTOCOL_VERSION } from "./constants";
+
+// ─── Base envelope ────────────────────────────────────────────────────────────
+
+/**
+ * Every WebSocket frame — in both directions — is wrapped in this envelope.
+ *
+ * ```json
+ * { "v":1, "id":"uuid-v4", "event":"chat.message", "payload":{...}, "ts":1710000000000, "ack":true }
+ * ```
+ */
+export interface Envelope<P = unknown> {
+  /** Protocol version. MUST be 1. */
+  readonly v: typeof PROTOCOL_VERSION;
+  /** UUID v4 — unique per frame. Used for ack correlation and idempotency. */
+  readonly id: string;
+  /** Dot-separated event name. Max 128 chars. Pattern: ^[a-z][a-z0-9._-]{0,127}$ */
+  readonly event: string;
+  /** Application payload. MUST be an object or omitted — never a primitive. */
+  readonly payload?: P;
+  /** Unix milliseconds (UTC) at time of send. */
+  readonly ts: number;
+  /** When true, sender requests ack.ok / ack.error in return. */
+  readonly ack?: true;
+}
+
+// ─── Status types ─────────────────────────────────────────────────────────────
+
+/** High-level status of a delivered operation (used by ack.ok). */
+export type OperationStatus = "delivered" | "queued" | "processed";
+
+/** Current health status of the connection. */
+export type HealthStatus = "healthy" | "degraded" | "reconnecting" | "offline";
+
+// ─── System payloads ──────────────────────────────────────────────────────────
+
+export interface SysConnectedPayload {
+  /** Server-assigned socket identifier. */
+  readonly socket_id: string;
+  /** Informational SemVer of the server binary. */
+  readonly server_version: string;
+  /** Always 1 in this version. */
+  readonly protocol_version: number;
+  /** Client MUST send auth.login within this window (ms). */
+  readonly auth_timeout_ms: number;
+  /** How often client should send sys.ping (ms). */
+  readonly ping_interval_ms: number;
+  /** How long server will wait for pong (ms). */
+  readonly ping_timeout_ms: number;
+  /** Server node that accepted this connection. */
+  readonly node_id?: string;
+  /** Supported features the server advertises. */
+  readonly features?: readonly string[];
+}
+
+export interface SysPingPayload {
+  /** Timestamp from the sender for RTT calculation. */
+  readonly sent_ts: number;
+}
+
+export interface SysPongPayload {
+  /** Mirrors the ping's sent_ts. */
+  readonly sent_ts: number;
+  /** Server-side processing time in ms. */
+  readonly server_ms?: number;
+}
+
+export interface SysDisconnectPayload {
+  /** Machine-readable reason code. */
+  readonly code: string;
+  /** Human-readable message. */
+  readonly message?: string;
+  /** Minimum ms to wait before reconnecting. */
+  readonly retry_after_ms?: number;
+  /** Whether the client should attempt to reconnect at all. */
+  readonly permanent?: boolean;
+}
+
+export interface SysRateLimitedPayload {
+  /** How long to wait before resuming sends (ms). */
+  readonly retry_after_ms: number;
+  /** The limit that was breached, e.g. "100/10s". */
+  readonly limit: string;
+  /** How many tokens remain. */
+  readonly remaining?: number;
+}
+
+// ─── Auth payloads ────────────────────────────────────────────────────────────
+
+export interface AuthLoginPayload {
+  readonly token: string;
+  readonly token_type: "bearer";
+  /** Optional device fingerprint for audit logs. */
+  readonly device_id?: string;
+}
+
+export interface AuthOkPayload {
+  readonly user_id: string;
+  readonly socket_id: string;
+  /** Unix ms when the session token expires. */
+  readonly expires_at: number;
+  /** Granted scopes. */
+  readonly scopes?: readonly string[];
+  /** Arbitrary per-user metadata the server attaches. */
+  readonly meta?: Record<string, unknown>;
+}
+
+export interface AuthRefreshPayload {
+  readonly token: string;
+  readonly token_type: "bearer";
+}
+
+export interface AuthRevokedPayload {
+  /** Why the session was revoked. */
+  readonly reason: string;
+}
+
+// ─── Ack payloads ─────────────────────────────────────────────────────────────
+
+export interface AckOkPayload {
+  /** The id of the frame being acknowledged. */
+  readonly ref_id: string;
+  /** Server-side processing latency (ms). */
+  readonly latency_ms: number;
+  /** High-level delivery status. */
+  readonly status: OperationStatus;
+  /** Optional data the server attaches to the ack (e.g. persisted record ID). */
+  readonly data?: Record<string, unknown>;
+}
+
+export interface AckErrorPayload {
+  readonly ref_id: string;
+  readonly code: string;
+  readonly message: string;
+  /** Field-level validation details. */
+  readonly details?: ReadonlyArray<{ field: string; message: string }>;
+}
+
+// ─── Error payloads ───────────────────────────────────────────────────────────
+
+export interface ErrorPayload {
+  readonly code: string;
+  readonly message: string;
+  /** The id of the frame that caused this error, if applicable. */
+  readonly ref_id?: string;
+  /** Field-level validation errors. */
+  readonly details?: ReadonlyArray<{ field: string; message: string }>;
+  /** Machine-readable hint for the client. */
+  readonly hint?: string;
+}
+
+// ─── Presence payloads ────────────────────────────────────────────────────────
+
+export interface PresenceInfo {
+  readonly socket_id: string;
+  readonly user_id: string;
+  readonly node_id: string;
+  readonly connect_at: number;
+  /** Custom attributes set by the server (display_name, avatar, role, …). */
+  readonly meta?: Record<string, unknown>;
+}
+
+export interface PresenceLeftPayload {
+  readonly socket_id: string;
+  readonly user_id: string;
+  readonly disconnect_at: number;
+}
+
+export interface PresenceUpdatePayload extends PresenceInfo {
+  readonly changed_fields: readonly string[];
+}
+
+export interface PresenceListPayload {
+  /** Optional scope (room, channel) to filter by. */
+  readonly scope?: string;
+}
+
+export interface PresenceSnapshotPayload {
+  /** Mirrors the id of the presence.list request. */
+  readonly request_id: string;
+  readonly count: number;
+  readonly users: readonly PresenceInfo[];
+  readonly scope?: string;
+}
+
+// ─── Typed envelope aliases ───────────────────────────────────────────────────
+// Convenient aliases used internally and re-exported for consumers.
+
+export type SysConnectedEnvelope = Envelope<SysConnectedPayload>;
+export type SysPingEnvelope = Envelope<SysPingPayload>;
+export type SysPongEnvelope = Envelope<SysPongPayload>;
+export type SysDisconnectEnvelope = Envelope<SysDisconnectPayload>;
+export type SysRateLimitedEnvelope = Envelope<SysRateLimitedPayload>;
+export type AuthOkEnvelope = Envelope<AuthOkPayload>;
+export type AuthRevokedEnvelope = Envelope<AuthRevokedPayload>;
+export type AckOkEnvelope = Envelope<AckOkPayload>;
+export type AckErrorEnvelope = Envelope<AckErrorPayload>;
+export type ErrorEnvelope = Envelope<ErrorPayload>;
+
+// ─── Client config ────────────────────────────────────────────────────────────
+
+export interface LiveFrameClientConfig {
+  /** WebSocket URL. MUST use wss:// in production. */
+  readonly url: string;
+  /** Called to supply the initial Bearer token. */
+  // ? readonly getToken: () => Promise<string>
+  /** Called before token expiry. Defaults to getToken. */
+  // ? readonly refreshToken?: () => Promise<string>
+  /** Device fingerprint included in auth.login (optional). */
+  readonly deviceId?: string;
+  /** ms to wait for auth.ok. Default: 10 000. */
+  // ? readonly authTimeoutMs?: number
+  /** ms to wait for ack.ok. Default: 5 000. */
+  // ? readonly ackTimeoutMs?: number
+  /** 0 = unlimited reconnect attempts. Default: 0. */
+  readonly maxReconnectAttempts?: number;
+  /** Base delay for exponential backoff. Default: 250. */
+  readonly reconnectBaseMs?: number;
+  /** Maximum backoff delay. Default: 30 000. */
+  readonly reconnectCapMs?: number;
+  /** Called on every state transition. */
+  readonly onStateChange?: (
+    state: import("./constants").ConnectionState,
+    prev: import("./constants").ConnectionState,
+  ) => void;
+  /** Called on every received envelope after internal handling. */
+  readonly onMessage?: (env: Envelope) => void;
+  /** Called on unrecoverable errors (bad auth, max retries). */
+  readonly onFatalError?: (reason: string, code?: number) => void;
+  /** Custom logger. Defaults to console. */
+  readonly logger?: Logger;
+}
+
+export interface Logger {
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+
+// ─── Send options ─────────────────────────────────────────────────────────────
+
+export interface SendOptions {
+  /** Request server-side acknowledgement. Default: false. */
+  readonly ack?: boolean;
+  /** Override the default ack timeout (ms). */
+  readonly ackTimeoutMs?: number;
+  /** Idempotency key. If set, retries with the same key are deduplicated. */
+  readonly idempotencyKey?: string;
+}