@bytecodealliance/jco 1.32.1 → 1.34.0

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

@@ -0,0 +1,190 @@
+/// 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>,
+    trailers: 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,
+    /// One-use configuration issued by the shared jco:node/tls provider.
+    tls-context: option<u32>,
+  }
+
+  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,
+    tls-context: option<u32>,
+    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>;
+}

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

@@ -0,0 +1,120 @@
+package jco:node@0.1.0;
+
+/// Typed, runtime-neutral host boundary for Node-compatible OS information.
+interface os {
+  variant errno {
+    number(s64),
+    symbolic(string),
+  }
+
+  record error-info {
+    errno: option<errno>,
+    code: option<string>,
+    message: option<string>,
+    syscall: option<string>,
+  }
+
+  record error {
+    name: string,
+    message: string,
+    code: option<string>,
+    errno: option<errno>,
+    syscall: option<string>,
+    info: option<error-info>,
+  }
+
+  record constant-entry {
+    name: string,
+    value: s64,
+  }
+
+  record os-constants {
+    uv-udp-reuseaddr: s32,
+    dlopen: list<constant-entry>,
+    errno: list<constant-entry>,
+    signals: list<constant-entry>,
+    priority: list<constant-entry>,
+  }
+
+  record static-properties {
+    eol: string,
+    dev-null: string,
+    constants: os-constants,
+  }
+
+  enum byte-order {
+    be,
+    le,
+  }
+
+  record cpu-times {
+    user: u64,
+    nice: u64,
+    sys: u64,
+    idle: u64,
+    irq: u64,
+  }
+
+  record cpu-info {
+    model: string,
+    speed: u32,
+    times: cpu-times,
+  }
+
+  record load-average {
+    one: f64,
+    five: f64,
+    fifteen: f64,
+  }
+
+  enum network-family {
+    ipv4,
+    ipv6,
+  }
+
+  record network-interface {
+    name: string,
+    address: string,
+    netmask: string,
+    family: network-family,
+    mac: string,
+    internal: bool,
+    scopeid: option<u32>,
+    cidr: option<string>,
+  }
+
+  variant user-info-value {
+    text(string),
+    bytes(list<u8>),
+  }
+
+  record user-info-record {
+    username: user-info-value,
+    uid: s64,
+    gid: s64,
+    shell: option<user-info-value>,
+    homedir: user-info-value,
+  }
+
+  get-static-properties: func() -> result<static-properties, error>;
+  arch: func() -> result<string, error>;
+  available-parallelism: func() -> result<u32, error>;
+  cpus: func() -> result<list<cpu-info>, error>;
+  endianness: func() -> result<byte-order, error>;
+  freemem: func() -> result<u64, error>;
+  get-priority: func(pid: s32) -> result<s32, error>;
+  homedir: func() -> result<string, error>;
+  hostname: func() -> result<string, error>;
+  loadavg: func() -> result<load-average, error>;
+  machine: func() -> result<string, error>;
+  network-interfaces: func() -> result<list<network-interface>, error>;
+  platform: func() -> result<string, error>;
+  release: func() -> result<string, error>;
+  set-priority: func(pid: s32, priority: s32) -> result<_, error>;
+  tmpdir: func() -> result<string, error>;
+  totalmem: func() -> result<u64, error>;
+  %type: func() -> result<string, error>;
+  uptime: func() -> result<f64, error>;
+  user-info: func(encoding: option<string>) -> result<user-info-record, error>;
+  version: func() -> result<string, error>;
+}

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

