@bytecodealliance/jco 1.32.1 → 1.33.0

package/lib/wit/builtin/jco-node-0.1.0/fs.wit

@@ -0,0 +1,208 @@
+package jco:node@0.1.0;
+
+/// Typed, runtime-neutral host boundary for the supported Node filesystem API.
+interface fs {
+  variant path {
+    text(string),
+    bytes(list<u8>),
+    file-url(string),
+  }
+
+  variant path-or-descriptor {
+    path(path),
+    descriptor(u32),
+  }
+
+  variant mode {
+    number(u32),
+    symbolic(string),
+  }
+
+  variant open-mode {
+    number(s32),
+    symbolic(string),
+  }
+
+  variant errno {
+    number(s64),
+    symbolic(string),
+  }
+
+  record error {
+    name: string,
+    message: string,
+    code: option<string>,
+    errno: option<errno>,
+    syscall: option<string>,
+    path: option<string>,
+    dest: option<string>,
+  }
+
+  enum file-type {
+    block,
+    character,
+    directory,
+    fifo,
+    file,
+    socket,
+    symlink,
+    unknown,
+  }
+
+  variant numeric {
+    number(f64),
+    bigint(s64),
+  }
+
+  record stats {
+    dev: numeric,
+    ino: numeric,
+    mode: numeric,
+    nlink: numeric,
+    uid: numeric,
+    gid: numeric,
+    rdev: numeric,
+    size: numeric,
+    blksize: numeric,
+    blocks: numeric,
+    atime-ms: numeric,
+    mtime-ms: numeric,
+    ctime-ms: numeric,
+    birthtime-ms: numeric,
+    atime-ns: option<s64>,
+    mtime-ns: option<s64>,
+    ctime-ns: option<s64>,
+    birthtime-ns: option<s64>,
+    file-type: file-type,
+  }
+
+  record statfs-result {
+    %type: numeric,
+    bsize: numeric,
+    blocks: numeric,
+    bfree: numeric,
+    bavail: numeric,
+    files: numeric,
+    ffree: numeric,
+  }
+
+  record dirent {
+    name: string,
+    parent-path: string,
+    file-type: file-type,
+  }
+
+  variant directory-entry {
+    name(string),
+    dirent(dirent),
+  }
+
+  variant glob-entry {
+    path(string),
+    dirent(dirent),
+  }
+
+  variant glob-exclude {
+    pattern(string),
+    patterns(list<string>),
+  }
+
+  record copy-options {
+    dereference: bool,
+    error-on-exist: bool,
+    force: bool,
+    preserve-timestamps: bool,
+    recursive: bool,
+    verbatim-symlinks: bool,
+  }
+
+  record glob-options {
+    cwd: option<path>,
+    exclude: option<glob-exclude>,
+    with-file-types: bool,
+  }
+
+  record mkdir-options {
+    recursive: bool,
+    mode: option<mode>,
+  }
+
+  record readdir-options {
+    recursive: bool,
+    with-file-types: bool,
+  }
+
+  record remove-options {
+    force: bool,
+    max-retries: u32,
+    recursive: bool,
+    retry-delay: u32,
+  }
+
+  record stat-options {
+    bigint: bool,
+    throw-if-no-entry: bool,
+  }
+
+  record read-file-options {
+    flag: option<string>,
+  }
+
+  record write-file-options {
+    flag: option<string>,
+    mode: option<mode>,
+    flush: bool,
+  }
+
+  record read-result {
+    bytes-read: u32,
+    data: list<u8>,
+  }
+
+  record readv-result {
+    bytes-read: u32,
+    buffers: list<list<u8>>,
+  }
+
+  access: func(path: path, mode: s32) -> result<_, error>;
+  append-file: func(file: path-or-descriptor, data: list<u8>, options: write-file-options) -> result<_, error>;
+  chmod: func(path: path, mode: mode) -> result<_, error>;
+  chown: func(path: path, uid: u32, gid: u32) -> result<_, error>;
+  close: func(descriptor: u32) -> result<_, error>;
+  copy-file: func(source: path, destination: path, mode: s32) -> result<_, error>;
+  cp: func(source: path, destination: path, options: copy-options) -> result<_, error>;
+  exists: func(path: path) -> result<bool, error>;
+  fchmod: func(descriptor: u32, mode: mode) -> result<_, error>;
+  fchown: func(descriptor: u32, uid: u32, gid: u32) -> result<_, error>;
+  fdatasync: func(descriptor: u32) -> result<_, error>;
+  fstat: func(descriptor: u32, options: stat-options) -> result<stats, error>;
+  fsync: func(descriptor: u32) -> result<_, error>;
+  ftruncate: func(descriptor: u32, length: u32) -> result<_, error>;
+  futimes: func(descriptor: u32, atime: f64, mtime: f64) -> result<_, error>;
+  glob: func(patterns: list<string>, options: glob-options) -> result<list<glob-entry>, error>;
+  lchown: func(path: path, uid: u32, gid: u32) -> result<_, error>;
+  link: func(existing-path: path, new-path: path) -> result<_, error>;
+  lstat: func(path: path, options: stat-options) -> result<option<stats>, error>;
+  lutimes: func(path: path, atime: f64, mtime: f64) -> result<_, error>;
+  mkdir: func(path: path, options: mkdir-options) -> result<option<string>, error>;
+  mkdtemp: func(prefix: string) -> result<string, error>;
+  open: func(path: path, %flags: open-mode, mode: mode) -> result<u32, error>;
+  read-file: func(file: path-or-descriptor, options: read-file-options) -> result<list<u8>, error>;
+  readdir: func(path: path, options: readdir-options) -> result<list<directory-entry>, error>;
+  readlink: func(path: path) -> result<string, error>;
+  realpath: func(path: path) -> result<string, error>;
+  rename: func(old-path: path, new-path: path) -> result<_, error>;
+  rm: func(path: path, options: remove-options) -> result<_, error>;
+  rmdir: func(path: path, options: remove-options) -> result<_, error>;
+  stat: func(path: path, options: stat-options) -> result<option<stats>, error>;
+  statfs: func(path: path, bigint: bool) -> result<statfs-result, error>;
+  symlink: func(target: path, path: path, %type: option<string>) -> result<_, error>;
+  truncate: func(path: path, length: u32) -> result<_, error>;
+  unlink: func(path: path) -> result<_, error>;
+  utimes: func(path: path, atime: f64, mtime: f64) -> result<_, error>;
+  write-file: func(file: path-or-descriptor, data: list<u8>, options: write-file-options) -> result<_, error>;
+  read: func(descriptor: u32, length: u32, position: option<u64>) -> result<read-result, error>;
+  write: func(descriptor: u32, data: list<u8>, position: option<u64>) -> result<u32, error>;
+  readv: func(descriptor: u32, lengths: list<u32>, position: option<u64>) -> result<readv-result, error>;
+  writev: func(descriptor: u32, buffers: list<list<u8>>, position: option<u64>) -> result<u32, error>;
+}

