@hashxltd/liveframe-vue 0.0.1

package/src/transport/index.ts

@@ -0,0 +1,212 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Owns the raw WebSocket lifecycle: HTTP→WS upgrade, send, receive, close.
+// Everything above this layer works with decoded Envelope objects only.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { WS_SUBPROTOCOL, CloseCodes } from "../protocol/constants";
+import { encode, decode } from "../protocol/codec";
+import type { Envelope, Logger } from "../protocol/types";
+import { TransportError, TransportErrorCode } from "../errors";
+import { TypedEmitter } from "../utils";
+
+// ─── Transport events ─────────────────────────────────────────────────────────
+
+interface TransportEvents extends Record<string, unknown> {
+  /** Fired once the WebSocket handshake completes (HTTP 101). */
+  open: void;
+  /** Fired for every successfully decoded inbound frame. */
+  message: Envelope;
+  /** Fired on any raw decode / transport error (non-fatal — logged only). */
+  error: Error;
+  /** Fired when the socket closes, for any reason. */
+  close: { code: number; reason: string; wasClean: boolean };
+}
+
+// ─── Transport ────────────────────────────────────────────────────────────────
+
+export class Transport extends TypedEmitter<TransportEvents> {
+  private ws: WebSocket | null = null;
+  private _url: string;
+  private log: Logger;
+
+  constructor(url: string, logger: Logger) {
+    super();
+    this._url = this.validateUrl(url);
+    this.log = logger;
+  }
+
+  // ─── Public ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Upgrades the HTTP connection to WebSocket.
+   *
+   * The browser/Node.js runtime performs the actual HTTP→WS handshake
+   * (sends `Upgrade: websocket`, `Connection: Upgrade`, `Sec-WebSocket-Key`,
+   * etc. and awaits the `101 Switching Protocols` response).
+   *
+   * We request the `wsframe.v1` sub-protocol so the server can reject
+   * unknown clients early, before any application logic runs.
+   *
+   * @param connectTimeoutMs  Maximum ms to wait for the WS open event.
+   */
+  open(connectTimeoutMs = 10_000): Promise<void> {
+    if (this.ws && this.ws.readyState < WebSocket.CLOSING) {
+      return Promise.resolve(); // already open
+    }
+
+    return new Promise<void>((resolve, reject) => {
+      let settled = false;
+
+      const settle = (fn: () => void) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        fn();
+      };
+
+      const timer = setTimeout(() => {
+        settle(() => {
+          this.ws?.close();
+          reject(
+            new TransportError(
+              TransportErrorCode.CONNECT_TIMEOUT,
+              `WebSocket did not open within ${connectTimeoutMs}ms`,
+            ),
+          );
+        });
+      }, connectTimeoutMs);
+
+      let ws: WebSocket;
+      try {
+        ws = new WebSocket(this._url, [WS_SUBPROTOCOL]);
+      } catch (err) {
+        settle(() =>
+          reject(
+            new TransportError(
+              TransportErrorCode.UPGRADE_FAILED,
+              `WebSocket constructor threw: ${(err as Error).message}`,
+            ),
+          ),
+        );
+        return;
+      }
+
+      ws.binaryType = "arraybuffer"; // we don't use binary, but be explicit
+
+      ws.onopen = () => {
+        this.ws = ws;
+        this.log.debug("[transport] WebSocket open", { protocol: ws.protocol });
+        this.emit("open", undefined as unknown as void);
+        settle(resolve);
+      };
+
+      ws.onmessage = (ev: MessageEvent<string>) => {
+        this.handleIncoming(ev.data);
+      };
+
+      ws.onerror = () => {
+        // The browser intentionally gives no detail here (security).
+        // We log and let onclose carry the code.
+        const err = new TransportError(
+          TransportErrorCode.UPGRADE_FAILED,
+          "WebSocket error event fired",
+        );
+        this.log.warn("[transport] WebSocket error event");
+        this.emit("error", err);
+        settle(() => reject(err)); // only matters if we haven't opened yet
+      };
+
+      ws.onclose = (ev: CloseEvent) => {
+        this.ws = null;
+        this.log.info("[transport] closed", {
+          code: ev.code,
+          reason: ev.reason,
+        });
+        this.emit("close", {
+          code: ev.code,
+          reason: ev.reason,
+          wasClean: ev.wasClean,
+        });
+      };
+    });
+  }
+
+  /**
+   * Serialises and sends an envelope.
+   * Throws TransportError if the socket is not open.
+   */
+  send<P>(env: Envelope<P>): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new TransportError(
+        TransportErrorCode.SOCKET_CLOSED,
+        `Cannot send event "${env.event}": socket is not open`,
+      );
+    }
+    const frame = encode(env); // throws FrameError if > 64 KB
+    this.ws.send(frame);
+  }
+
+  /**
+   * Closes the WebSocket with the given code and reason.
+   * Safe to call when already closed.
+   */
+  close(code: number = CloseCodes.NORMAL, reason: string = ""): void {
+    if (this.ws && this.ws.readyState < WebSocket.CLOSING) {
+      this.ws.close(code, reason);
+    }
+  }
+
+  get isOpen(): boolean {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+
+  get bufferedAmount(): number {
+    return this.ws?.bufferedAmount ?? 0;
+  }
+
+  // ─── Private ────────────────────────────────────────────────────────────────
+
+  private handleIncoming(raw: string): void {
+    try {
+      const env = decode(raw);
+      this.emit("message", env);
+    } catch (err) {
+      this.log.warn("[transport] malformed frame — dropped", { err });
+      this.emit("error", err as Error);
+    }
+  }
+
+  private validateUrl(url: string): string {
+    let parsed: URL;
+    try {
+      parsed = new URL(url);
+    } catch {
+      throw new TransportError(
+        TransportErrorCode.UPGRADE_FAILED,
+        `Invalid WebSocket URL: "${url}"`,
+      );
+    }
+
+    if (parsed.protocol === "http:") {
+      // Rewrite http: → ws: so consumers can pass HTTP URLs conveniently.
+      parsed.protocol = "ws:";
+    } else if (parsed.protocol === "https:") {
+      parsed.protocol = "wss:";
+    }
+
+    const secure = parsed.protocol === "wss:";
+
+    // Block plaintext connections when the page itself is HTTPS.
+    const pageIsSecure =
+      typeof location !== "undefined" && location.protocol === "https:";
+
+    if (!secure && pageIsSecure) {
+      throw new TransportError(
+        TransportErrorCode.INSECURE_URL,
+        `Insecure ws:// connection blocked on an HTTPS origin. Use wss://.`,
+      );
+    }
+
+    return parsed.toString();
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,157 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Zero-dependency utilities used throughout the library.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ─── UUID v4 ──────────────────────────────────────────────────────────────────
+
+export function uuid(): string {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID()
+  }
+  // Fallback: Math.random-based (non-cryptographic, acceptable for frame IDs)
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0
+    return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16)
+  })
+}
+
+// ─── Exponential backoff with full jitter ─────────────────────────────────────
+
+/**
+ * Returns the next reconnect delay using full-jitter exponential backoff.
+ * delay = rand(0, min(cap, base × 2^attempt))
+ */
+export function backoffMs(attempt: number, baseMs: number, capMs: number): number {
+  const ceiling = Math.min(capMs, baseMs * Math.pow(2, attempt))
+  return Math.floor(Math.random() * ceiling)
+}
+
+// ─── Deferred promise ─────────────────────────────────────────────────────────
+
+export interface Deferred<T> {
+  promise: Promise<T>
+  resolve(value: T | PromiseLike<T>): void
+  reject(reason?: unknown): void
+}
+
+export function deferred<T>(): Deferred<T> {
+  let resolve!: Deferred<T>['resolve']
+  let reject!: Deferred<T>['reject']
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+// ─── Typed event emitter ──────────────────────────────────────────────────────
+
+type Listener<T> = (data: T) => void
+type AnyListener = Listener<unknown>
+
+export class TypedEmitter<Events extends Record<string, unknown>> {
+  private readonly _listeners = new Map<string, Set<AnyListener>>()
+
+  /** Subscribe. Returns an unsubscribe function. */
+  on<K extends keyof Events & string>(event: K, fn: Listener<Events[K]>): () => void {
+    let set = this._listeners.get(event)
+    if (!set) {
+      set = new Set()
+      this._listeners.set(event, set)
+    }
+    set.add(fn as AnyListener)
+    return () => this.off(event, fn)
+  }
+
+  /** Subscribe once, then auto-unsubscribe. */
+  once<K extends keyof Events & string>(event: K, fn: Listener<Events[K]>): () => void {
+    const wrapped = (data: Events[K]) => {
+      fn(data)
+      this.off(event, wrapped)
+    }
+    return this.on(event, wrapped)
+  }
+
+  off<K extends keyof Events & string>(event: K, fn: Listener<Events[K]>): void {
+    this._listeners.get(event)?.delete(fn as AnyListener)
+  }
+
+  emit<K extends keyof Events & string>(event: K, data: Events[K]): void {
+    this._listeners.get(event)?.forEach((fn) => {
+      try {
+        fn(data)
+      } catch {
+        /* isolate listener errors */
+      }
+    })
+  }
+
+  /** Remove all listeners, optionally scoped to one event. */
+  removeAllListeners(event?: keyof Events & string): void {
+    if (event) {
+      this._listeners.delete(event)
+    } else {
+      this._listeners.clear()
+    }
+  }
+}
+
+// ─── Token bucket (client-side rate limiting) ─────────────────────────────────
+
+export class TokenBucket {
+  private tokens: number
+  private windowAt: number
+
+  constructor(
+    private readonly capacity: number,
+    private readonly windowMs: number,
+  ) {
+    this.tokens = capacity
+    this.windowAt = Date.now()
+  }
+
+  /** Returns true when a token was consumed; false when empty. */
+  tryConsume(): boolean {
+    this.refill()
+    if (this.tokens <= 0) return false
+    this.tokens -= 1
+    return true
+  }
+
+  get remaining(): number {
+    this.refill()
+    return this.tokens
+  }
+
+  get nextRefillMs(): number {
+    const elapsed = Date.now() - this.windowAt
+    return Math.max(0, this.windowMs - elapsed)
+  }
+
+  private refill(): void {
+    if (Date.now() - this.windowAt >= this.windowMs) {
+      this.tokens = this.capacity
+      this.windowAt = Date.now()
+    }
+  }
+}
+
+// ─── Abort-aware sleep ────────────────────────────────────────────────────────
+
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException('Aborted', 'AbortError'))
+      return
+    }
+    const t = setTimeout(resolve, ms)
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(t)
+        reject(new DOMException('Aborted', 'AbortError'))
+      },
+      { once: true },
+    )
+  })
+}

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}