@bytecodealliance/preview3-shim 0.1.1 → 0.2.0

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

@@ -0,0 +1,224 @@
+/**
+ * Create a new UDP socket.
+ * WIT:
+ * ```
+ * createUdpSocket: func(address-family: ip-address-family) -> result<udp-socket, error-code>
+ * ```
+ *
+ * @async
+ * @param {IP_ADDRESS_FAMILY} addressFamily - The IP address family
+ * @returns {Promise<UdpSocket>}
+ * @throws {SocketError} with payload.tag 'invalid-argument' if ~addressFamily~ is not IPv4 or IPv6
+ * @throws {SocketError} for other errors, payload.tag maps the system error
+ */
+export declare function createUdpSocket(addressFamily: any): UdpSocket;
+export declare class UdpSocket {
+    #private;
+    /**
+     * WIT static constructor for `wasi:sockets/types.udp-socket`.
+     *
+     * WIT:
+     * ```
+     * create: static func(address-family: ip-address-family) -> result<udp-socket, error-code>
+     * ```
+     *
+     * @static
+     * @param {IP_ADDRESS_FAMILY} addressFamily - The IP address family (IPv4 or IPv6)
+     * @returns {UdpSocket} A new UdpSocket 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): UdpSocket;
+    /**
+     * Creates a new UDP socket
+     * WIT:
+     * ```
+     * constructor(address-family: ip-address-family)
+     * ```
+     *
+     * @static
+     * @param {IP_ADDRESS_FAMILY} addressFamily - The IP address family (IPv4 or IPv6)
+     * @param {string} socketId - The internal socket identifier
+     * @returns {UdpSocket} A new UdpSocket instance
+     * @private
+     */
+    static _create(t: any, addressFamily: any, socketId: any): UdpSocket;
+    /**
+     * Bind the socket to the provided IP address and port.
+     * 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;
+    /**
+     * Associate this socket with a specific peer address.
+     * WIT:
+     * ```
+     * connect: func(remote-address: ip-socket-address) -> result<_, error-code>
+     * ```
+     *
+     * @param {Object} remoteAddress - The remote address to connect to
+     * @returns {void}
+     * @throws {SocketError} with payload.tag 'invalid-state' if the socket is already connected
+     * @throws {SocketError} with payload.tag 'invalid-argument' if ~remoteAddress~ is invalid or wildcard
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    connect(remoteAddress: any): void;
+    /**
+     * Dissociate this socket from its peer address.
+     * WIT:
+     * ```
+     * disconnect: func() -> result<_, error-code>
+     * ```
+     *
+     * @returns {void}
+     * @throws {SocketError} with payload.tag 'invalid-state' if the socket is not connected
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    disconnect(): void;
+    /**
+     * Send a message on the socket to a particular peer.
+     * WIT:
+     * ```
+     * send: func(data: list<u8>, remote-address: option<ip-socket-address>) -> result<_, error-code>
+     * ```
+     *
+     * @async
+     * @param {Uint8Array} data - The datagram payload
+     * @param {?Object} remoteAddress Optional peer address if not connected.
+     * @returns {Promise<void>}
+     * @throws {SocketError} with payload.tag 'invalid-state' if socket is not bound
+     * @throws {SocketError} with payload.tag 'invalid-argument' if ~data~ is not a Uint8Array or address invalid
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    send(data: any, remoteAddress?: any): Promise<void>;
+    /**
+     * Receive a message on the socket.
+     * WIT:
+     * ```
+     * receive: func() -> result<tuple<list<u8>, ip-socket-address>, error-code>
+     * ```
+     *
+     * @async
+     * @returns {Promise<[Uint8Array, Object]>} Received data and sender address
+     * @throws {SocketError} with payload.tag 'invalid-state' if socket has not been bound
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    receive(): Promise<any[]>;
+    /**
+     * Get the current bound 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 the socket hasn't been bound yet
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    getLocalAddress(): any;
+    /**
+     * Get the address the socket is currently connected to.
+     * WIT:
+     * ```
+     * remote-address: func() -> result<ip-socket-address, error-code>
+     * ```
+     *
+     * @returns {Object} The connected peer address
+     * @throws {SocketError} with payload.tag 'invalid-state' if the socket is not connected
+     */
+    getRemoteAddress(): any;
+    /**
+     * Whether this is an IPv4 or IPv6 socket.
+     * WIT:
+     * ```
+     * address-family: func() -> ip-address-family
+     * ```
+     *
+     * @returns {IP_ADDRESS_FAMILY}
+     */
+    getAddressFamily(): any;
+    /**
+     * Get the unicast hop limit (TTL).
+     * WIT:
+     * ```
+     * unicast-hop-limit: func() -> result<u8, error-code>
+     * ```
+     *
+     * @returns {number}
+     */
+    getUnicastHopLimit(): number;
+    /**
+     * Set the unicast hop limit (TTL).
+     * WIT:
+     * ```
+     * set-unicast-hop-limit: func(value: u8) -> result<_, error-code>
+     * ```
+     *
+     * @param {number} value - The hop limit (must be ≥1)
+     * @returns {void}
+     * @throws {SocketError} with payload.tag 'invalid-argument' if value < 1
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    setUnicastHopLimit(value: any): void;
+    /**
+     * Get the receive buffer size.
+     * WIT:
+     * ```
+     * receive-buffer-size: func() -> result<u64, error-code>
+     * ```
+     *
+     * @returns {bigint}
+     * @throws {SocketError} payload.tag maps the system error
+     */
+    getReceiveBufferSize(): any;
+    /**
+     * Set the receive buffer size.
+     * WIT:
+     * ```
+     * set-receive-buffer-size: func(value: u64) -> result<_, error-code>
+     * ```
+     *
+     * @param {bigint} value - The buffer size in bytes (must be >0)
+     * @throws {SocketError} payload.tag maps the system error
+     */
+    setReceiveBufferSize(value: any): void;
+    /**
+     * Get the send buffer size.
+     * WIT:
+     * ```
+     * send-buffer-size: func() -> result<u64, error-code>
+     * ```
+     *
+     * @async
+     * @returns {bigint}
+     * @throws {SocketError} payload.tag maps the system error
+     */
+    getSendBufferSize(): any;
+    /**
+     * Set the send buffer size.
+     * WIT:
+     * ```
+     * set-send-buffer-size: func(value: u64) -> result<_, error-code>
+     * ```
+     *
+     * @param {bigint} value - The buffer size in bytes (must be >0)
+     * @throws {SocketError} with payload.tag 'invalid-argument' if value == 0
+     */
+    setSendBufferSize(value: any): void;
+    /**
+     * Dispose the socket.
+     *
+     * Releases native resources and marks the socket as closed.
+     */
+    [Symbol.dispose](): void;
+}
+export declare const udpCreateSocket: {};

