@bytecodealliance/preview3-shim 0.1.0-rc.0

package/lib/nodejs/workers/tcp-worker.js

@@ -0,0 +1,283 @@
+import { Socket, Server } from "node:net";
+import { Readable, Writable } from "stream";
+import { pipeline } from "stream/promises";
+import { once } from "node:events";
+
+import { Router } from "../workers/resource-worker.js";
+import { serializeIpAddress, makeIpAddress, ipAddressConflict } from "../sockets/address.js";
+import { SocketError } from "../sockets/error.js";
+
+import process from "node:process";
+const { TCP, constants: TCPConstants } = process.binding("tcp_wrap");
+
+// Socket instances stored by ID
+const sockets = new Map();
+// Unique IDs for sockets
+let NEXT_SOCKET_ID = 0n;
+
+// Handle worker messages
+Router()
+  .beforeAll((msg) => {
+    if (msg.op !== "tcp-create" && !sockets.has(msg.socketId)) {
+      throw new Error("Invalid socket ID");
+    }
+  })
+  .op("tcp-create", handleTcpCreate)
+  .op("tcp-bind", handleTcpBind)
+  .op("tcp-connect", handleTcpConnect)
+  .op("tcp-listen", handleTcpListen)
+  .op("tcp-send", handleTcpSend)
+  .op("tcp-receive", handleTcpReceive)
+  .op("tcp-get-local-address", handleGetLocalAddress)
+  .op("tcp-get-remote-address", handleGetRemoteAddress)
+  .op("tcp-set-listen-backlog-size", handleTcpSetBacklogSize)
+  .op("tcp-set-keep-alive", handleTcpSetKeepAlive)
+  .op("tcp-recv-buffer-size", handleRecvBufferSize)
+  .op("tcp-send-buffer-size", handleSendBufferSize)
+  .op("tcp-dispose", handleTcpDispose);
+
+// Create a new TCP socket
+function handleTcpCreate({ family }) {
+  const socketId = NEXT_SOCKET_ID++;
+  const handle = new TCP(TCPConstants.SOCKET);
+
+  sockets.set(socketId, {
+    handle,
+    family,
+    tcp: null,
+    server: null,
+    backlog: 128,
+    localAddress: null,
+  });
+
+  return { socketId };
+}
+
+// Bind a socket to local address
+async function handleTcpBind({ socketId, localAddress }) {
+  const socket = sockets.get(socketId);
+  const address = serializeIpAddress(localAddress);
+  const port = localAddress.val.port;
+
+  const { handle, family } = socket;
+
+  const hasConflict = [...sockets].some(
+    ([id, { localAddress: boundAddress }]) =>
+      id !== socketId && boundAddress && ipAddressConflict(boundAddress, localAddress),
+  );
+
+  if (hasConflict) {
+    const err = new Error("EADDRINUSE");
+    err.code = "EADDRINUSE";
+    throw err;
+  }
+
+  await new Promise((resolve, reject) => {
+    let code;
+    if (family === "ipv6") {
+      code = handle.bind6(address, port, TCPConstants.UV_TCP_IPV6ONLY);
+    } else {
+      code = handle.bind(address, port);
+    }
+
+    if (code !== 0) {
+      reject(SocketError.from(-code));
+    } else {
+      resolve();
+    }
+  });
+
+  const out = {};
+  const code = handle.getsockname(out);
+  if (code !== 0) {
+    throw SocketError.from(-code);
+  }
+  socket.localAddress = makeIpAddress(out.family.toLowerCase(), out.address, out.port);
+}
+
+// Connect a socket to remote address
+async function handleTcpConnect({ socketId, remoteAddress }) {
+  const socket = sockets.get(socketId);
+  const host = serializeIpAddress(remoteAddress);
+  const port = remoteAddress.val.port;
+
+  const tcp = (socket.tcp = new Socket({
+    handle: socket.handle,
+    pauseOnCreate: true,
+    allowHalfOpen: true,
+  }));
+
+  const onConnect = once(tcp, "connect");
+  const onError = once(tcp, "error").then(([err]) => {
+    throw err;
+  });
+
+  // TODO(tandr): Add lookup
+  tcp.connect({ port, host });
+
+  await Promise.race([onConnect, onError]);
+}
+
+async function handleTcpListen({ socketId, stream }) {
+  const writer = stream.getWriter();
+  const socket = sockets.get(socketId);
+  const { handle, backlog, family } = socket;
+
+  const server = new Server({
+    pauseOnConnect: true,
+    allowHalfOpen: true,
+  });
+
+  const onListening = once(server, "listening");
+  const onError = once(server, "error").then(([err]) => {
+    throw err;
+  });
+
+  server.listen(handle, backlog);
+
+  await Promise.race([onListening, onError]);
+
+  const addr = server.address();
+  if (addr && typeof addr === "object") {
+    socket.localAddress = makeIpAddress(family, addr.address, addr.port);
+  }
+
+  server.on("connection", (conn) => {
+    const id = NEXT_SOCKET_ID++;
+    sockets.set(id, {
+      handle: conn._handle,
+      family,
+      backlog,
+      tcp: conn,
+      server: null,
+      localAddress: makeIpAddress(family, conn.localAddress, conn.localPort),
+    });
+    writer.write({ family, socketId: id });
+  });
+
+  socket.server = server;
+  server.on("error", (err) => stream.abort(err));
+  server.on("close", () => writer.close());
+}
+
+async function handleTcpSend({ socketId, stream }) {
+  const socket = sockets.get(socketId);
+  const { tcp } = socket;
+  const readable = Readable.fromWeb(stream);
+
+  // TODO(tandr): Should we handle FIN packet?
+  await pipeline(readable, tcp);
+}
+
+async function handleTcpReceive({ socketId, stream }) {
+  const socket = sockets.get(socketId);
+  const { tcp } = socket;
+
+  const writable = Writable.fromWeb(stream);
+  await pipeline(tcp, writable);
+}
+
+async function handleGetLocalAddress({ socketId }) {
+  const socket = sockets.get(socketId);
+  const out = {};
+
+  const code = socket.handle.getsockname(out);
+  if (code !== 0) {
+    throw new SocketError.from(-code);
+  }
+
+  return makeIpAddress(out.family.toLowerCase(), out.address, out.port);
+}
+
+async function handleGetRemoteAddress({ socketId }) {
+  const socket = sockets.get(socketId);
+  const out = {};
+
+  const code = socket.handle.getpeername(out);
+  if (code !== 0) {
+    throw new SocketError.from(-code);
+  }
+
+  return makeIpAddress(out.family.toLowerCase(), out.address, out.port);
+}
+
+function handleTcpSetBacklogSize({ socketId, value }) {
+  const socket = sockets.get(socketId);
+  socket.backlog = Number(value);
+}
+
+async function handleTcpSetKeepAlive({ socketId, keepAliveEnabled, keepAliveIdleTime }) {
+  const socket = sockets.get(socketId);
+  const time = Number(keepAliveIdleTime / 1_000_000_000n);
+
+  const code = socket.handle.setKeepAlive(keepAliveEnabled, time);
+  if (code !== 0) {
+    throw mapErrorCode(-code);
+  }
+}
+
+async function handleRecvBufferSize({ socketId }) {
+  const socket = sockets.get(socketId);
+
+  if (socket.tcp) {
+    return BigInt(socket.tcp.getRecvBufferSize());
+  } else {
+    return await getDefaultReceiveBufferSize();
+  }
+}
+
+async function handleSendBufferSize({ socketId }) {
+  const socket = sockets.get(socketId);
+  if (socket.tcp) {
+    return BigInt(socket.tcp.getSendBufferSize());
+  } else {
+    return await getDefaultSendBufferSize();
+  }
+}
+
+function handleTcpDispose({ socketId }) {
+  const socket = sockets.get(socketId);
+  if (!socket) {
+    return;
+  }
+
+  if (socket.server) {
+    socket.server.close();
+  }
+
+  if (socket.tcp) {
+    socket.tcp.destroy();
+  }
+  if (socket.handle) {
+    socket.handle.close();
+  }
+
+  sockets.delete(socketId);
+}
+
+let _recvBufferSize, _sendBufferSize;
+async function getDefaultBufferSizes() {
+  var s = new Socket();
+  s.bind(0);
+  await new Promise((resolve, reject) => {
+    s.once("error", reject);
+    s.once("listening", resolve);
+  });
+  _recvBufferSize = BigInt(s.getRecvBufferSize());
+  _sendBufferSize = BigInt(s.getSendBufferSize());
+  s.close();
+}
+
+export async function getDefaultSendBufferSize() {
+  if (!_sendBufferSize) {
+    await getDefaultBufferSizes();
+  }
+  return _sendBufferSize;
+}
+
+export async function getDefaultReceiveBufferSize() {
+  if (!_recvBufferSize) {
+    await getDefaultBufferSizes();
+  }
+  return _recvBufferSize;
+}

