@abndnce/pulsar-client 0.0.7 → 0.0.9

package/dist/index.d.mts

@@ -16,7 +16,8 @@ interface PulsarClientConnection {
  *
  * @param host  Server IP address
  * @param port  Server UDP port
- * @returns A connected PulsarClientConnection with an open keepalive channel.
+ * @returns A connected PulsarClientConnection with an open keepalive channel
+ *          and a `connect()` helper for opening socket tunnels.
  */
 declare function connectDirect(host: string, port: number): Promise<PulsarClientConnection>;
 //#endregion
@@ -29,4 +30,93 @@ declare function connectDirect(host: string, port: number): Promise<PulsarClient
  */
 declare function connectNostr(_relay: string, _pubkey: string): Promise<PulsarClientConnection>;
 //#endregion
-export { type PulsarClientConnection, connectDirect, connectNostr };
+//#region lib/socket-channel.d.ts
+/**
+ * Shared utilities for opening Pulsar socket tunnel data channels.
+ *
+ * These work with any RTCPeerConnection, regardless of how it was
+ * established (direct, nostr, etc.).
+ */
+/**
+ * Wait for an RTCDataChannel to enter the "open" state.
+ *
+ * Also monitors the RTCPeerConnection for failure/closure, and
+ * accepts an optional AbortSignal for cancellation.
+ *
+ * Rejects if the channel closes, the peer connection fails, or
+ * the timeout elapses before the channel opens.
+ */
+declare function waitForDataChannelOpen(channel: RTCDataChannel, pc: RTCPeerConnection, timeoutMs?: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Create a data channel on the given `pc` with the Pulsar socket label
+ * convention (`socket/<hostname>:<port>`) and wait for it to open.
+ *
+ * This is the low-level primitive used by `connect()` and
+ * `libcurlTransport()`.
+ */
+declare function openSocketChannel(pc: RTCPeerConnection, hostname: string, port: number, timeoutMs?: number, signal?: AbortSignal): Promise<RTCDataChannel>;
+//#endregion
+//#region lib/tunnel.d.ts
+/**
+ * WebSocket-compatible wrapper around an RTCDataChannel.
+ *
+ * libcurl.js compares `readyState` against `WebSocket.OPEN` (numeric 1)
+ * and expects static constants (`CONNECTING`, `OPEN`, `CLOSING`, `CLOSED`).
+ * Using `EventTarget` ensures `addEventListener` / `removeEventListener`
+ * work, which libcurl's poll loop depends on.
+ */
+declare class DataChannelSocket extends EventTarget {
+  static readonly CONNECTING = 0;
+  static readonly OPEN = 1;
+  static readonly CLOSING = 2;
+  static readonly CLOSED = 3;
+  readonly CONNECTING = 0;
+  readonly OPEN = 1;
+  readonly CLOSING = 2;
+  readonly CLOSED = 3;
+  readonly url: string;
+  readonly protocol = "";
+  readonly extensions = "";
+  binaryType: string;
+  onopen: ((event: Event) => void) | null;
+  onclose: ((event: CloseEvent) => void) | null;
+  onerror: ((event: Event) => void) | null;
+  onmessage: ((event: MessageEvent) => void) | null;
+  private _channel;
+  private _closed;
+  private _closeDispatched;
+  private _readyState;
+  constructor(pc: RTCPeerConnection, destination: string);
+  private _open;
+  get readyState(): number;
+  get bufferedAmount(): number;
+  send(data: string | ArrayBufferLike | ArrayBufferView): void;
+  close(): void;
+  private _dispatch;
+  private _dispatchError;
+  private _dispatchClose;
+}
+/**
+ * Create a libcurl.js transport factory from an existing WebRTC
+ * peer connection.
+ *
+ * Usage:
+ * ```ts
+ * import { connectDirect, libcurlTransport } from '@abndnce/pulsar-client';
+ * import { libcurl } from 'libcurl.js';
+ *
+ * const tunnel = await connectDirect('216.250.119.217', 42069);
+ * libcurl.transport = libcurlTransport(tunnel.pc);
+ * libcurl.set_websocket('wss://pulsar-tunnel.local/');
+ * ```
+ *
+ * libcurl.js calls the factory with URLs like:
+ *   `wss://pulsar-tunnel.local/example.com:80`
+ *   `wss://pulsar-tunnel.local/216.250.119.217:443`
+ *
+ * The factory parses `<hostname>:<port>` from the URL path, opens a
+ * Pulsar socket data channel, and returns a WebSocket-like adapter.
+ */
+declare function libcurlTransport(pc: RTCPeerConnection): (url: string) => DataChannelSocket;
+//#endregion
+export { type PulsarClientConnection, connectDirect, connectNostr, libcurlTransport, openSocketChannel, waitForDataChannelOpen };

package/dist/index.mjs

@@ -1,7 +1,11 @@
-//#region ../core/credentials.ts
+//#region ../core/constants.ts
 const PULSAR_UFRAG = "pulsar";
 const PULSAR_PWD = "pulsarpulsarpulsarpuls";
 const PULSAR_FINGERPRINT = "F1:85:10:8F:36:FF:58:D8:D0:4B:52:D7:ED:DC:5C:28:AE:7D:DB:54:0E:2A:DD:C7:C3:94:EA:A1:27:D0:4E:78";
+/** Label prefix for socket tunnel data channels. */
+const SOCKET_PREFIX = "socket/";
+/** Label for the mandatory keepalive data channel. */
+const KEEPALIVE_LABEL = "keepalive";
 //#endregion
 //#region lib/connection/direct.ts
 /**
@@ -11,11 +15,12 @@ const PULSAR_FINGERPRINT = "F1:85:10:8F:36:FF:58:D8:D0:4B:52:D7:ED:DC:5C:28:AE:7
 *
 * @param host  Server IP address
 * @param port  Server UDP port
-* @returns A connected PulsarClientConnection with an open keepalive channel.
+* @returns A connected PulsarClientConnection with an open keepalive channel
+*          and a `connect()` helper for opening socket tunnels.
 */
 async function connectDirect(host, port) {
 	const pc = new RTCPeerConnection();
-	const keepalive = pc.createDataChannel("keepalive", { ordered: true });
+	const keepalive = pc.createDataChannel(KEEPALIVE_LABEL, { ordered: true });
 	const offer = await pc.createOffer();
 	await pc.setLocalDescription(offer);
 	const remoteSdp = [
@@ -77,4 +82,221 @@ async function connectNostr(_relay, _pubkey) {
 	throw new Error("Nostr mode not yet implemented");
 }
 //#endregion
-export { connectDirect, connectNostr };
+//#region lib/socket-channel.ts
+/**
+* Shared utilities for opening Pulsar socket tunnel data channels.
+*
+* These work with any RTCPeerConnection, regardless of how it was
+* established (direct, nostr, etc.).
+*/
+/**
+* Wait for an RTCDataChannel to enter the "open" state.
+*
+* Also monitors the RTCPeerConnection for failure/closure, and
+* accepts an optional AbortSignal for cancellation.
+*
+* Rejects if the channel closes, the peer connection fails, or
+* the timeout elapses before the channel opens.
+*/
+function waitForDataChannelOpen(channel, pc, timeoutMs = 1e4, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new DOMException("The operation was aborted.", "AbortError"));
+			return;
+		}
+		if (channel.readyState === "open") {
+			resolve();
+			return;
+		}
+		const timeout = setTimeout(() => {
+			cleanup();
+			reject(/* @__PURE__ */ new Error(`DataChannel open timed out after ${timeoutMs}ms`));
+		}, timeoutMs);
+		const cleanup = () => {
+			clearTimeout(timeout);
+			channel.removeEventListener("open", onOpen);
+			channel.removeEventListener("close", onClose);
+			channel.removeEventListener("error", onError);
+			pc.removeEventListener("connectionstatechange", onStateChange);
+			signal?.removeEventListener("abort", onAbort);
+		};
+		const onOpen = () => {
+			cleanup();
+			resolve();
+		};
+		const onClose = () => {
+			cleanup();
+			reject(/* @__PURE__ */ new Error("DataChannel closed before opening"));
+		};
+		const onError = () => {
+			cleanup();
+			reject(/* @__PURE__ */ new Error("DataChannel error before opening"));
+		};
+		const onStateChange = () => {
+			if (pc.connectionState === "failed" || pc.connectionState === "closed") {
+				cleanup();
+				reject(/* @__PURE__ */ new Error(`Peer connection ${pc.connectionState}`));
+			}
+		};
+		const onAbort = () => {
+			cleanup();
+			reject(new DOMException("The operation was aborted.", "AbortError"));
+		};
+		channel.addEventListener("open", onOpen, { once: true });
+		channel.addEventListener("close", onClose, { once: true });
+		channel.addEventListener("error", onError, { once: true });
+		pc.addEventListener("connectionstatechange", onStateChange);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/**
+* Create a data channel on the given `pc` with the Pulsar socket label
+* convention (`socket/<hostname>:<port>`) and wait for it to open.
+*
+* This is the low-level primitive used by `connect()` and
+* `libcurlTransport()`.
+*/
+function openSocketChannel(pc, hostname, port, timeoutMs, signal) {
+	const label = `${SOCKET_PREFIX}${hostname}:${port}`;
+	const channel = pc.createDataChannel(label, { ordered: true });
+	return waitForDataChannelOpen(channel, pc, timeoutMs, signal).then(() => channel);
+}
+//#endregion
+//#region lib/tunnel.ts
+/**
+* WebSocket-compatible wrapper around an RTCDataChannel.
+*
+* libcurl.js compares `readyState` against `WebSocket.OPEN` (numeric 1)
+* and expects static constants (`CONNECTING`, `OPEN`, `CLOSING`, `CLOSED`).
+* Using `EventTarget` ensures `addEventListener` / `removeEventListener`
+* work, which libcurl's poll loop depends on.
+*/
+var DataChannelSocket = class DataChannelSocket extends EventTarget {
+	static CONNECTING = 0;
+	static OPEN = 1;
+	static CLOSING = 2;
+	static CLOSED = 3;
+	CONNECTING = 0;
+	OPEN = 1;
+	CLOSING = 2;
+	CLOSED = 3;
+	url;
+	protocol = "";
+	extensions = "";
+	binaryType = "arraybuffer";
+	onopen = null;
+	onclose = null;
+	onerror = null;
+	onmessage = null;
+	_channel = null;
+	_closed = false;
+	_closeDispatched = false;
+	_readyState = DataChannelSocket.CONNECTING;
+	constructor(pc, destination) {
+		super();
+		this.url = `wss://pulsar-tunnel.local/${destination}`;
+		const channel = pc.createDataChannel(`${SOCKET_PREFIX}${destination}`, { ordered: true });
+		channel.binaryType = "arraybuffer";
+		this._channel = channel;
+		this._open(channel, pc);
+	}
+	async _open(channel, pc) {
+		try {
+			await waitForDataChannelOpen(channel, pc);
+		} catch (error) {
+			if (!this._closed) {
+				console.error(`[DataChannelSocket] Failed to open channel: ${error instanceof Error ? error.message : String(error)}`);
+				this._dispatchError();
+			}
+			this._dispatchClose();
+			return;
+		}
+		if (this._closed) {
+			channel.close();
+			this._dispatchClose();
+			return;
+		}
+		this._channel = channel;
+		this._readyState = DataChannelSocket.OPEN;
+		channel.onmessage = (event) => {
+			this._dispatch(new MessageEvent("message", { data: event.data }));
+		};
+		channel.onclose = () => {
+			this._readyState = DataChannelSocket.CLOSED;
+			this._dispatchClose();
+		};
+		channel.onerror = () => {
+			this._dispatchError();
+		};
+		this._dispatch(new Event("open"));
+	}
+	get readyState() {
+		return this._readyState;
+	}
+	get bufferedAmount() {
+		return this._channel?.bufferedAmount ?? 0;
+	}
+	send(data) {
+		if (this._readyState !== DataChannelSocket.OPEN || !this._channel) throw new Error("DataChannelSocket is not open");
+		if (typeof data === "string") this._channel.send(data);
+		else this._channel.send(data);
+	}
+	close() {
+		if (this._closed) return;
+		this._closed = true;
+		if (this._channel && this._channel.readyState !== "closed") this._channel.close();
+		else this._dispatchClose();
+	}
+	_dispatch(event) {
+		const handlerName = `on${event.type}`;
+		const handler = this[handlerName];
+		if (handler) handler(event);
+		this.dispatchEvent(event);
+	}
+	_dispatchError() {
+		this._dispatch(new Event("error"));
+	}
+	_dispatchClose() {
+		if (this._closeDispatched) return;
+		this._closeDispatched = true;
+		this._readyState = DataChannelSocket.CLOSED;
+		this._dispatch(new CloseEvent("close"));
+	}
+};
+/**
+* Create a libcurl.js transport factory from an existing WebRTC
+* peer connection.
+*
+* Usage:
+* ```ts
+* import { connectDirect, libcurlTransport } from '@abndnce/pulsar-client';
+* import { libcurl } from 'libcurl.js';
+*
+* const tunnel = await connectDirect('216.250.119.217', 42069);
+* libcurl.transport = libcurlTransport(tunnel.pc);
+* libcurl.set_websocket('wss://pulsar-tunnel.local/');
+* ```
+*
+* libcurl.js calls the factory with URLs like:
+*   `wss://pulsar-tunnel.local/example.com:80`
+*   `wss://pulsar-tunnel.local/216.250.119.217:443`
+*
+* The factory parses `<hostname>:<port>` from the URL path, opens a
+* Pulsar socket data channel, and returns a WebSocket-like adapter.
+*/
+function libcurlTransport(pc) {
+	return (url) => {
+		let dest;
+		try {
+			dest = new URL(url).pathname.replace(/^\//, "").replace(/\/$/, "");
+		} catch {
+			const slash = url.indexOf("/", url.indexOf("//") + 2);
+			dest = slash === -1 ? url : url.slice(slash + 1);
+		}
+		if (!dest) throw new Error(`libcurl transport: no destination found in URL "${url}"`);
+		if (dest.lastIndexOf(":") === -1) throw new Error(`libcurl transport: invalid destination "${dest}" — expected "hostname:port"`);
+		return new DataChannelSocket(pc, dest);
+	};
+}
+//#endregion
+export { connectDirect, connectNostr, libcurlTransport, openSocketChannel, waitForDataChannelOpen };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@abndnce/pulsar-client",
   "type": "module",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "homepage": "https://github.com/abndnce/pulsar",
   "license": "MIT",
   "exports": {