@sigx/lynx-websocket 0.1.0

package/dist/websocket.js

@@ -0,0 +1,429 @@
+/**
+ * Browser-standard `WebSocket` client backed by the `@sigx/lynx-websocket`
+ * native module (URLSessionWebSocketTask on iOS, OkHttp WebSocket on
+ * Android).
+ *
+ * Public surface mirrors the WHATWG WebSocket interface:
+ *
+ *   new WebSocket(url, protocols?)
+ *   .readyState / .url / .protocol / .extensions / .bufferedAmount
+ *   .binaryType        ('arraybuffer' only — 'blob' is not supported)
+ *   .onopen / .onmessage / .onerror / .onclose
+ *   .addEventListener / .removeEventListener / .dispatchEvent
+ *   .send(string | ArrayBuffer | ArrayBufferView)
+ *   .close(code?, reason?)
+ *
+ * Multi-socket dispatch: each instance is assigned a monotonic numeric id.
+ * The native side emits a single `__sigxWebSocketEvent` global event
+ * carrying `{ id, type, ... }`; the JS shim demultiplexes by id and fires
+ * the matching instance's listeners.
+ */
+import { callAsync, guardModule, isModuleAvailable } from '@sigx/lynx-core';
+const MODULE = 'WebSocket';
+const EVENT_NAME = '__sigxWebSocketEvent';
+function lynxObj() {
+    return typeof lynx !== 'undefined' ? lynx : undefined;
+}
+const CONNECTING = 0;
+const OPEN = 1;
+const CLOSING = 2;
+const CLOSED = 3;
+/**
+ * Decode a base64 string into an `ArrayBuffer`. Lynx's BTS runtime has
+ * `atob` per the platform docs, but fall back to a manual decoder to keep
+ * this shim portable across hosts where it might be absent.
+ */
+function base64ToArrayBuffer(b64) {
+    if (typeof atob === 'function') {
+        const bin = atob(b64);
+        const buf = new ArrayBuffer(bin.length);
+        const view = new Uint8Array(buf);
+        for (let i = 0; i < bin.length; i++)
+            view[i] = bin.charCodeAt(i);
+        return buf;
+    }
+    // Pure-JS fallback. Not the fastest, but executed at most for binary
+    // frames on hosts that ship no atob (vanishingly rare).
+    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+    const lookup = new Int8Array(256).fill(-1);
+    for (let i = 0; i < chars.length; i++)
+        lookup[chars.charCodeAt(i)] = i;
+    const clean = b64.replace(/=+$/, '');
+    const out = new Uint8Array((clean.length * 3) >> 2);
+    let p = 0;
+    let buf = 0;
+    let bits = 0;
+    for (let i = 0; i < clean.length; i++) {
+        const v = lookup[clean.charCodeAt(i)];
+        if (v < 0)
+            continue;
+        buf = (buf << 6) | v;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[p++] = (buf >> bits) & 0xff;
+        }
+    }
+    return out.buffer;
+}
+/**
+ * Encode an `ArrayBuffer` / view to base64 for transport to native.
+ * Native side base64-decodes back to raw bytes before sending on the wire.
+ */
+function arrayBufferToBase64(buf) {
+    const bytes = new Uint8Array(buf);
+    if (typeof btoa === 'function') {
+        // Build the binary string in chunks to dodge call-stack limits on
+        // large frames (String.fromCharCode.apply blows up around ~64k args).
+        let bin = '';
+        const CHUNK = 0x8000;
+        for (let i = 0; i < bytes.length; i += CHUNK) {
+            bin += String.fromCharCode.apply(null, Array.from(bytes.subarray(i, i + CHUNK)));
+        }
+        return btoa(bin);
+    }
+    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+    let out = '';
+    let i = 0;
+    for (; i + 2 < bytes.length; i += 3) {
+        const n = (bytes[i] << 16) | (bytes[i + 1] << 8) | bytes[i + 2];
+        out += chars[(n >> 18) & 63] + chars[(n >> 12) & 63] + chars[(n >> 6) & 63] + chars[n & 63];
+    }
+    if (i < bytes.length) {
+        const rem = bytes.length - i;
+        const n = rem === 1 ? bytes[i] << 16 : (bytes[i] << 16) | (bytes[i + 1] << 8);
+        out += chars[(n >> 18) & 63] + chars[(n >> 12) & 63];
+        out += rem === 2 ? chars[(n >> 6) & 63] + '=' : '==';
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Shared event dispatch — one global lynx listener that demuxes by socket id.
+const sockets = new Map();
+let nextId = 1;
+let subscribed = false;
+let cachedEmitter = null;
+function ensureSubscribed() {
+    if (subscribed)
+        return;
+    const emitter = lynxObj()?.getJSModule?.('GlobalEventEmitter');
+    if (!emitter)
+        return; // web/SSR/test — events simply won't arrive
+    cachedEmitter = emitter;
+    emitter.addListener(EVENT_NAME, (raw) => {
+        // Lynx ships event params as a single JSON-shaped object or as the
+        // first arg of the listener. Tolerate both shapes.
+        const evt = typeof raw === 'string' ? safeParse(raw) : raw;
+        if (!evt || typeof evt.id !== 'number')
+            return;
+        const ws = sockets.get(evt.id);
+        if (!ws)
+            return;
+        // Internal dispatch lives on the instance so it can mutate state.
+        ws._dispatch(evt);
+    });
+    subscribed = true;
+}
+function safeParse(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+/**
+ * WHATWG-compatible WebSocket. Drop-in for browser code.
+ *
+ * @example
+ * ```ts
+ * const ws = new WebSocket('wss://ws.postman-echo.com/raw');
+ * ws.onopen = () => ws.send('hello');
+ * ws.onmessage = e => console.log(e.data);
+ * ```
+ */
+export class WebSocket {
+    get readyState() {
+        return this._readyState;
+    }
+    constructor(url, protocols) {
+        this.CONNECTING = CONNECTING;
+        this.OPEN = OPEN;
+        this.CLOSING = CLOSING;
+        this.CLOSED = CLOSED;
+        this.protocol = '';
+        this.extensions = '';
+        this.bufferedAmount = 0;
+        this.binaryType = 'arraybuffer';
+        this.onopen = null;
+        this.onmessage = null;
+        this.onerror = null;
+        this.onclose = null;
+        this._readyState = CONNECTING;
+        this._listeners = Object.create(null);
+        if (typeof url !== 'string' || url.length === 0) {
+            throw new TypeError(`WebSocket: invalid URL`);
+        }
+        // Match browsers: only ws:/wss: are valid. We accept http:/https: too
+        // and let the native side reject — some debug proxies normalise.
+        const colon = url.indexOf(':');
+        if (colon <= 0) {
+            throw new SyntaxError(`WebSocket: invalid URL "${url}"`);
+        }
+        const scheme = url.slice(0, colon).toLowerCase();
+        if (scheme !== 'ws' && scheme !== 'wss' && scheme !== 'http' && scheme !== 'https') {
+            throw new SyntaxError(`WebSocket: unsupported URL scheme "${scheme}"`);
+        }
+        guardModule(MODULE);
+        this.url = url;
+        this._id = nextId++;
+        sockets.set(this._id, this);
+        ensureSubscribed();
+        const protoList = Array.isArray(protocols)
+            ? protocols
+            : typeof protocols === 'string' && protocols.length > 0
+                ? [protocols]
+                : [];
+        // Fire-and-forget — open/error are delivered through the event
+        // channel, not the callback. We still surface synchronous bridge
+        // failures (e.g. module not registered) as an async error event.
+        callAsync(MODULE, 'create', this._id, url, protoList).catch(err => {
+            this._dispatch({
+                id: this._id,
+                type: 'error',
+                data: err instanceof Error ? err.message : String(err),
+            });
+            this._dispatch({
+                id: this._id,
+                type: 'close',
+                code: 1006,
+                reason: '',
+                wasClean: false,
+            });
+        });
+    }
+    send(data) {
+        if (this._readyState === CONNECTING) {
+            // Browsers throw InvalidStateError here.
+            throw new Error("InvalidStateError: WebSocket is still in CONNECTING state.");
+        }
+        if (this._readyState !== OPEN) {
+            // Browsers silently drop on CLOSING/CLOSED but warn in devtools.
+            return;
+        }
+        let isBinary = false;
+        let payload;
+        if (typeof data === 'string') {
+            payload = data;
+        }
+        else if (data instanceof ArrayBuffer) {
+            isBinary = true;
+            payload = arrayBufferToBase64(data);
+        }
+        else if (ArrayBuffer.isView(data)) {
+            isBinary = true;
+            const view = data;
+            // Copy the active range out of the underlying buffer so we don't
+            // accidentally send bytes outside the view.
+            const slice = view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength);
+            payload = arrayBufferToBase64(slice);
+        }
+        else {
+            throw new TypeError('WebSocket.send: unsupported data type');
+        }
+        // bufferedAmount is approximated as the byte length the JS side has
+        // handed off — the native side acks via 'flushed' frames in a future
+        // version; for now this is a write-through counter.
+        this.bufferedAmount += isBinary ? base64ByteLength(payload) : utf8ByteLength(payload);
+        callAsync(MODULE, 'send', this._id, payload, isBinary).catch(err => {
+            this._dispatch({
+                id: this._id,
+                type: 'error',
+                data: err instanceof Error ? err.message : String(err),
+            });
+        });
+    }
+    close(code, reason) {
+        if (this._readyState === CLOSING || this._readyState === CLOSED)
+            return;
+        // WHATWG: code must be 1000 or 3000–4999. Validate to mirror browsers.
+        if (code !== undefined) {
+            if (code !== 1000 && (code < 3000 || code > 4999)) {
+                throw new Error(`InvalidAccessError: close code ${code} must be 1000 or in the 3000-4999 range.`);
+            }
+        }
+        if (reason !== undefined && utf8ByteLength(reason) > 123) {
+            throw new SyntaxError('SyntaxError: close reason must be ≤123 UTF-8 bytes.');
+        }
+        this._readyState = CLOSING;
+        callAsync(MODULE, 'close', this._id, code ?? 1000, reason ?? '').catch(err => {
+            // Bridge call itself failed (e.g. module missing). Synthesize an
+            // abnormal close so the instance doesn't get stuck in CLOSING and
+            // we still clean up sockets state.
+            this._dispatch({
+                id: this._id,
+                type: 'error',
+                data: err instanceof Error ? err.message : String(err),
+            });
+            this._dispatch({
+                id: this._id,
+                type: 'close',
+                code: 1006,
+                reason: '',
+                wasClean: false,
+            });
+        });
+    }
+    // -- EventTarget ---------------------------------------------------------
+    addEventListener(type, listener) {
+        var _a;
+        if (!listener)
+            return;
+        ((_a = this._listeners)[type] ?? (_a[type] = new Set())).add(listener);
+    }
+    removeEventListener(type, listener) {
+        this._listeners[type]?.delete(listener);
+    }
+    dispatchEvent(event) {
+        this._invoke(event.type, event);
+        return true;
+    }
+    // -- Internal ------------------------------------------------------------
+    /** @internal — called by the shared global-event subscriber. */
+    _dispatch(evt) {
+        switch (evt.type) {
+            case 'open': {
+                this._readyState = OPEN;
+                if (typeof evt.protocol === 'string')
+                    this.protocol = evt.protocol;
+                if (typeof evt.extensions === 'string')
+                    this.extensions = evt.extensions;
+                this._invoke('open', {
+                    type: 'open',
+                    target: this,
+                    currentTarget: this,
+                });
+                break;
+            }
+            case 'message': {
+                if (this._readyState !== OPEN)
+                    return;
+                let data;
+                if (evt.isBinary && typeof evt.binary === 'string') {
+                    data = base64ToArrayBuffer(evt.binary);
+                }
+                else {
+                    data = evt.data ?? '';
+                }
+                this._invoke('message', {
+                    type: 'message',
+                    target: this,
+                    currentTarget: this,
+                    data,
+                });
+                break;
+            }
+            case 'error': {
+                this._invoke('error', {
+                    type: 'error',
+                    target: this,
+                    currentTarget: this,
+                    message: evt.data,
+                });
+                break;
+            }
+            case 'close': {
+                if (this._readyState === CLOSED)
+                    return;
+                this._readyState = CLOSED;
+                sockets.delete(this._id);
+                this._invoke('close', {
+                    type: 'close',
+                    target: this,
+                    currentTarget: this,
+                    code: evt.code ?? 1006,
+                    reason: evt.reason ?? '',
+                    wasClean: evt.wasClean ?? false,
+                });
+                break;
+            }
+        }
+    }
+    _invoke(type, event) {
+        const handler = this[`on${type}`];
+        if (typeof handler === 'function') {
+            try {
+                handler.call(this, event);
+            }
+            catch (e) {
+                console.warn(`[WebSocket] on${type} handler threw:`, e);
+            }
+        }
+        const set = this._listeners[type];
+        if (set) {
+            for (const listener of set) {
+                try {
+                    if (typeof listener === 'function')
+                        listener.call(this, event);
+                    else
+                        listener.handleEvent(event);
+                }
+                catch (e) {
+                    console.warn(`[WebSocket] '${type}' listener threw:`, e);
+                }
+            }
+        }
+    }
+}
+WebSocket.CONNECTING = CONNECTING;
+WebSocket.OPEN = OPEN;
+WebSocket.CLOSING = CLOSING;
+WebSocket.CLOSED = CLOSED;
+/** Whether the native WebSocket module is registered in this build. */
+export function isWebSocketAvailable() {
+    return isModuleAvailable(MODULE);
+}
+// ---------------------------------------------------------------------------
+// Byte-length helpers (kept local to avoid pulling a dep).
+function utf8ByteLength(s) {
+    let n = 0;
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c < 0x80)
+            n += 1;
+        else if (c < 0x800)
+            n += 2;
+        else if (c >= 0xd800 && c <= 0xdbff) {
+            n += 4;
+            i++; // surrogate pair
+        }
+        else
+            n += 3;
+    }
+    return n;
+}
+function base64ByteLength(b64) {
+    const padding = b64.endsWith('==') ? 2 : b64.endsWith('=') ? 1 : 0;
+    return ((b64.length * 3) >> 2) - padding;
+}
+// Test-only escape hatch: exported under a stable name with a leading
+// underscore so it's tree-shakeable but reachable from unit tests.
+/** @internal */
+export const __internal = {
+    deliver(evt) {
+        const ws = sockets.get(evt.id);
+        if (ws)
+            ws._dispatch(evt);
+    },
+    reset() {
+        sockets.clear();
+        nextId = 1;
+        subscribed = false;
+        cachedEmitter = null;
+    },
+    get cachedEmitter() {
+        return cachedEmitter;
+    },
+};
+//# sourceMappingURL=websocket.js.map