package/lib/nodejs/workers/udp-worker.js

@@ -0,0 +1,194 @@
+import { once } from "node:events";
+
+import { Router } from "../workers/resource-worker.js";
+import {
+  serializeIpAddress,
+  makeIpAddress,
+  ipAddressConflict,
+  isLoopbackIpAddress,
+} from "../sockets/address.js";
+
+import dgram from "node:dgram";
+
+const sockets = new Map();
+// Unique IDs for sockets
+let NEXT_SOCKET_ID = 0n;
+
+export function noLookup(ip, _opts, cb) {
+  cb(null, ip);
+}
+
+Router()
+  .beforeAll((msg) => {
+    if (msg.op !== "udp-create" && !sockets.has(msg.socketId)) {
+      throw new Error("Invalid socket ID");
+    }
+  })
+  .op("udp-create", handleCreate)
+  .op("udp-bind", handleBind)
+  .op("udp-connect", handleConnect)
+  .op("udp-disconnect", handleDisconnect)
+  .op("udp-send", handleSend)
+  .op("udp-receive", handleReceive)
+  .op("udp-get-local-address", handleGetLocal)
+  .op("udp-set-unicast-hop-limit", handleSetHop)
+  .op("udp-recv-buffer-size", handleRecvBuffer)
+  .op("udp-send-buffer-size", handleSendBuffer)
+  .op("udp-dispose", handleDispose);
+
+function handleCreate({ family }) {
+  const socketId = NEXT_SOCKET_ID++;
+  const socket = {
+    family,
+    connected: null,
+    localAddress: null,
+    receiveQueue: [],
+  };
+  socket.udp = createSocket(socket);
+  sockets.set(socketId, socket);
+
+  return { socketId };
+}
+
+function createSocket(socket) {
+  const type = socket.family === "ipv6" ? "udp6" : "udp4";
+  const ipv6Only = socket.family === "ipv6";
+  const udp = dgram.createSocket({
+    type,
+    ipv6Only,
+    reuseAddr: false,
+    lookup: noLookup,
+  });
+
+  udp.on("message", (msg, rinfo) => socket.receiveQueue.push({ msg, rinfo }));
+  udp.on("error", () => {});
+  return udp;
+}
+
+async function handleBind({ socketId, localAddress }) {
+  const socket = sockets.get(socketId);
+  const hasConflict = [...sockets].some(
+    ([id, { localAddress: boundAddress }]) =>
+      id !== socketId && boundAddress && ipAddressConflict(boundAddress, localAddress),
+  );
+
+  if (hasConflict) {
+    const err = new Error("EADDRINUSE");
+    err.code = "EADDRINUSE";
+    throw err;
+  }
+
+  const addr = serializeIpAddress(localAddress);
+  const port = localAddress.val.port;
+
+  const onListening = once(socket.udp, "listening");
+  const onError = once(socket.udp, "error").then(([err]) => {
+    throw err;
+  });
+
+  socket.udp.bind(port, addr);
+
+  await Promise.race([onListening, onError]);
+  const boundAddr = socket.udp.address();
+  socket.localAddress = makeIpAddress(socket.family, boundAddr.address, boundAddr.port);
+}
+
+async function handleConnect({ socketId, remoteAddress }) {
+  const socket = sockets.get(socketId);
+  const preserveLocalAddress =
+    socket.connected &&
+    socket.localAddress &&
+    isLoopbackIpAddress(socket.connected) &&
+    isLoopbackIpAddress(remoteAddress);
+
+  if (socket.connected) {
+    const localAddress = preserveLocalAddress ? socket.localAddress : null;
+    await new Promise((resolve) => socket.udp.close(resolve));
+    socket.udp = createSocket(socket);
+    if (localAddress) {
+      await handleBind({ socketId, localAddress });
+    } else {
+      socket.localAddress = null;
+    }
+  }
+
+  const addr = serializeIpAddress(remoteAddress);
+  const port = remoteAddress.val.port;
+
+  await new Promise((resolve, reject) => {
+    socket.udp.connect(port, addr, (err) => (err ? reject(err) : resolve()));
+  });
+  const boundAddr = socket.udp.address();
+  socket.localAddress = makeIpAddress(socket.family, boundAddr.address, boundAddr.port);
+  socket.connected = remoteAddress;
+}
+
+function handleDisconnect({ socketId }) {
+  const socket = sockets.get(socketId);
+  socket.udp.disconnect();
+  socket.connected = null;
+}
+
+async function handleSend({ socketId, data, remoteAddress }) {
+  const socket = sockets.get(socketId);
+  const isConnected = socket.connected != null;
+
+  await new Promise((resolve, reject) => {
+    if (isConnected) {
+      socket.udp.send(data, (err) => (err ? reject(err) : resolve()));
+    } else {
+      const addr = serializeIpAddress(remoteAddress);
+      const port = remoteAddress.val.port;
+
+      socket.udp.send(data, port, addr, (err) => (err ? reject(err) : resolve()));
+    }
+  });
+
+  const boundAddr = socket.udp.address();
+  socket.localAddress = makeIpAddress(socket.family, boundAddr.address, boundAddr.port);
+}
+
+async function handleReceive({ socketId }) {
+  const socket = sockets.get(socketId);
+  if (socket.receiveQueue.length === 0) {
+    await Promise.race([
+      once(socket.udp, "message"),
+      once(socket.udp, "error").then(([err]) => {
+        throw err;
+      }),
+    ]);
+  }
+
+  const { msg, rinfo } = socket.receiveQueue.shift();
+  return {
+    data: msg,
+    remoteAddress: makeIpAddress(socket.family, rinfo.address, rinfo.port),
+  };
+}
+
+function handleGetLocal({ socketId }) {
+  const socket = sockets.get(socketId);
+  const addr = socket.udp.address();
+  return makeIpAddress(socket.family, addr.address, addr.port);
+}
+
+function handleSetHop({ socketId, value }) {
+  const socket = sockets.get(socketId);
+  socket.udp.setTTL(value);
+}
+
+function handleRecvBuffer({ socketId }) {
+  const socket = sockets.get(socketId);
+  return BigInt(socket.udp.getRecvBufferSize());
+}
+
+function handleSendBuffer({ socketId }) {
+  const socket = sockets.get(socketId);
+  return BigInt(socket.udp.getSendBufferSize());
+}
+
+function handleDispose({ socketId }) {
+  const socket = sockets.get(socketId);
+  socket.udp.close();
+  sockets.delete(socketId);
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@bytecodealliance/preview3-shim",
+  "version": "0.1.0-rc.0",
+  "description": "WASI Preview3 shim for JS environments",
+  "homepage": "https://github.com/bytecodealliance/jco/blob/main/packages/preview3-shim/#readme",
+  "bugs": {
+    "url": "https://github.com/bytecodealliance/jco/issues"
+  },
+  "license": "(Apache-2.0 WITH LLVM-exception)",
+  "author": "Tomasz Andrzejak",
+  "contributors": [
+    {
+      "name": "Tomasz Andrzejak"
+    },
+    {
+      "name": "Victor Adossi",
+      "email": "vadossi@cosmonic.com"
+    }
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bytecodealliance/jco.git"
+  },
+  "files": [
+    "types",
+    "lib"
+  ],
+  "type": "module",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "node": "./lib/nodejs/index.js"
+    },
+    "./*": {
+      "types": "./types/*.d.ts",
+      "node": "./lib/nodejs/*.js"
+    }
+  },
+  "dependencies": {
+    "@bytecodealliance/preview2-shim": "^0.17.3"
+  },
+  "devDependencies": {
+    "globals": "^16.3.0",
+    "vite": "^7.1.5",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "compile:check": "tsc --noEmit types/index.d.ts",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "test": "vitest --run",
+    "bench": "vitest bench --run"
+  }
+}

