@bytecodealliance/preview3-shim 0.1.1 → 0.2.0

package/dist/nodejs/sockets/error.d.ts

@@ -0,0 +1,83 @@
+export declare const ERROR_MAP: {
+    EACCES: string;
+    EPERM: string;
+    EOPNOTSUPP: string;
+    ENOPROTOOPT: string;
+    EPFNOSUPPORT: string;
+    EPROTONOSUPPORT: string;
+    ESOCKTNOSUPPORT: string;
+    EINVAL: string;
+    EAFNOSUPPORT: string;
+    ENOMEM: string;
+    ENOBUFS: string;
+    ETIMEDOUT: string;
+    EADDRINUSE: string;
+    EADDRNOTAVAIL: string;
+    EHOSTUNREACH: string;
+    EHOSTDOWN: string;
+    ENETUNREACH: string;
+    ENETDOWN: string;
+    ENONET: string;
+    ECONNREFUSED: string;
+    EPIPE: string;
+    ECONNRESET: string;
+    ECONNABORTED: string;
+    EMSGSIZE: string;
+    ENOTCONN: string;
+    EISCONN: string;
+    EALREADY: string;
+    EDESTADDRREQ: string;
+};
+export declare const CODE_MAP: {
+    4053: string;
+    4083: string;
+    ENOTCONN: string;
+    EBADF: string;
+    EACCES: string;
+    EPERM: string;
+    ENOTSUP: string;
+    EOPNOTSUPP: string;
+    ENOPROTOOPT: string;
+    EPFNOSUPPORT: string;
+    EPROTONOSUPPORT: string;
+    ESOCKTNOSUPPORT: string;
+    EINVAL: string;
+    EAFNOSUPPORT: string;
+    ENOMEM: string;
+    ENOBUFS: string;
+    4090: string;
+    EADDRNOTAVAIL: string;
+    4091: string;
+    EADDRINUSE: string;
+    EHOSTUNREACH: string;
+    EHOSTDOWN: string;
+    ENETUNREACH: string;
+    ENETDOWN: string;
+    ENONET: string;
+    ECONNREFUSED: string;
+    EPIPE: string;
+    ECONNRESET: string;
+    ECONNABORTED: string;
+    EMSGSIZE: string;
+};
+/**
+ * Custom error for Socket operations with JCO compatible payload.
+ *
+ * https://bytecodealliance.github.io/jco/wit-type-representations.html#result-considerations-idiomatic-js-errors-for-host-implementations
+ */
+export declare class SocketError extends Error {
+    payload: any;
+    /**
+     * @param {string} tag        – machine‐readable error tag
+     * @param {string} [message]  – human‐readable message
+     * @param {any}    [val]      – optional extra data
+     */
+    constructor(tag: any, message?: any, val?: any, opts?: {
+        cause?: unknown;
+    });
+    /**
+     * Create or rewrap an error into SocketError
+     * @param {any} err – number, string, Error, or SocketError
+     */
+    static from(err: any): SocketError;
+}

package/dist/nodejs/sockets/error.js