package/lib/wit/builtin/jco-node-0.1.0/http.wit

@@ -0,0 +1,144 @@
+package jco:node@0.1.0;
+
+/// Guest-owned callback resources used by the direct Node-compatible HTTP implementation.
+interface http-callbacks {
+  variant errno {
+    number(s64),
+    symbolic(string),
+  }
+
+  record error {
+    name: string,
+    message: string,
+    code: option<string>,
+    errno: option<errno>,
+    syscall: option<string>,
+    hostname: option<string>,
+    address: option<string>,
+    port: option<u16>,
+  }
+
+  record header {
+    name: string,
+    value: list<u8>,
+  }
+
+  record incoming-request {
+    method: string,
+    url: string,
+    http-version: string,
+    headers: list<header>,
+    body: list<u8>,
+    remote-address: option<string>,
+    remote-port: option<u16>,
+  }
+
+  record outgoing-response {
+    status-code: u16,
+    status-message: string,
+    headers: list<header>,
+    body: list<u8>,
+  }
+
+  resource request-listener {
+    handle: func(request: incoming-request) -> result<outgoing-response, error>;
+  }
+
+  /// Redeem a registration once. The host owns the returned listener until the server closes.
+  take-request-listener: func(id: u32) -> option<request-listener>;
+}
+
+/// Typed host boundary for Node-compatible HTTP clients and servers.
+interface http {
+  variant errno {
+    number(s64),
+    symbolic(string),
+  }
+
+  record error {
+    name: string,
+    message: string,
+    code: option<string>,
+    errno: option<errno>,
+    syscall: option<string>,
+    hostname: option<string>,
+    address: option<string>,
+    port: option<u16>,
+  }
+
+  record header {
+    name: string,
+    value: list<u8>,
+  }
+
+  record request-options {
+    method: string,
+    scheme: string,
+    authority: string,
+    path-with-query: string,
+    headers: list<header>,
+    body: list<u8>,
+    connect-timeout-ms: option<u32>,
+    first-byte-timeout-ms: option<u32>,
+    between-bytes-timeout-ms: option<u32>,
+  }
+
+  record response {
+    status-code: u16,
+    status-message: string,
+    http-version: string,
+    headers: list<header>,
+    body: list<u8>,
+  }
+
+  record server-options {
+    request-timeout: option<u32>,
+    headers-timeout: option<u32>,
+    keep-alive-timeout: option<u32>,
+    keep-alive-timeout-buffer: option<u32>,
+    connections-checking-interval: option<u32>,
+    max-header-size: option<u32>,
+    join-duplicate-headers: option<bool>,
+    no-delay: option<bool>,
+    require-host-header: option<bool>,
+    keep-alive: option<bool>,
+    keep-alive-initial-delay: option<u32>,
+    reject-non-standard-body-writes: option<bool>,
+    optimize-empty-requests: option<bool>,
+  }
+
+  record listen-options {
+    port: option<u16>,
+    host: option<string>,
+    backlog: option<u32>,
+    path: option<string>,
+    exclusive: option<bool>,
+    ipv6-only: option<bool>,
+    reuse-port: option<bool>,
+  }
+
+  record tcp-address {
+    address: string,
+    family: string,
+    port: u16,
+  }
+
+  variant server-address {
+    tcp(tcp-address),
+    pipe(string),
+  }
+
+  request: func(options: request-options) -> result<response, error>;
+
+  resource server {
+    constructor(options: server-options, listener: u32);
+    listen: func(options: listen-options) -> result<server-address, error>;
+    close: func() -> result<bool, error>;
+    close-all-connections: func() -> result<_, error>;
+    close-idle-connections: func() -> result<_, error>;
+    get-connections: func() -> result<u64, error>;
+    address: func() -> option<server-address>;
+    ref: func();
+    unref: func();
+  }
+}