@@ -0,0 +1,245 @@
+package jco:node@0.1.0;
+
+/// Explicit access to the embedding process. No capability is granted by default.
+/// The Node provider affects the embedding Node process, not a virtual WASI process.
+interface process {
+  variant errno {
+    number(s64),
+    symbolic(string)
+  }
+
+  record error {
+    name: string,
+    message: string,
+    code: option<string>,
+    errno: option<errno>,
+    syscall: option<string>,
+    path: option<string>
+  }
+
+  record process-metadata {
+    arch: string,
+    platform: string,
+    pid: u32,
+    ppid: u32,
+    argv: list<string>,
+    argv0: string,
+    exec-argv: list<string>,
+    exec-path: string,
+    version: string,
+    versions: list<tuple<string, string>>,
+    release-json: string,
+    config-json: string,
+    features-json: string,
+    has-permission: bool,
+  }
+
+  enum flag {
+    no-deprecation,
+    throw-deprecation,
+    trace-deprecation,
+    trace-process-warnings
+  }
+
+  variant exit-code {
+    number(f64),
+    text(string)
+  }
+
+  record state {
+    title: string,
+    debug-port: f64,
+    exit-code: option<exit-code>,
+    no-deprecation: option<bool>,
+    throw-deprecation: option<bool>,
+    trace-deprecation: option<bool>,
+    trace-process-warnings: option<bool>,
+    source-maps-enabled: bool,
+    connected: option<bool>,
+  }
+
+  enum identity {
+    uid,
+    euid,
+    gid,
+    egid
+  }
+
+  variant id {
+    number(u32),
+    name(string)
+  }
+
+  variant signal {
+    number(s32),
+    name(string)
+  }
+
+  variant mask {
+    number(u32),
+    text(string)
+  }
+
+  variant path {
+    text(string),
+    url(string),
+    bytes(list<u8>)
+  }
+
+  record warning {
+    name: string,
+    message: string,
+    stack: option<string>,
+    code: option<string>,
+    detail: option<string>
+  }
+
+  record report-options {
+    compact: bool,
+    directory: string,
+    filename: string,
+    signal: string,
+    report-on-fatal-error: bool,
+    report-on-signal: bool,
+    report-on-uncaught-exception: bool,
+    exclude-env: bool,
+    exclude-network: bool,
+  }
+
+  enum report-option {
+    compact,
+    directory,
+    filename,
+    signal,
+    report-on-fatal-error,
+    report-on-signal,
+    report-on-uncaught-exception,
+    exclude-env,
+    exclude-network
+  }
+
+  variant report-value {
+    boolean(bool),
+    text(string)
+  }
+
+  record cpu-usage-record {
+    user: f64,
+    system: f64
+  }
+
+  record memory-usage-record {
+    rss: f64,
+    heap-total: f64,
+    heap-used: f64,
+    external: f64,
+    array-buffers: f64
+  }
+
+  record resource-usage-record {
+    user-cpu-time: f64,
+    system-cpu-time: f64,
+    max-rss: f64,
+    shared-memory-size: f64,
+    unshared-data-size: f64,
+    unshared-stack-size: f64,
+    minor-page-fault: f64,
+    major-page-fault: f64,
+    swapped-out: f64,
+    fs-read: f64,
+    fs-write: f64,
+    ipc-sent: f64,
+    ipc-received: f64,
+    signals-count: f64,
+    voluntary-context-switches: f64,
+    involuntary-context-switches: f64
+  }
+
+  metadata: func() -> result<process-metadata, error>;
+
+  get-state: func() -> result<state, error>;
+
+  set-title: func(value: string) -> result<_, error>;
+
+  set-debug-port: func(value: f64) -> result<_, error>;
+
+  set-exit-code: func(value: option<exit-code>) -> result<_, error>;
+
+  set-flag: func(name: flag, value: bool) -> result<_, error>;
+
+  env-entries: func() -> result<list<tuple<string, string>>, error>;
+
+  env-get: func(name: string) -> result<option<string>, error>;
+
+  env-set: func(name: string, value: option<string>) -> result<_, error>;
+
+  cwd: func() -> result<string, error>;
+
+  chdir: func(directory: string) -> result<_, error>;
+
+  cpu-usage: func(previous: option<cpu-usage-record>) -> result<cpu-usage-record, error>;
+
+  thread-cpu-usage: func(previous: option<cpu-usage-record>) -> result<cpu-usage-record, error>;
+
+  memory-usage: func() -> result<memory-usage-record, error>;
+
+  rss: func() -> result<f64, error>;
+
+  resource-usage: func() -> result<resource-usage-record, error>;
+
+  /// Split the clock to avoid engines that lift WIT u64 as an imprecise JS number.
+  record clock-time {
+    seconds: f64,
+    nanoseconds: u32
+  }
+
+  hrtime: func() -> result<clock-time, error>;
+
+  uptime: func() -> result<f64, error>;
+
+  available-memory: func() -> result<f64, error>;
+
+  constrained-memory: func() -> result<f64, error>;
+
+  get-active-resources-info: func() -> result<list<string>, error>;
+
+  get-id: func(kind: identity) -> result<u32, error>;
+
+  set-id: func(kind: identity, value: id) -> result<_, error>;
+
+  getgroups: func() -> result<list<u32>, error>;
+
+  setgroups: func(groups: list<id>) -> result<_, error>;
+
+  initgroups: func(user: id, extra-group: id) -> result<_, error>;
+
+  kill: func(pid: s32, signal: signal) -> result<bool, error>;
+
+  umask: func(mask: mask) -> result<u32, error>;
+
+  exit: func(code: option<exit-code>) -> result<_, error>;
+
+  abort: func() -> result<_, error>;
+
+  execve: func(file: string, args: list<string>, env: option<list<tuple<string, string>>>) -> result<_, error>;
+
+  load-env-file: func(path: option<path>) -> result<_, error>;
+
+  set-source-maps-enabled: func(value: bool) -> result<_, error>;
+
+  emit-warning: func(warning: warning) -> result<_, error>;
+
+  permission-has: func(scope: string, reference: option<path>) -> result<bool, error>;
+
+  get-report: func(error: option<warning>) -> result<string, error>;
+
+  write-report: func(filename: option<string>, error: option<warning>) -> result<string, error>;
+
+  get-report-options: func() -> result<report-options, error>;
+
+  set-report-option: func(name: report-option, value: report-value) -> result<_, error>;
+
+  allowed-flags: func() -> result<list<string>, error>;
+
+  allowed-flag: func(value: string) -> result<bool, error>;
+}