@@ -0,0 +1,120 @@
+export const ERROR_MAP = {
+    EACCES: "access-denied",
+    EPERM: "access-denied",
+    EOPNOTSUPP: "not-supported",
+    ENOPROTOOPT: "not-supported",
+    EPFNOSUPPORT: "not-supported",
+    EPROTONOSUPPORT: "not-supported",
+    ESOCKTNOSUPPORT: "not-supported",
+    EINVAL: "invalid-argument",
+    EAFNOSUPPORT: "invalid-argument",
+    ENOMEM: "out-of-memory",
+    ENOBUFS: "out-of-memory",
+    ETIMEDOUT: "timeout",
+    EADDRINUSE: "address-in-use",
+    EADDRNOTAVAIL: "address-not-bindable",
+    EHOSTUNREACH: "remote-unreachable",
+    EHOSTDOWN: "remote-unreachable",
+    ENETUNREACH: "remote-unreachable",
+    ENETDOWN: "remote-unreachable",
+    ENONET: "remote-unreachable",
+    ECONNREFUSED: "connection-refused",
+    EPIPE: "connection-broken",
+    ECONNRESET: "connection-reset",
+    ECONNABORTED: "connection-aborted",
+    EMSGSIZE: "datagram-too-large",
+    ENOTCONN: "invalid-state",
+    EISCONN: "invalid-state",
+    EALREADY: "invalid-state",
+    EDESTADDRREQ: "invalid-argument",
+};
+export const CODE_MAP = {
+    4053: "invalid-state",
+    4083: "invalid-state",
+    ENOTCONN: "invalid-state",
+    EBADF: "invalid-state",
+    EACCES: "access-denied",
+    EPERM: "access-denied",
+    ENOTSUP: "not-supported",
+    EOPNOTSUPP: "not-supported",
+    ENOPROTOOPT: "not-supported",
+    EPFNOSUPPORT: "not-supported",
+    EPROTONOSUPPORT: "not-supported",
+    ESOCKTNOSUPPORT: "not-supported",
+    EINVAL: "invalid-argument",
+    EAFNOSUPPORT: "invalid-argument",
+    ENOMEM: "out-of-memory",
+    ENOBUFS: "out-of-memory",
+    4090: "address-not-bindable",
+    EADDRNOTAVAIL: "address-not-bindable",
+    4091: "address-in-use",
+    EADDRINUSE: "address-in-use",
+    EHOSTUNREACH: "remote-unreachable",
+    EHOSTDOWN: "remote-unreachable",
+    ENETUNREACH: "remote-unreachable",
+    ENETDOWN: "remote-unreachable",
+    ENONET: "remote-unreachable",
+    ECONNREFUSED: "connection-refused",
+    EPIPE: "connection-broken",
+    ECONNRESET: "connection-reset",
+    ECONNABORTED: "connection-aborted",
+    EMSGSIZE: "datagram-too-large",
+};
+/**
+ * Custom error for Socket operations with JCO compatible payload.
+ *
+ * https://bytecodealliance.github.io/jco/wit-type-representations.html#result-considerations-idiomatic-js-errors-for-host-implementations
+ */
+export class SocketError extends Error {
+    payload;
+    /**
+     * @param {string} tag        – machine‐readable error tag
+     * @param {string} [message]  – human‐readable message
+     * @param {any}    [val]      – optional extra data
+     */
+    constructor(tag, message = undefined, val = undefined, opts = {}) {
+        super(message ?? `Error: ${tag}`, { cause: opts.cause });
+        this.name = "SocketError";
+        this.payload = val !== undefined ? { tag, val } : { tag };
+    }
+    /**
+     * Create or rewrap an error into SocketError
+     * @param {any} err – number, string, Error, or SocketError
+     */
+    static from(err) {
+        if (err instanceof SocketError) {
+            return err;
+        }
+        let tag, message, val;
+        if (typeof err === "number") {
+            tag = CODE_MAP[err] ?? "other";
+            message = `Error code ${err}`;
+            if (tag === "other") {
+                val = message;
+            }
+        }
+        else if (typeof err === "string") {
+            tag = ERROR_MAP[err] ?? "other";
+            if (tag === "other") {
+                val = err;
+            }
+        }
+        else if (err && typeof err.code === "string") {
+            tag = ERROR_MAP[err.code] ?? "other";
+            message = err.message;
+            if (tag === "other") {
+                val = err.code;
+            }
+        }
+        else if (err && typeof err.message === "string" && ERROR_MAP[err.message]) {
+            tag = ERROR_MAP[err.message];
+            message = err.message;
+        }
+        else {
+            tag = "other";
+            message = err?.message;
+            val = message;
+        }
+        return new SocketError(tag, message, val);
+    }
+}

package/dist/nodejs/sockets/ip-name-lookup.d.ts

@@ -0,0 +1,18 @@
+export declare const ipNameLookup: {
+    /**
+     * Resolve an internet host name to a list of IP addresses.
+     *
+     * WIT:
+     * ```
+     * resolve-addresses: async func(name: string) -> result<list<ip-address>, error-code>
+     * ```
+     *
+     * @param {string} name - Host name or IP address to resolve.
+     * @returns {Promise<Array<{tag: "ipv4" | "ipv6", val: number[]}>>}
+     * @throws {SocketError} payload.tag maps to wasi:sockets/ip-name-lookup error-code.
+     */
+    resolveAddresses(name: any): Promise<{
+        tag: string;
+        val: any;
+    }[]>;
+};

package/dist/nodejs/sockets/ip-name-lookup.js

