@bytecodealliance/preview3-shim 0.1.0-rc.0

package/lib/nodejs/sockets/udp.js

@@ -0,0 +1,516 @@
+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: 65_536n,
+    sendBufferSize: 65_536n,
+  };
+
+  /**
+   * 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/lib/nodejs/sockets.js

@@ -0,0 +1,14 @@
+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 const types = {
+  TcpSocket,
+  UdpSocket,
+};