@abndnce/pulsar-client 0.0.7 → 0.0.8

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,75 @@ 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.
+ * Rejects if it closes or errors before opening.
+ */
+declare function waitForDataChannelOpen(channel: RTCDataChannel, timeoutMs?: number): 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): Promise<RTCDataChannel>;
+//#endregion
+//#region lib/tunnel.d.ts
+/**
+ * A minimal WebSocket-like wrapper around an RTCDataChannel.
+ *
+ * libcurl.js expects its transport factory to return objects
+ * with `send()`, `close()`, `onopen`, `onmessage`, `onclose`,
+ * and `onerror` — which is exactly the RTCDataChannel API, so
+ * the wrapper is thin.
+ */
+declare class DataChannelSocket {
+  private _channel;
+  private _closed;
+  onopen: (() => void) | null;
+  onmessage: ((event: {
+    data: ArrayBuffer | string;
+  }) => void) | null;
+  onclose: (() => void) | null;
+  onerror: ((event: {
+    error?: string;
+  }) => void) | null;
+  constructor(channel: RTCDataChannel);
+  get readyState(): string;
+  get binaryType(): string;
+  set binaryType(_: string);
+  send(data: ArrayBuffer | string | ArrayBufferView): void;
+  close(): void;
+}
+/**
+ * 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,144 @@ 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.
+* Rejects if it closes or errors before opening.
+*/
+function waitForDataChannelOpen(channel, timeoutMs = 1e4) {
+	return new Promise((resolve, reject) => {
+		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.onopen = null;
+			channel.onclose = null;
+			channel.onerror = null;
+		};
+		channel.onopen = () => {
+			cleanup();
+			resolve();
+		};
+		channel.onclose = () => {
+			cleanup();
+			reject(/* @__PURE__ */ new Error("DataChannel closed before opening"));
+		};
+		channel.onerror = (e) => {
+			cleanup();
+			reject(/* @__PURE__ */ new Error(`DataChannel error before opening: ${e}`));
+		};
+	});
+}
+/**
+* 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) {
+	const label = `${SOCKET_PREFIX}${hostname}:${port}`;
+	const channel = pc.createDataChannel(label, { ordered: true });
+	return waitForDataChannelOpen(channel, timeoutMs).then(() => channel);
+}
+//#endregion
+//#region lib/tunnel.ts
+/**
+* A minimal WebSocket-like wrapper around an RTCDataChannel.
+*
+* libcurl.js expects its transport factory to return objects
+* with `send()`, `close()`, `onopen`, `onmessage`, `onclose`,
+* and `onerror` — which is exactly the RTCDataChannel API, so
+* the wrapper is thin.
+*/
+var DataChannelSocket = class {
+	_channel;
+	_closed = false;
+	onopen = null;
+	onmessage = null;
+	onclose = null;
+	onerror = null;
+	constructor(channel) {
+		this._channel = channel;
+		channel.onopen = () => {
+			if (!this._closed) this.onopen?.();
+		};
+		channel.onmessage = (event) => {
+			if (!this._closed) this.onmessage?.({ data: event.data });
+		};
+		channel.onclose = () => {
+			this._closed = true;
+			this.onclose?.();
+		};
+		channel.onerror = (event) => {
+			this.onerror?.({ error: String(event) });
+		};
+	}
+	get readyState() {
+		return this._channel.readyState;
+	}
+	get binaryType() {
+		return "arraybuffer";
+	}
+	set binaryType(_) {}
+	send(data) {
+		if (this._closed || this._channel.readyState !== "open") return;
+		this._channel.send(data);
+	}
+	close() {
+		this._closed = true;
+		try {
+			this._channel.close();
+		} catch {}
+	}
+};
+/**
+* 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.createDataChannel(`${SOCKET_PREFIX}${dest}`, { ordered: true }));
+	};
+}
+//#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.8",
   "homepage": "https://github.com/abndnce/pulsar",
   "license": "MIT",
   "exports": {