@@ -0,0 +1,84 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { domainToASCII } from "node:url";
+import { ipv4ToTuple, ipv6ToTuple } from "./address.js";
+import { SocketError } from "./error.js";
+const DNS_ERROR_MAP = {
+    EACCES: "access-denied",
+    EPERM: "access-denied",
+    EINVAL: "invalid-argument",
+    ENOTFOUND: "name-unresolvable",
+    EAI_ADDRFAMILY: "name-unresolvable",
+    EAI_AGAIN: "temporary-resolver-failure",
+    EAI_FAIL: "permanent-resolver-failure",
+    EAI_NODATA: "name-unresolvable",
+    EAI_NONAME: "name-unresolvable",
+};
+function ipAddress(address, family) {
+    switch (family) {
+        case 4:
+            return { tag: "ipv4", val: ipv4ToTuple(address) };
+        case 6:
+            return { tag: "ipv6", val: ipv6ToTuple(address) };
+        default:
+            throw new SocketError("other", `Unknown IP address family: ${family}`, `${family}`);
+    }
+}
+function normalizeLookupName(name) {
+    if (typeof name !== "string" || name === "" || name.trim() !== name) {
+        throw new SocketError("invalid-argument");
+    }
+    if (name.startsWith("[") || name.endsWith("]")) {
+        const bracketedIpv6 = name.match(/^\[([^\]]+)\]$/);
+        if (bracketedIpv6 && isIP(bracketedIpv6[1]) === 6) {
+            return bracketedIpv6[1];
+        }
+        throw new SocketError("invalid-argument");
+    }
+    if (isIP(name) !== 0) {
+        return name;
+    }
+    const asciiName = domainToASCII(name);
+    if (asciiName === "") {
+        throw new SocketError("invalid-argument");
+    }
+    return asciiName;
+}
+export const ipNameLookup = {
+    /**
+     * Resolve an internet host name to a list of IP addresses.
+     *
+     * WIT:
+     * ```
+     * resolve-addresses: async func(name: string) -> result<list<ip-address>, error-code>
+     * ```
+     *
+     * @param {string} name - Host name or IP address to resolve.
+     * @returns {Promise<Array<{tag: "ipv4" | "ipv6", val: number[]}>>}
+     * @throws {SocketError} payload.tag maps to wasi:sockets/ip-name-lookup error-code.
+     */
+    async resolveAddresses(name) {
+        try {
+            const lookupName = normalizeLookupName(name);
+            const literalFamily = isIP(lookupName);
+            if (literalFamily !== 0) {
+                return [ipAddress(lookupName, literalFamily)];
+            }
+            const addresses = await lookup(lookupName, { all: true, verbatim: false });
+            const result = addresses.map(({ address, family }) => ipAddress(address, family));
+            if (result.length === 0) {
+                throw new SocketError("name-unresolvable");
+            }
+            return result;
+        }
+        catch (error) {
+            if (error instanceof SocketError) {
+                throw error;
+            }
+            const tag = DNS_ERROR_MAP[error?.code] ?? "other";
+            throw new SocketError(tag, error?.message, tag === "other" ? error?.code : undefined, {
+                cause: error,
+            });
+        }
+    },
+};

package/dist/nodejs/sockets/tcp.d.ts