package/types/cli.d.ts

@@ -0,0 +1,12 @@
+export type * as environment from "./interfaces/wasi-cli-environment.d.ts";
+export type * as exit from "./interfaces/wasi-cli-exit.d.ts";
+export type * as run from "./interfaces/wasi-cli-run.d.ts";
+export type * as stderr from "./interfaces/wasi-cli-stderr.d.ts";
+export type * as stdin from "./interfaces/wasi-cli-stdin.d.ts";
+export type * as stdout from "./interfaces/wasi-cli-stdout.d.ts";
+export type * as terminalInput from "./interfaces/wasi-cli-terminal-input.d.ts";
+export type * as terminalOutput from "./interfaces/wasi-cli-terminal-output.d.ts";
+export type * as terminalStderr from "./interfaces/wasi-cli-terminal-stderr.d.ts";
+export type * as terminalStdin from "./interfaces/wasi-cli-terminal-stdin.d.ts";
+export type * as terminalStdout from "./interfaces/wasi-cli-terminal-stdout.d.ts";
+export type * as types from "./interfaces/wasi-cli-types.d.ts";

package/types/clocks.d.ts

@@ -0,0 +1,2 @@
+export type * as monotonicClock from "./interfaces/wasi-clocks-monotonic-clock.d.ts";
+export type * as systemClock from "./interfaces/wasi-clocks-system-clock.d.ts";