package/lib/wit/builtin/jco-node-0.1.0/http2.wit

@@ -0,0 +1,191 @@
+/// Guest-owned callbacks used by the direct Node-compatible HTTP/2 implementation.
+interface http2-callbacks {
+  variant errno {
+    number(s64),
+    symbolic(string),
+  }
+
+  record error {
+    name: string,
+    message: string,
+    code: option<string>,
+    errno: option<errno>,
+    syscall: option<string>,
+    hostname: option<string>,
+    address: option<string>,
+    port: option<u16>,
+  }
+
+  record header {
+    name: string,
+    value: list<u8>,
+  }
+
+  record incoming-stream {
+    session-id: u32,
+    id: u32,
+    headers: list<header>,
+    body: list<u8>,
+    remote-address: option<string>,
+    remote-port: option<u16>,
+  }
+
+  record outgoing-response {
+    headers: list<header>,
+    body: list<u8>,
+  }
+
+  resource stream-listener {
+    handle: func(input: incoming-stream) -> result<outgoing-response, error>;
+  }
+
+  resource server-error-listener {
+    handle: func(reason: error);
+  }
+
+  /// Redeem each registration once; the host owns the resources until the server closes.
+  take-stream-listener: func(id: u32) -> option<stream-listener>;
+  take-server-error-listener: func(id: u32) -> option<server-error-listener>;
+}
+
+/// Typed host boundary for Node-compatible HTTP/2 clients and servers.
+interface http2 {
+  variant errno {
+    number(s64),
+    symbolic(string),
+  }
+
+  record error {
+    name: string,
+    message: string,
+    code: option<string>,
+    errno: option<errno>,
+    syscall: option<string>,
+    hostname: option<string>,
+    address: option<string>,
+    port: option<u16>,
+  }
+
+  record header {
+    name: string,
+    value: list<u8>,
+  }
+
+  record custom-setting {
+    id: u16,
+    value: u32,
+  }
+
+  record http2-settings {
+    header-table-size: option<u32>,
+    enable-push: option<bool>,
+    initial-window-size: option<u32>,
+    max-frame-size: option<u32>,
+    max-concurrent-streams: option<u32>,
+    max-header-list-size: option<u32>,
+    enable-connect-protocol: option<bool>,
+    custom-settings: list<custom-setting>,
+  }
+
+  record client-options {
+    settings: http2-settings,
+    reject-unauthorized: option<bool>,
+    server-name: option<string>,
+    ca: option<list<u8>>,
+  }
+
+  record request-options {
+    end-stream: option<bool>,
+    wait-for-trailers: option<bool>,
+  }
+
+  record response {
+    headers: list<header>,
+    trailers: list<header>,
+    body: list<u8>,
+  }
+
+  record stream-state {
+    state: option<u32>,
+    local-window-size: option<u32>,
+    local-close: option<u32>,
+    remote-close: option<u32>,
+  }
+
+  record ping-response {
+    duration-ms: f64,
+    payload: list<u8>,
+  }
+
+  record session-info {
+    alpn-protocol: option<string>,
+    encrypted: bool,
+    local-settings: http2-settings,
+    remote-settings: http2-settings,
+  }
+
+  record server-options {
+    secure: bool,
+    key: option<list<u8>>,
+    cert: option<list<u8>>,
+    settings: http2-settings,
+    allow-http1: option<bool>,
+    strict-field-whitespace-validation: option<bool>,
+  }
+
+  record listen-options {
+    port: option<u16>,
+    host: option<string>,
+    backlog: option<u32>,
+    path: option<string>,
+    exclusive: option<bool>,
+    ipv6-only: option<bool>,
+    reuse-port: option<bool>,
+  }
+
+  record tcp-address {
+    address: string,
+    family: string,
+    port: u16,
+  }
+
+  variant server-address {
+    tcp(tcp-address),
+    pipe(string),
+  }
+
+  resource client-stream {
+    write: func(chunk: list<u8>) -> result<bool, error>;
+    finish: func() -> result<response, error>;
+    close: func(code: u32) -> result<_, error>;
+    id: func() -> option<u32>;
+    state: func() -> stream-state;
+  }
+
+  resource client-session {
+    constructor(authority: string, options: client-options);
+    ready: func() -> result<session-info, error>;
+    request: func(headers: list<header>, options: request-options) -> result<own<client-stream>, error>;
+    close: func() -> result<_, error>;
+    destroy: func(code: u32) -> result<_, error>;
+    settings: func(settings: http2-settings) -> result<http2-settings, error>;
+    ping: func(payload: list<u8>) -> result<ping-response, error>;
+    goaway: func(code: u32, last-stream-id: option<u32>, opaque-data: list<u8>) -> result<_, error>;
+    ref: func();
+    unref: func();
+  }
+
+  resource server {
+    constructor(
+      options: server-options,
+      listener: u32,
+      error-listener: u32,
+    );
+    listen: func(options: listen-options) -> result<server-address, error>;
+    close: func() -> result<bool, error>;
+    address: func() -> option<server-address>;
+    update-settings: func(settings: http2-settings) -> result<_, error>;
+    ref: func();
+    unref: func();
+  }
+}