@@ -0,0 +1,333 @@
+import { StreamReader } from "../stream.js";
+import { FutureReader } from "../future.js";
+/**
+ * Creates a new TCP socket
+ * WIT: createTcpSocket: func(address-family: ip-address-family) -> result<tcp-socket, error-code>
+ *
+ * @param {IP_ADDRESS_FAMILY} addressFamily - The IP address family (IPv4 or IPv6)
+ * @returns {TcpSocket>} A new TCP socket instance
+ * @throws {SocketError} with payload.tag 'invalid-argument' if `addressFamily` is not IPV4 or IPV6
+ * @throws {SocketError} for other errors, payload.tag maps the low-level system error_
+ */
+export declare function createTcpSocket(addressFamily: any): TcpSocket;
+export declare class TcpSocket {
+    #private;
+    /**
+     * WIT static constructor for `wasi:sockets/types.tcp-socket`.
+     *
+     * WIT:
+     * ```
+     * create: static func(address-family: ip-address-family) -> result<tcp-socket, error-code>
+     * ```
+     *
+     * @static
+     * @param {IP_ADDRESS_FAMILY} addressFamily - The IP address family (IPv4 or IPv6)
+     * @returns {TcpSocket} A new TcpSocket instance
+     * @throws {SocketError} with payload.tag 'invalid-argument' if `addressFamily` is not IPV4 or IPV6
+     * @throws {SocketError} for other socket creation errors
+     */
+    static create(addressFamily: any): TcpSocket;
+    /**
+     * Creates a new TCP socket
+     * WIT:
+     * ```
+     * constructor(address-family: ip-address-family)
+     * ```
+     *
+     * @static
+     * @param {IP_ADDRESS_FAMILY} addressFamily - The IP address family (IPv4 or IPv6)
+     * @param {number} socketId - The internal socket identifier
+     * @returns {TcpSocket} A new TcpSocket instance
+     * @private
+     */
+    static _create(t: any, addressFamily: any, socketId: any): TcpSocket;
+    /**
+     * Binds the socket to a local address
+     * WIT:
+     * ```
+     * bind: func(local-address: ip-socket-address) -> result<_, error-code>
+     * ```
+     *
+     * @param {Object} localAddress - The local address to bind to
+     * @returns {void}
+     * @throws {SocketError} with payload.tag 'invalid-state' if the socket is not in ~STATE.UNBOUND~
+     * @throws {SocketError} with payload.tag 'invalid-argument' if ~localAddress~ is invalid
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    bind(localAddress: any): void;
+    /**
+     * Connects to a remote endpoint
+     * WIT:
+     * ```
+     * connect: async func(remote-address: ip-socket-address) -> result<_, error-code>
+     * ```
+     *
+     * @async
+     * @param {Object} remoteAddress - The remote address to connect to
+     * @returns {Promise<void>}
+     * @throws {SocketError} with payload.tag 'invalid-state' if socket is CONNECTING, CONNECTED, or LISTENING
+     * @throws {SocketError} with payload.tag 'invalid-argument' if ~remoteAddress~ is invalid or port == 0
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    connect(remoteAddress: any): Promise<void>;
+    /**
+     * Starts listening for connections
+     * WIT:
+     * ```
+     * listen: func() -> result<stream<tcp-socket>, error-code>
+     * ```
+     *
+     * @returns {StreamReader} A stream of incoming TCP socket connections
+     * @throws {SocketError} with payload.tag 'invalid-state' if socket is LISTENING or CONNECTED
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    listen(): StreamReader;
+    /**
+     * Sends data to the connected peer
+     * WIT:
+     * ```
+     * send: async func(data: stream<u8>) -> result<_, error-code>
+     * ```
+     *
+     * @async
+     * @param {object} data - The byte stream to send.
+     * @returns {Promise<void>}
+     * @throws {SocketError} With payload.tag 'invalid-state' if socket is not CONNECTED
+     * @throws {SocketError} With payload.tag 'invalid-argument' if `data` is not a readable byte stream
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    send(data: any): Promise<void>;
+    /**
+     * Receives data from the connected peer
+     * WIT:
+     * ```
+     * receive: func() -> tuple<stream<u8>, future<result<_, error-code>>>
+     * ```
+     *
+     * @throws {SocketError} with payload.tag 'invalid-state' if socket is not CONNECTED
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     * @returns {{ stream: StreamReader, future: FutureReader }}
+     */
+    receive(): (StreamReader | FutureReader)[];
+    /**
+     * Gets the bound local address
+     * WIT:
+     * ```
+     * local-address: func() -> result<ip-socket-address, error-code>
+     * ```
+     *
+     * @returns {Object} The local socket address
+     * @throws {SocketError} with payload.tag 'invalid-state' if socket is not BOUND
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    getLocalAddress(): any;
+    /**
+     * Gets the remote address
+     * WIT:
+     * ```
+     * remote-address: func() -> result<ip-socket-address, error-code>
+     * ```
+     *
+     * @returns {Object} The remote socket address
+     * @throws {SocketError} with payload.tag 'invalid-state' if socket is not CONNECTED
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    getRemoteAddress(): any;
+    /**
+     * Checks if the socket is in listening state
+     * WIT:
+     * ```
+     * is-listening: func() -> bool
+     * ```
+     *
+     * @returns {boolean} True if socket is listening, false otherwise
+     */
+    getIsListening(): boolean;
+    /**
+     * Gets the address family
+     * WIT:
+     * ```
+     * address-family: func() -> ip-address-family
+     * ```
+     *
+     * @returns {IP_ADDRESS_FAMILY} The IP address family (IPv4 or IPv6)
+     */
+    getAddressFamily(): any;
+    /**
+     * Sets the listen backlog size
+     * WIT:
+     * ```
+     * set-listen-backlog-size: func(value: u64) -> result<_, error-code>
+     * ```
+     *
+     * @param {bigint} value - The backlog size
+     * @returns {void}
+     * @throws {SocketError} with payload.tag 'invalid-argument' if `value` is 0
+     * @throws {SocketError} with payload.tag 'not-supported' if socket is CONNECTING or CONNECTED
+     * @throws {SocketError} with payload.tag 'invalid-state' if socket is not UNBOUND or BOUND
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    setListenBacklogSize(value: any): void;
+    /**
+     * Gets whether keep-alive is enabled
+     * WIT:
+     * ```
+     * keep-alive-enabled: func() -> result<bool, error-code>
+     * ```
+     *
+     * @returns {boolean} True if keep-alive is enabled, false otherwise
+     */
+    getKeepAliveEnabled(): boolean;
+    /**
+     * Sets keep-alive enabled state
+     * WIT:
+     * ```
+     * set-keep-alive-enabled: func(value: bool) -> result<_, error-code>
+     * ```
+     *
+     * @async
+     * @param {boolean} value - Whether to enable keep-alive
+     * @returns {void}
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    setKeepAliveEnabled(value: any): void;
+    /**
+     * Gets the keep-alive idle time
+     * WIT:
+     * ```
+     * keep-alive-idle-time: func() -> result<duration, error-code>
+     * ```
+     *
+     * @returns {bigint} The keep-alive idle time in nanoseconds
+     */
+    getKeepAliveIdleTime(): bigint;
+    /**
+     * Sets the keep-alive idle time
+     * WIT:
+     * ```
+     * set-keep-alive-idle-time: func(value: duration) -> result<_, error-code>
+     * ```
+     *
+     * @param {bigint} value - The idle time in nanoseconds
+     * @returns {void}
+     * @throws {SocketError} with payload.tag 'invalid-argument' if `value` is less than 1
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    setKeepAliveIdleTime(value: any): void;
+    /**
+     * Gets the keep-alive interval
+     * WIT:
+     * ```
+     * keep-alive-interval: func() -> result<duration, error-code>
+     * ```
+     *
+     * @returns {bigint} The keep-alive interval in nanoseconds
+     */
+    getKeepAliveInterval(): bigint;
+    /**
+     * Sets the keep-alive interval
+     * WIT:
+     * ```
+     * set-keep-alive-interval: func(value: duration) -> result<_, error-code>
+     * ```
+     *
+     * @param {bigint} value - The interval in nanoseconds
+     * @returns {void}
+     * @throws {SocketError} with payload.tag 'invalid-argument' if `value` is less than 1
+     */
+    setKeepAliveInterval(value: any): void;
+    /**
+     * Gets the keep-alive count
+     * WIT:
+     * ```
+     * keep-alive-count: func() -> result<u32, error-code>
+     * ```
+     *
+     * @returns {number} The keep-alive count
+     */
+    getKeepAliveCount(): number;
+    /**
+     * Sets the keep-alive count
+     * WIT:
+     * ```
+     * set-keep-alive-count: func(value: u32) -> result<_, error-code>
+     * ```
+     *
+     * @param {number} value - The keep-alive count
+     * @returns {void}
+     * @throws {SocketError} with payload.tag 'invalid-argument' if `value` is less than 1
+     */
+    setKeepAliveCount(value: any): void;
+    /**
+     * Gets the hop limit
+     * WIT:
+     * ```
+     * hop-limit: func() -> result<u8, error-code>
+     * ```
+     *
+     * @returns {number} The hop limit
+     */
+    getHopLimit(): number;
+    /**
+     * Sets the hop limit
+     * WIT:
+     * ```
+     * set-hop-limit: func(value: u8) -> result<_, error-code>
+     * ```
+     *
+     * @param {number} value - The hop limit
+     * @returns {void}
+     * @throws {SocketError} with payload.tag 'invalid-argument' if `value` is less than 1
+     */
+    setHopLimit(value: any): void;
+    /**
+     * Gets the receive buffer size
+     * WIT:
+     * ```
+     * receive-buffer-size: func() -> result<u64, error-code>
+     * ```
+     *
+     * @returns {bigint} The receive buffer size in bytes
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    getReceiveBufferSize(): any;
+    /**
+     * Sets the receive buffer size
+     * WIT:
+     * ```
+     * set-receive-buffer-size: func(value: u64) -> result<_, error-code>
+     * ```
+     *
+     * @param {bigint} value - The receive buffer size in bytes
+     * @returns {void}
+     * @throws {SocketError} with payload.tag 'invalid-argument' if `value` is 0
+     */
+    setReceiveBufferSize(value: any): void;
+    /**
+     * Gets the send buffer size
+     * WIT:
+     * ```
+     * send-buffer-size: func() -> result<u64, error-code>
+     * ```
+     *
+     * @returns {bigint} The send buffer size in bytes
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    getSendBufferSize(): any;
+    /**
+     * Sets the send buffer size
+     * WIT:
+     * ```
+     * set-send-buffer-size: func(value: u64) -> result<_, error-code>
+     * ```
+     *
+     * @param {bigint} value - The send buffer size in bytes
+     * @returns {void}
+     * @throws {SocketError} with payload.tag 'invalid-argument' if `value` is 0
+     */
+    setSendBufferSize(value: any): void;
+    /**
+     * Disposes the socket
+     */
+    [Symbol.dispose](): void;
+}