package/types/filesystem.d.ts

@@ -0,0 +1,2 @@
+export * as preopens from "./interfaces/wasi-filesystem-preopens";
+export * as types from "./interfaces/wasi-filesystem-types";

package/types/http.d.ts

@@ -0,0 +1,4 @@
+export * as client from "./interfaces/wasi-http-client";
+export * as handler from "./interfaces/wasi-http-handler";
+export * as types from "./interfaces/wasi-http-types";
+export function _setHandler(nextHandler: typeof handler | null): typeof handler | null;

package/types/index.d.ts

@@ -0,0 +1,6 @@
+export type * as cli from "./cli.d.ts";
+export type * as clocks from "./clocks.d.ts";
+export type * as filesystem from "./filesystem.d.ts";
+export type * as http from "./http.d.ts";
+export type * as random from "./random.d.ts";
+export type * as sockets from "./sockets.d.ts";

package/types/interfaces/wasi-cli-environment.d.ts

@@ -0,0 +1,21 @@
+/** @module Interface wasi:cli/environment@0.3.0-rc-2026-03-15 **/
+/**
+ * Get the POSIX-style environment variables.
+ *
+ * Each environment variable is provided as a pair of string variable names
+ * and string value.
+ *
+ * Morally, these are a value import, but until value imports are available
+ * in the component model, this import function should return the same
+ * values each time it is called.
+ */
+export function getEnvironment(): Array<[string, string]>;
+/**
+ * Get the POSIX-style arguments to the program.
+ */
+export function getArguments(): Array<string>;
+/**
+ * Return a path that programs should use as their initial current working
+ * directory, interpreting `.` as shorthand for this.
+ */
+export function getInitialCwd(): string | undefined;