package/dist/websocket.js.map

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

package/ios/WebSocketEventBus.swift

@@ -0,0 +1,86 @@
+import Foundation
+
+/// Process-wide pub/sub bus that owns the conversion of native WebSocket
+/// callbacks into JS-side event payloads. Sockets, sessions, and OS
+/// delegates write here; per-LynxView `WebSocketPublisher` instances read.
+///
+/// Mirrors the publisher pattern used elsewhere in the repo
+/// (`LinkingState`, `SafeAreaPublisher`, …): native lifecycle is decoupled
+/// from any specific LynxView so events survive view recreation and
+/// per-view subscribers can fan out without holding onto the WS task.
+final class WebSocketEventBus {
+
+    static let shared = WebSocketEventBus()
+
+    /// JSON-encodable payload pushed to JS as the single
+    /// `__sigxWebSocketEvent` global event. Keys match the `NativeEvent`
+    /// interface in `src/websocket.ts`.
+    typealias Payload = [String: Any]
+    typealias Listener = (Payload) -> Void
+
+    private let queue = DispatchQueue(label: "com.sigx.websocket.bus")
+    private var listeners: [(token: UUID, fn: Listener)] = []
+
+    @discardableResult
+    func addListener(_ fn: @escaping Listener) -> UUID {
+        let token = UUID()
+        queue.sync { listeners.append((token, fn)) }
+        return token
+    }
+
+    func removeListener(_ token: UUID) {
+        queue.sync { listeners.removeAll { $0.token == token } }
+    }
+
+    // MARK: - Publish
+
+    func publish(open protocolStr: String, extensions: String, id: Int) {
+        emit([
+            "id": id,
+            "type": "open",
+            "protocol": protocolStr,
+            "extensions": extensions,
+        ])
+    }
+
+    func publish(messageText text: String, id: Int) {
+        emit([
+            "id": id,
+            "type": "message",
+            "data": text,
+            "isBinary": false,
+        ])
+    }
+
+    func publish(messageBinary base64: String, id: Int) {
+        emit([
+            "id": id,
+            "type": "message",
+            "binary": base64,
+            "isBinary": true,
+        ])
+    }
+
+    func publish(error message: String, id: Int) {
+        emit([
+            "id": id,
+            "type": "error",
+            "data": message,
+        ])
+    }
+
+    func publish(close code: Int, reason: String, wasClean: Bool, id: Int) {
+        emit([
+            "id": id,
+            "type": "close",
+            "code": code,
+            "reason": reason,
+            "wasClean": wasClean,
+        ])
+    }
+
+    private func emit(_ payload: Payload) {
+        let snapshot = queue.sync { listeners }
+        for (_, fn) in snapshot { fn(payload) }
+    }
+}