package/dist/nodejs/sockets/udp.js

@@ -0,0 +1,475 @@
+import { ResourceWorker } from "../workers/resource-worker.js";
+import { SocketError } from "./error.js";
+import { isWildcardIpAddress, isUnicastIpAddress, isIpv4MappedAddress, isBindableIpAddress, IP_ADDRESS_FAMILY, } from "./address.js";
+let WORKER = null;
+function worker() {
+    return (WORKER ??= new ResourceWorker(new URL("../workers/udp-worker.js", import.meta.url)));
+}
+let UDP_CREATE_TOKEN = null;
+function token() {
+    return (UDP_CREATE_TOKEN ??= Symbol("UdpCreateToken"));
+}
+const STATE = {
+    UNBOUND: "unbound",
+    BOUND: "bound",
+    CONNECTED: "connected",
+    CLOSED: "closed",
+};
+/**
+ * Create a new UDP socket.
+ * WIT:
+ * ```
+ * createUdpSocket: func(address-family: ip-address-family) -> result<udp-socket, error-code>
+ * ```
+ *
+ * @async
+ * @param {IP_ADDRESS_FAMILY} addressFamily - The IP address family
+ * @returns {Promise<UdpSocket>}
+ * @throws {SocketError} with payload.tag 'invalid-argument' if ~addressFamily~ is not IPv4 or IPv6
+ * @throws {SocketError} for other errors, payload.tag maps the system error
+ */
+export function createUdpSocket(addressFamily) {
+    if (addressFamily !== IP_ADDRESS_FAMILY.IPV4 && addressFamily !== IP_ADDRESS_FAMILY.IPV6) {
+        throw new SocketError("invalid-argument");
+    }
+    try {
+        const { socketId } = worker().runSync({
+            op: "udp-create",
+            family: addressFamily,
+        });
+        return UdpSocket._create(token(), addressFamily, socketId);
+    }
+    catch (e) {
+        throw SocketError.from(e);
+    }
+}
+export class UdpSocket {
+    #socketId = null;
+    #family = null;
+    #state = STATE.UNBOUND;
+    #remote = null;
+    #options = {
+        hopLimit: 1,
+        receiveBufferSize: 65536n,
+        sendBufferSize: 65536n,
+    };
+    /**
+     * WIT static constructor for `wasi:sockets/types.udp-socket`.
+     *
+     * WIT:
+     * ```
+     * create: static func(address-family: ip-address-family) -> result<udp-socket, error-code>
+     * ```
+     *
+     * @static
+     * @param {IP_ADDRESS_FAMILY} addressFamily - The IP address family (IPv4 or IPv6)
+     * @returns {UdpSocket} A new UdpSocket 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) {
+        return createUdpSocket(addressFamily);
+    }
+    /**
+     * Creates a new UDP socket
+     * WIT:
+     * ```
+     * constructor(address-family: ip-address-family)
+     * ```
+     *
+     * @static
+     * @param {IP_ADDRESS_FAMILY} addressFamily - The IP address family (IPv4 or IPv6)
+     * @param {string} socketId - The internal socket identifier
+     * @returns {UdpSocket} A new UdpSocket instance
+     * @private
+     */
+    static _create(t, addressFamily, socketId) {
+        if (t !== token()) {
+            throw new Error("Use createUdpSocket to create a Socket");
+        }
+        if (addressFamily !== IP_ADDRESS_FAMILY.IPV4 && addressFamily !== IP_ADDRESS_FAMILY.IPV6) {
+            throw new SocketError("invalid-argument");
+        }
+        const sock = new UdpSocket();
+        sock.#family = addressFamily;
+        sock.#socketId = socketId;
+        return sock;
+    }
+    /**
+     * Bind the socket to the provided IP address and port.
+     * 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) {
+        if (this.#state !== STATE.UNBOUND) {
+            throw new SocketError("invalid-state");
+        }
+        if (localAddress.tag !== this.#family ||
+            (!isUnicastIpAddress(localAddress) && !isWildcardIpAddress(localAddress)) ||
+            isIpv4MappedAddress(localAddress)) {
+            throw new SocketError("invalid-argument");
+        }
+        if (!isBindableIpAddress(localAddress)) {
+            throw new SocketError("address-not-bindable");
+        }
+        try {
+            worker().runSync({
+                op: "udp-bind",
+                socketId: this.#socketId,
+                localAddress,
+            });
+            this.#state = STATE.BOUND;
+        }
+        catch (e) {
+            throw SocketError.from(e);
+        }
+    }
+    /**
+     * Associate this socket with a specific peer address.
+     * WIT:
+     * ```
+     * connect: func(remote-address: ip-socket-address) -> result<_, error-code>
+     * ```
+     *
+     * @param {Object} remoteAddress - The remote address to connect to
+     * @returns {void}
+     * @throws {SocketError} with payload.tag 'invalid-state' if the socket is already connected
+     * @throws {SocketError} with payload.tag 'invalid-argument' if ~remoteAddress~ is invalid or wildcard
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    connect(remoteAddress) {
+        if (remoteAddress.tag !== this.#family ||
+            remoteAddress.val.port === 0 ||
+            isWildcardIpAddress(remoteAddress) ||
+            !isUnicastIpAddress(remoteAddress) ||
+            isIpv4MappedAddress(remoteAddress)) {
+            throw new SocketError("invalid-argument");
+        }
+        try {
+            worker().runSync({
+                op: "udp-connect",
+                socketId: this.#socketId,
+                remoteAddress,
+            });
+            this.#remote = remoteAddress;
+            this.#state = STATE.CONNECTED;
+        }
+        catch (e) {
+            throw SocketError.from(e);
+        }
+    }
+    /**
+     * Dissociate this socket from its peer address.
+     * WIT:
+     * ```
+     * disconnect: func() -> result<_, error-code>
+     * ```
+     *
+     * @returns {void}
+     * @throws {SocketError} with payload.tag 'invalid-state' if the socket is not connected
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    disconnect() {
+        if (this.#state !== STATE.CONNECTED) {
+            throw new SocketError("invalid-state");
+        }
+        try {
+            worker().runSync({
+                op: "udp-disconnect",
+                socketId: this.#socketId,
+            });
+            this.#remote = null;
+            this.#state = STATE.BOUND;
+        }
+        catch (e) {
+            throw SocketError.from(e);
+        }
+    }
+    /**
+     * Send a message on the socket to a particular peer.
+     * WIT:
+     * ```
+     * send: func(data: list<u8>, remote-address: option<ip-socket-address>) -> result<_, error-code>
+     * ```
+     *
+     * @async
+     * @param {Uint8Array} data - The datagram payload
+     * @param {?Object} remoteAddress Optional peer address if not connected.
+     * @returns {Promise<void>}
+     * @throws {SocketError} with payload.tag 'invalid-state' if socket is not bound
+     * @throws {SocketError} with payload.tag 'invalid-argument' if ~data~ is not a Uint8Array or address invalid
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    async send(data, remoteAddress = null) {
+        if (this.#state === STATE.CLOSED) {
+            throw new SocketError("invalid-state");
+        }
+        if (!(data instanceof Uint8Array)) {
+            throw new SocketError("invalid-argument");
+        }
+        const addr = remoteAddress ?? this.#remote;
+        if (!addr ||
+            addr.val.port === 0 ||
+            addr.tag !== this.#family ||
+            isWildcardIpAddress(addr) ||
+            isIpv4MappedAddress(addr) ||
+            !isUnicastIpAddress(addr)) {
+            throw new SocketError("invalid-argument");
+        }
+        if (this.#state === STATE.CONNECTED &&
+            remoteAddress != null &&
+            (addr.tag !== this.#remote.tag ||
+                addr.val.port !== this.#remote.val.port ||
+                addr.val.address.some((v, i) => v !== this.#remote.val.address[i]))) {
+            throw new SocketError("invalid-argument");
+        }
+        const wasUnbound = this.#state === STATE.UNBOUND;
+        try {
+            await worker().run({
+                op: "udp-send",
+                socketId: this.#socketId,
+                data,
+                remoteAddress: addr,
+            }, [data.buffer]);
+            if (wasUnbound) {
+                this.#state = STATE.BOUND;
+            }
+        }
+        catch (e) {
+            throw SocketError.from(e);
+        }
+    }
+    /**
+     * Receive a message on the socket.
+     * WIT:
+     * ```
+     * receive: func() -> result<tuple<list<u8>, ip-socket-address>, error-code>
+     * ```
+     *
+     * @async
+     * @returns {Promise<[Uint8Array, Object]>} Received data and sender address
+     * @throws {SocketError} with payload.tag 'invalid-state' if socket has not been bound
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    async receive() {
+        if (this.#state === STATE.UNBOUND) {
+            throw new SocketError("invalid-state");
+        }
+        try {
+            const { data, remoteAddress } = await worker().run({
+                op: "udp-receive",
+                socketId: this.#socketId,
+            });
+            return [new Uint8Array(data), remoteAddress];
+        }
+        catch (e) {
+            throw SocketError.from(e);
+        }
+    }
+    /**
+     * Get the current bound 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 the socket hasn't been bound yet
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    getLocalAddress() {
+        if (this.#state === STATE.UNBOUND) {
+            throw new SocketError("invalid-state");
+        }
+        try {
+            return worker().runSync({
+                op: "udp-get-local-address",
+                socketId: this.#socketId,
+            });
+        }
+        catch (e) {
+            throw SocketError.from(e);
+        }
+    }
+    /**
+     * Get the address the socket is currently connected to.
+     * WIT:
+     * ```
+     * remote-address: func() -> result<ip-socket-address, error-code>
+     * ```
+     *
+     * @returns {Object} The connected peer address
+     * @throws {SocketError} with payload.tag 'invalid-state' if the socket is not connected
+     */
+    getRemoteAddress() {
+        if (this.#state !== STATE.CONNECTED) {
+            throw new SocketError("invalid-state");
+        }
+        return this.#remote;
+    }
+    /**
+     * Whether this is an IPv4 or IPv6 socket.
+     * WIT:
+     * ```
+     * address-family: func() -> ip-address-family
+     * ```
+     *
+     * @returns {IP_ADDRESS_FAMILY}
+     */
+    getAddressFamily() {
+        return this.#family;
+    }
+    /**
+     * Get the unicast hop limit (TTL).
+     * WIT:
+     * ```
+     * unicast-hop-limit: func() -> result<u8, error-code>
+     * ```
+     *
+     * @returns {number}
+     */
+    getUnicastHopLimit() {
+        return this.#options.hopLimit;
+    }
+    /**
+     * Set the unicast hop limit (TTL).
+     * WIT:
+     * ```
+     * set-unicast-hop-limit: func(value: u8) -> result<_, error-code>
+     * ```
+     *
+     * @param {number} value - The hop limit (must be ≥1)
+     * @returns {void}
+     * @throws {SocketError} with payload.tag 'invalid-argument' if value < 1
+     * @throws {SocketError} for other errors, payload.tag maps the system error
+     */
+    setUnicastHopLimit(value) {
+        if (value < 1) {
+            throw new SocketError("invalid-argument");
+        }
+        this.#options.hopLimit = value;
+        if (this.#state === STATE.UNBOUND) {
+            return;
+        }
+        try {
+            worker().runSync({
+                op: "udp-set-unicast-hop-limit",
+                socketId: this.#socketId,
+                value,
+            });
+        }
+        catch (e) {
+            throw SocketError.from(e);
+        }
+    }
+    /**
+     * Get the receive buffer size.
+     * WIT:
+     * ```
+     * receive-buffer-size: func() -> result<u64, error-code>
+     * ```
+     *
+     * @returns {bigint}
+     * @throws {SocketError} payload.tag maps the system error
+     */
+    getReceiveBufferSize() {
+        if (this.#options.receiveBufferSize) {
+            return this.#options.receiveBufferSize;
+        }
+        try {
+            const size = worker().runSync({
+                op: "udp-recv-buffer-size",
+                socketId: this.#socketId,
+            });
+            this.#options.receiveBufferSize = size;
+            return size;
+        }
+        catch (e) {
+            throw SocketError.from(e);
+        }
+    }
+    /**
+     * Set the receive buffer size.
+     * WIT:
+     * ```
+     * set-receive-buffer-size: func(value: u64) -> result<_, error-code>
+     * ```
+     *
+     * @param {bigint} value - The buffer size in bytes (must be >0)
+     * @throws {SocketError} payload.tag maps the system error
+     */
+    setReceiveBufferSize(value) {
+        if (value === 0n) {
+            throw new SocketError("invalid-argument");
+        }
+        this.#options.receiveBufferSize = value;
+    }
+    /**
+     * Get the send buffer size.
+     * WIT:
+     * ```
+     * send-buffer-size: func() -> result<u64, error-code>
+     * ```
+     *
+     * @async
+     * @returns {bigint}
+     * @throws {SocketError} payload.tag maps the system error
+     */
+    getSendBufferSize() {
+        if (this.#options.sendBufferSize) {
+            return this.#options.sendBufferSize;
+        }
+        try {
+            const size = worker().runSync({
+                op: "udp-send-buffer-size",
+                socketId: this.#socketId,
+            });
+            this.#options.sendBufferSize = size;
+            return size;
+        }
+        catch (e) {
+            throw SocketError.from(e);
+        }
+    }
+    /**
+     * Set the send buffer size.
+     * WIT:
+     * ```
+     * set-send-buffer-size: func(value: u64) -> result<_, error-code>
+     * ```
+     *
+     * @param {bigint} value - The buffer size in bytes (must be >0)
+     * @throws {SocketError} with payload.tag 'invalid-argument' if value == 0
+     */
+    setSendBufferSize(value) {
+        if (value === 0n) {
+            throw new SocketError("invalid-argument");
+        }
+        this.#options.sendBufferSize = value;
+    }
+    /**
+     * Dispose the socket.
+     *
+     * Releases native resources and marks the socket as closed.
+     */
+    [Symbol.dispose]() {
+        if (this.#socketId) {
+            worker().runSync({
+                op: "udp-dispose",
+                socketId: this.#socketId,
+            });
+        }
+        this.#socketId = null;
+        this.#state = STATE.CLOSED;
+    }
+}
+export const udpCreateSocket = {};

package/dist/nodejs/sockets.d.ts

@@ -0,0 +1,11 @@
+import { TcpSocket } from "./sockets/tcp.js";
+import { UdpSocket } from "./sockets/udp.js";
+export { ipNameLookup } from "./sockets/ip-name-lookup.js";
+export * from "./sockets/tcp.js";
+export * from "./sockets/udp.js";
+export { IP_ADDRESS_FAMILY } from "./sockets/address.js";
+export { makeIpAddress, serializeIpAddress } from "./sockets/address.js";
+export declare const types: {
+    TcpSocket: typeof TcpSocket;
+    UdpSocket: typeof UdpSocket;
+};