package/lib/wit/builtin/jco-node-0.1.0/inspector.wit

@@ -0,0 +1,142 @@
+package jco:node@0.1.0;
+
+/// Host-backed adapter for Node's `inspector` module (and `inspector/promises`).
+///
+/// The inspector is host machinery by definition: a V8 WebSocket server and a Chrome DevTools
+/// Protocol dispatcher wired into the running isolate. WASI expresses none of it, so unlike Jco's
+/// portable shims every observable operation forwards to the host's real `node:inspector` over
+/// this interface. Guest-side code owns Node-faithful argument validation, session state, the
+/// `EventEmitter` surface, and error reconstruction; the host owns the V8 machinery.
+///
+/// Protocol payloads are JSON by definition (CDP), so `session-post`, notifications, and the
+/// broadcast namespaces carry their parameters and results as JSON strings without loss. The
+/// `console` forwarder JSON-encodes its arguments, which is lossy for functions, symbols, and
+/// cycles -- best-effort, and documented as such guest-side.
+///
+/// Callbacks run the other way: the host must call back into the component when a protocol
+/// response or a notification arrives. A component cannot implement a resource declared in an
+/// *imported* interface -- its methods would run host-side -- so the callback resources live in the
+/// guest-*exported* `inspector-callbacks` interface below. This import carries only a `u32`
+/// callback id; the host redeems it for an owned resource handle through the exported `take-*`
+/// functions and invokes the resource method to re-enter the guest. The host must never do so while
+/// a guest->host call is still on the stack (component re-entrance); the Node adapter queues
+/// deliveries and flushes them on a later turn, which makes guest-side callbacks always
+/// asynchronous even where Node fires them synchronously. Node does not promise synchronous
+/// delivery.
+///
+/// The one exception is a `session-post` whose CDP command resolves in-isolate: the host returns
+/// that response directly from the import call, so the promise-based `Session.post` can `await` it
+/// without any callback re-entering a suspended task. The `post-callback` resource remains for
+/// genuinely deferred responses, and notifications arrive between guest tasks.
+///
+/// Session ids are `u32` allocated guest-side (like `cluster`'s worker ids), so `new Session()`
+/// touches no host state. Deny-by-default: declaring the import grants nothing; an application
+/// opts in by mapping the interface to a host adapter at transpile time.
+interface inspector {
+    /// A failure reported by the host, carrying Node's own error code where it has one.
+    record failure {
+        code: string,
+        message: string,
+    }
+
+    /// Why an operation the guest asked for cannot be carried out.
+    variant error {
+        /// No inspector capability was granted to this component.
+        denied(string),
+        /// The host runtime has no usable `node:inspector` (for example, a browser host).
+        unavailable(string),
+        /// No session with this id is connected.
+        no-such-session(u32),
+        /// The host's inspector call failed.
+        failed(failure),
+    }
+
+    /// Which inspector a session attaches to. `main-thread` is `connectToMainThread`, valid only
+    /// from a worker.
+    enum connect-kind {
+        local,
+        main-thread,
+    }
+
+    /// Which experimental broadcast namespace an `emit` targets.
+    enum broadcast-target {
+        network,
+        dom-storage,
+    }
+
+    /// Activate the inspector, optionally waiting for a client to attach before returning.
+    open: func(port: option<u32>, host: option<string>, wait: bool) -> result<_, error>;
+
+    /// Deactivate the inspector.
+    close: func() -> result<_, error>;
+
+    /// The active inspector WebSocket URL, or none when it is not active.
+    url: func() -> result<option<string>, error>;
+
+    /// Block until a client has connected and is ready to step. Requires an active inspector.
+    wait-for-debugger: func() -> result<_, error>;
+
+    /// Emit through the inspector's own `console`, optionally into a named context. `args-json` is
+    /// the JSON-encoded argument list.
+    console-call: func(context: option<string>, method: string, args-json: string) -> result<_, error>;
+
+    /// Connect a session. `listener` is the id of the guest-exported `notification-listener` the
+    /// host redeems once and keeps for the session's lifetime, calling it per notification.
+    session-connect: func(session: u32, kind: connect-kind, listener: u32) -> result<_, error>;
+
+    /// The outcome of a CDP command the host resolved synchronously.
+    ///
+    /// In-isolate protocol methods (`Runtime.evaluate`, `Debugger.*`, ...) resolve during the post
+    /// call, so their response is returned directly. This matters beyond efficiency: a guest that
+    /// `await`s the result would otherwise need the host to call back in while the guest is
+    /// suspended, which the component model forbids.
+    variant command-response {
+        /// Success: the JSON-encoded CDP result, absent when the result is empty.
+        ok(option<string>),
+        /// Failure: the protocol error, carrying Node's `ERR_INSPECTOR_COMMAND` code.
+        failed(failure),
+    }
+
+    /// Post a CDP command on a session.
+    ///
+    /// Returns `some(response)` when the command resolved synchronously (the common case), `none`
+    /// when the response is deferred. For a deferred response, if `callback` is present it is the id
+    /// of a guest-exported `post-callback` the host redeems and calls once the response arrives. A
+    /// guest must not `await` a deferred response -- delivery would re-enter a suspended task -- so
+    /// the promise-based `Session.post` only awaits synchronous responses.
+    session-post: func(session: u32, method: string, params-json: option<string>, callback: option<u32>) -> result<option<command-response>, error>;
+
+    /// Disconnect a session, releasing its notification listener.
+    session-disconnect: func(session: u32) -> result<_, error>;
+
+    /// Feed one event to an experimental broadcast namespace (`Network`, `DOMStorage`). `params-json`
+    /// is the JSON-encoded parameter object.
+    emit: func(target: broadcast-target, event: string, params-json: string) -> result<_, error>;
+
+    /// Register a network resource for the inspector to serve (`NetworkResources.put`).
+    put-network-resource: func(url: string, data: string) -> result<_, error>;
+}
+
+/// Callback channel the host uses to re-enter the component. Guest-*exported*: the component owns
+/// the resource implementations, and the host redeems ids for handles through the `take-*`
+/// functions. See the `inspector` interface docs for why the callbacks cannot live on the import.
+interface inspector-callbacks {
+    /// A one-shot response to a `session-post`, matching Node's `(err, result)` callback.
+    resource post-callback {
+        /// Deliver the response. `error-json` is a JSON `{ code, message }` when the command
+        /// failed, otherwise absent; `result-json` is the JSON-encoded CDP result on success.
+        done: func(error-json: option<string>, result-json: option<string>);
+    }
+
+    /// The long-lived channel for one connected session's notifications.
+    resource notification-listener {
+        /// Deliver one CDP notification. `params-json` is the JSON-encoded parameter object.
+        notify: func(method: string, params-json: string);
+    }
+
+    /// Redeem a `session-post` callback id for its resource. Absent if the id is unknown.
+    take-post-callback: func(id: u32) -> option<post-callback>;
+
+    /// Redeem a session's notification-listener id for its resource. Absent if the id is unknown.
+    take-notification-listener: func(id: u32) -> option<notification-listener>;
+}