package/types/interfaces/wasi-cli-exit.d.ts

@@ -0,0 +1,6 @@
+/** @module Interface wasi:cli/exit@0.3.0-rc-2026-03-15 **/
+/**
+ * Exit the current instance and any linked instances.
+ */
+export function exit(status: Result<void, void>): void;
+export type Result<T, E> = { tag: 'ok', val: T } | { tag: 'err', val: E };

package/types/interfaces/wasi-cli-run.d.ts

@@ -0,0 +1,5 @@
+/** @module Interface wasi:cli/run@0.3.0-rc-2026-03-15 **/
+/**
+ * Run the program.
+ */
+export function run(): Promise<void>;

package/types/interfaces/wasi-cli-stderr.d.ts

@@ -0,0 +1,14 @@
+/** @module Interface wasi:cli/stderr@0.3.0-rc-2026-03-15 **/
+/**
+ * Write the given stream to stderr.
+ *
+ * If the stream's writable end is dropped this function will either return
+ * success once the entire contents of the stream have been written or an
+ * error-code representing a failure.
+ *
+ * Otherwise if there is an error the readable end of the stream will be
+ * dropped and this function will return an error-code.
+ */
+export function writeViaStream(data: ReadableStream<number>): Promise<Result<void, ErrorCode>>;
+export type ErrorCode = import('./wasi-cli-types.js').ErrorCode;
+export type Result<T, E> = { tag: 'ok', val: T } | { tag: 'err', val: E };