package/ios/WebSocketModule.swift

@@ -0,0 +1,89 @@
+import Foundation
+import Lynx
+
+/// Native WebSocket bridge — JS-callable side.
+///
+/// JS usage (via the `@sigx/lynx-websocket` shim, not directly):
+///
+///   NativeModules.WebSocket.create(id, url, protocols, cb)
+///   NativeModules.WebSocket.send(id, payload, isBinary, cb)
+///   NativeModules.WebSocket.close(id, code, reason, cb)
+///
+/// Async lifecycle events (`open`, `message`, `error`, `close`) are pushed
+/// back via `WebSocketEventBus`, which a per-LynxView `WebSocketPublisher`
+/// forwards to JS through `LynxView.sendGlobalEvent("__sigxWebSocketEvent",
+/// [...])`.
+///
+/// Implemented with `URLSessionWebSocketTask` (iOS 13+). Each socket is
+/// stored in `tasks` keyed by the JS-supplied numeric id; the same id is
+/// echoed back in every event so the JS shim can demultiplex.
+@objc class WebSocketModule: NSObject, LynxModule {
+
+    @objc static var name: String { "WebSocket" }
+
+    @objc static var methodLookup: [String: String] {
+        [
+            "create": NSStringFromSelector(#selector(create(_:url:protocols:callback:))),
+            "send":   NSStringFromSelector(#selector(send(_:payload:isBinary:callback:))),
+            "close":  NSStringFromSelector(#selector(close(_:code:reason:callback:))),
+        ]
+    }
+
+    required override init() { super.init() }
+    required init(param: Any) { super.init() }
+
+    // MARK: - JS-callable methods
+
+    @objc func create(_ id: NSNumber, url: String?, protocols: [Any]?, callback: LynxCallbackBlock?) {
+        guard let urlString = url, let parsed = URL(string: urlString) else {
+            WebSocketEventBus.shared.publish(error: "Invalid URL", id: id.intValue)
+            WebSocketEventBus.shared.publish(close: 1006, reason: "Invalid URL", wasClean: false, id: id.intValue)
+            callback?(NSNull())
+            return
+        }
+
+        var request = URLRequest(url: parsed)
+        if let protos = protocols as? [String], !protos.isEmpty {
+            request.setValue(protos.joined(separator: ", "), forHTTPHeaderField: "Sec-WebSocket-Protocol")
+        }
+
+        WebSocketTaskStore.shared.create(id: id.intValue, request: request)
+        callback?(NSNull())
+    }
+
+    @objc func send(_ id: NSNumber, payload: String?, isBinary: NSNumber?, callback: LynxCallbackBlock?) {
+        let binary = (isBinary?.boolValue ?? false)
+        guard let task = WebSocketTaskStore.shared.task(forId: id.intValue) else {
+            callback?(["error": "WebSocket \(id) not found"])
+            return
+        }
+
+        let message: URLSessionWebSocketTask.Message
+        if binary {
+            // Payload is base64-encoded on the JS side — decode to raw bytes.
+            guard let data = Data(base64Encoded: payload ?? "") else {
+                callback?(["error": "Invalid base64 payload"])
+                return
+            }
+            message = .data(data)
+        } else {
+            message = .string(payload ?? "")
+        }
+
+        task.send(message) { error in
+            if let error = error {
+                WebSocketEventBus.shared.publish(error: error.localizedDescription, id: id.intValue)
+            }
+        }
+        callback?(NSNull())
+    }
+
+    @objc func close(_ id: NSNumber, code: NSNumber?, reason: String?, callback: LynxCallbackBlock?) {
+        WebSocketTaskStore.shared.close(
+            id: id.intValue,
+            code: code?.intValue ?? 1000,
+            reason: reason ?? ""
+        )
+        callback?(NSNull())
+    }
+}

package/ios/WebSocketPublisher.swift

@@ -0,0 +1,34 @@
+import Foundation
+import Lynx
+
+/// Per-`LynxView` publisher that pumps `WebSocketEventBus` payloads into JS
+/// via `LynxView.sendGlobalEvent("__sigxWebSocketEvent", [...])`.
+///
+/// One instance per LynxView; instantiated by the generated
+/// `GeneratedLifecyclePublishers.attachAll(to:)` and retained for the
+/// LynxView's lifetime. The bus is global so opening a socket from one
+/// LynxView and reading it from another (via the JS shim) works, but in
+/// practice each LynxView holds its own JS heap so events are delivered to
+/// the matching view only.
+final class WebSocketPublisher {
+
+    private weak var lynxView: LynxView?
+    private var token: UUID?
+
+    init(lynxView: LynxView) {
+        self.lynxView = lynxView
+        self.token = WebSocketEventBus.shared.addListener { [weak self] payload in
+            guard let view = self?.lynxView else { return }
+            // sendGlobalEvent expects an array of params; pass a single
+            // dictionary as the only param, matching what the JS shim
+            // expects (it reads the first arg as `NativeEvent`).
+            view.sendGlobalEvent("__sigxWebSocketEvent", withParams: [payload])
+        }
+    }
+
+    deinit {
+        if let token = token {
+            WebSocketEventBus.shared.removeListener(token)
+        }
+    }
+}