@meshline/transport-node 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meshline contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# Node.js relay transport
+
+Cookie-free HTTPS and WebSocket adapters for Meshline on **Node.js 24 or later**.
+This ESM package includes TypeScript declarations.
+
+## Install and configure
+
+Install this adapter and the matching core together:
+
+```sh
+npm install @meshline/sdk@0.1.0-alpha.1 @meshline/transport-node@0.1.0-alpha.1
+```
+
+```ts
+import { createNodeRelayFetch, createNodeSocketFactory } from '@meshline/transport-node';
+
+const transport = {
+    fetch: createNodeRelayFetch(),
+    socketFactory: createNodeSocketFactory(),
+};
+```
+
+Spread these transport fields into `RelayClientPool` options alongside the
+network context and account ID. Pass the application registry as the pool's
+second argument. See the
+[Node session example](https://github.com/meshline-network/sdk/blob/main/typescript/examples/node.ts)
+for SQLite integration and resource ownership.
+
+## Transport behavior
+
+The adapters disable redirects, cookies, and implicit retries. HTTPS and WSS
+retain normal TLS certificate and hostname verification. The optional `ca`
+configuration trusts an explicit private network root only for this transport;
+it does not change process-wide trust settings.
+
+The WebSocket adapter uses `ws`, enforces the protocol's 1 MiB frame limit,
+rejects invalid UTF-8, and can send RFC 1003/1009 rejection close codes.
+Managers handle durable retries separately from the transport.
+
+[Transport guide](https://github.com/meshline-network/sdk/blob/main/typescript/docs/guides/transport.md)
+· [Platform requirements](https://github.com/meshline-network/sdk/blob/main/typescript/docs/platforms.md)

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { type RelayFetch, type RelaySocketFactory } from '@meshline/sdk';
+/** Optional explicit trust roots, e.g. a private network CA. TLS verification remains enabled. */
+export interface NodeTransportOptions {
+    readonly ca?: string | Uint8Array;
+}
+/** Cookie-free HTTPS with no redirects, caching, implicit retries or global TLS changes. */
+export declare function createNodeRelayFetch(options?: NodeTransportOptions): RelayFetch;
+/** Full RFC close codes and bounded frames; no cookies, redirects or compression negotiation. */
+export declare function createNodeSocketFactory(options?: NodeTransportOptions): RelaySocketFactory;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsC,KAAK,UAAU,EAAmD,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAE9J,kGAAkG;AAClG,MAAM,WAAW,oBAAoB;IAAG,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;CAAE;AAE3E,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,oBAAyB,GAAG,UAAU,CAsBnF;AAED,iGAAiG;AACjG,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,oBAAyB,GAAG,kBAAkB,CAyB9F"}

package/dist/index.js

@@ -0,0 +1,58 @@
+import { request } from 'node:https';
+import WebSocket from 'ws';
+import { maxSocketMessageBytes, webEndpoint } from '@meshline/sdk';
+/** Cookie-free HTTPS with no redirects, caching, implicit retries or global TLS changes. */
+export function createNodeRelayFetch(options = {}) {
+    const ca = typeof options.ca === 'string' || options.ca === undefined ? options.ca : Buffer.from(options.ca);
+    return (url, init) => new Promise((resolve, reject) => {
+        const endpoint = new URL(url);
+        if (endpoint.protocol !== 'https:' || endpoint.username || endpoint.password)
+            throw new TypeError('Expected a credential-free HTTPS request URL.');
+        const outgoing = request(endpoint, { method: init.method, headers: init.headers, signal: init.signal, ...(ca === undefined ? {} : { ca }) }, response => {
+            const headers = new Headers();
+            for (let index = 0; index < response.rawHeaders.length; index += 2)
+                headers.append(response.rawHeaders[index], response.rawHeaders[index + 1]);
+            resolve({
+                status: response.statusCode, headers,
+                body: { async cancel() { response.destroy(); } },
+                async arrayBuffer() {
+                    const chunks = [];
+                    for await (const chunk of response)
+                        chunks.push(chunk);
+                    const buffer = Buffer.concat(chunks);
+                    return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+                },
+            });
+        });
+        outgoing.on('error', reject);
+        outgoing.end(init.body);
+    });
+}
+/** Full RFC close codes and bounded frames; no cookies, redirects or compression negotiation. */
+export function createNodeSocketFactory(options = {}) {
+    const ca = typeof options.ca === 'string' || options.ca === undefined ? options.ca : Buffer.from(options.ca);
+    return endpoint => {
+        webEndpoint(endpoint, 'wss:');
+        // ws 8.22 supports closeTimeout; @types/ws 8.18 does not yet declare it.
+        const socketOptions = { followRedirects: false, perMessageDeflate: false,
+            maxPayload: maxSocketMessageBytes, handshakeTimeout: 60000, closeTimeout: 3000, ...(ca === undefined ? {} : { ca }) };
+        const socket = new WebSocket(endpoint, socketOptions);
+        return {
+            get readyState() { return socket.readyState; },
+            get bufferedAmount() { return socket.bufferedAmount; },
+            send(text) { socket.send(text); },
+            close(code, reason) { socket.close(code, reason); return code; },
+            on(event, listener) {
+                const handler = (...args) => {
+                    const value = event === 'open' ? undefined : event === 'error' ? args[0]
+                        : event === 'close' ? { code: args[0], reason: String(args[1]) }
+                            : args[1] ? args[0] : String(args[0]);
+                    listener(value);
+                };
+                socket.on(event, handler);
+                return () => { socket.off(event, handler); };
+            },
+        };
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@meshline/transport-node",
+  "version": "0.1.0-alpha.1",
+  "description": "Node.js HTTPS and WebSocket adapters for Meshline",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@meshline/sdk": "0.1.0-alpha.1"
+  },
+  "dependencies": {
+    "ws": "8.22.0"
+  },
+  "devDependencies": {
+    "@types/ws": "8.18.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/meshline-network/sdk.git",
+    "directory": "typescript/packages/transport-node"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+import { request } from 'node:https';
+import WebSocket from 'ws';
+import { maxSocketMessageBytes, webEndpoint, type RelayFetch, type RelayFetchResponse, type RelaySocketEvents, type RelaySocketFactory } from '@meshline/sdk';
+
+/** Optional explicit trust roots, e.g. a private network CA. TLS verification remains enabled. */
+export interface NodeTransportOptions { readonly ca?: string | Uint8Array }
+
+/** Cookie-free HTTPS with no redirects, caching, implicit retries or global TLS changes. */
+export function createNodeRelayFetch(options: NodeTransportOptions = {}): RelayFetch {
+    const ca = typeof options.ca === 'string' || options.ca === undefined ? options.ca : Buffer.from(options.ca);
+    return (url, init) => new Promise<RelayFetchResponse>((resolve, reject) => {
+        const endpoint = new URL(url);
+        if (endpoint.protocol !== 'https:' || endpoint.username || endpoint.password) throw new TypeError('Expected a credential-free HTTPS request URL.');
+        const outgoing = request(endpoint, { method: init.method, headers: init.headers, signal: init.signal, ...(ca === undefined ? {} : { ca }) }, response => {
+            const headers = new Headers();
+            for (let index = 0; index < response.rawHeaders.length; index += 2) headers.append(response.rawHeaders[index]!, response.rawHeaders[index + 1]!);
+            resolve({
+                status: response.statusCode!, headers,
+                body: { async cancel() { response.destroy(); } },
+                async arrayBuffer() {
+                    const chunks: Uint8Array[] = [];
+                    for await (const chunk of response) chunks.push(chunk as Uint8Array);
+                    const buffer = Buffer.concat(chunks);
+                    return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength) as ArrayBuffer;
+                },
+            });
+        });
+        outgoing.on('error', reject);
+        outgoing.end(init.body);
+    });
+}
+
+/** Full RFC close codes and bounded frames; no cookies, redirects or compression negotiation. */
+export function createNodeSocketFactory(options: NodeTransportOptions = {}): RelaySocketFactory {
+    const ca = typeof options.ca === 'string' || options.ca === undefined ? options.ca : Buffer.from(options.ca);
+    return endpoint => {
+        webEndpoint(endpoint, 'wss:');
+        // ws 8.22 supports closeTimeout; @types/ws 8.18 does not yet declare it.
+        const socketOptions: WebSocket.ClientOptions & { closeTimeout: number } = { followRedirects: false, perMessageDeflate: false,
+            maxPayload: maxSocketMessageBytes, handshakeTimeout: 60000, closeTimeout: 3000, ...(ca === undefined ? {} : { ca }) };
+        const socket = new WebSocket(endpoint, socketOptions);
+        return {
+            get readyState() { return socket.readyState; },
+            get bufferedAmount() { return socket.bufferedAmount; },
+            send(text) { socket.send(text); },
+            close(code, reason) { socket.close(code, reason); return code; },
+            on(event, listener) {
+                const handler = (...args: unknown[]): void => {
+                    const value = event === 'open' ? undefined : event === 'error' ? args[0]
+                        : event === 'close' ? { code: args[0], reason: String(args[1]) }
+                            : args[1] ? args[0] : String(args[0]);
+                    listener(value as RelaySocketEvents[typeof event]);
+                };
+                socket.on(event, handler);
+                return () => { socket.off(event, handler); };
+            },
+        };
+    };
+}