package/types/interfaces/wasi-cli-stdin.d.ts

@@ -0,0 +1,19 @@
+/** @module Interface wasi:cli/stdin@0.3.0-rc-2026-03-15 **/
+/**
+ * Return a stream for reading from stdin.
+ *
+ * This function returns a stream which provides data read from stdin,
+ * and a future to signal read results.
+ *
+ * If the stream's readable end is dropped the future will resolve to success.
+ *
+ * If the stream's writable end is dropped the future will either resolve to
+ * success if stdin was closed by the writer or to an error-code if reading
+ * failed for some other reason.
+ *
+ * Multiple streams may be active at the same time. The behavior of concurrent
+ * reads is implementation-specific.
+ */
+export function readViaStream(): [ReadableStream<number>, Promise<Result<void, ErrorCode>>];
+export type ErrorCode = import('./wasi-cli-types.js').ErrorCode;
+export type Result<T, E> = { tag: 'ok', val: T } | { tag: 'err', val: E };

package/types/interfaces/wasi-cli-stdout.d.ts

@@ -0,0 +1,14 @@
+/** @module Interface wasi:cli/stdout@0.3.0-rc-2026-03-15 **/
+/**
+ * Write the given stream to stdout.
+ *
+ * If the stream's writable end is dropped this function will either return
+ * success once the entire contents of the stream have been written or an
+ * error-code representing a failure.
+ *
+ * Otherwise if there is an error the readable end of the stream will be
+ * dropped and this function will return an error-code.
+ */
+export function writeViaStream(data: ReadableStream<number>): Promise<Result<void, ErrorCode>>;
+export type ErrorCode = import('./wasi-cli-types.js').ErrorCode;
+export type Result<T, E> = { tag: 'ok', val: T } | { tag: 'err', val: E };

package/types/interfaces/wasi-cli-terminal-input.d.ts

@@ -0,0 +1,8 @@
+/** @module Interface wasi:cli/terminal-input@0.3.0-rc-2026-03-15 **/
+
+export class TerminalInput {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+}

package/types/interfaces/wasi-cli-terminal-output.d.ts

@@ -0,0 +1,8 @@
+/** @module Interface wasi:cli/terminal-output@0.3.0-rc-2026-03-15 **/
+
+export class TerminalOutput {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+}

package/types/interfaces/wasi-cli-terminal-stderr.d.ts

@@ -0,0 +1,7 @@
+/** @module Interface wasi:cli/terminal-stderr@0.3.0-rc-2026-03-15 **/
+/**
+ * If stderr is connected to a terminal, return a `terminal-output` handle
+ * allowing further interaction with it.
+ */
+export function getTerminalStderr(): TerminalOutput | undefined;
+export type TerminalOutput = import('./wasi-cli-terminal-output.js').TerminalOutput;