wasmeld/wit/resident/package.wit

package wasmeld:resident@0.1.0;

/// Event/effect ABI for Components that remain active without monopolizing
/// their Actor thread. The Host owns timers, subscriptions, sockets, streams,
/// and all operating-system handles. A Component handles one bounded event and
/// returns effects before control goes back to the Runtime.
interface actor {
  type resource-id = u64;

  record timer-fired {
    timer-id: resource-id,
    scheduled-at-ns: u64,
  }

  record stream-opened {
    endpoint-id: resource-id,
    stream-id: resource-id,
    peer: option<string>,
  }

  record stream-chunk {
    stream-id: resource-id,
    bytes: list<u8>,
  }

  enum close-reason {
    peer-closed,
    host-closed,
    idle-timeout,
    protocol-error,
    transport-error,
  }

  record stream-closed {
    stream-id: resource-id,
    reason: close-reason,
  }

  record datagram {
    endpoint-id: resource-id,
    peer: string,
    bytes: list<u8>,
  }

  record message {
    subscription-id: resource-id,
    message-id: u64,
    bytes: list<u8>,
  }

  /// Escape hatch for Host-owned event sources such as filesystem watchers,
  /// serial devices, process signals, or platform-specific buses. `kind` and
  /// `payload` are interpreted by the separately versioned Host capability
  /// that created `source-id`.
  record source-event {
    source-id: resource-id,
    kind: string,
    payload: list<u8>,
  }

  variant event {
    timer(timer-fired),
    stream-opened(stream-opened),
    stream-data(stream-chunk),
    stream-writable(resource-id),
    stream-half-closed(resource-id),
    stream-closed(stream-closed),
    datagram(datagram),
    message(message),
    source(source-event),
    shutdown,
  }

  record stream-write {
    stream-id: resource-id,
    bytes: list<u8>,
  }

  record datagram-send {
    endpoint-id: resource-id,
    peer: string,
    bytes: list<u8>,
  }

  record timer-arm {
    timer-id: resource-id,
    delay-ms: u64,
    interval-ms: option<u64>,
  }

  record message-ack {
    subscription-id: resource-id,
    message-id: u64,
  }

  record source-command {
    source-id: resource-id,
    command: string,
    payload: list<u8>,
  }

  variant effect {
    write-stream(stream-write),
    close-stream(resource-id),
    pause-stream(resource-id),
    resume-stream(resource-id),
    send-datagram(datagram-send),
    arm-timer(timer-arm),
    cancel-timer(resource-id),
    acknowledge-message(message-ack),
    source-command(source-command),
  }

  variant resident-error {
    event-failed(string),
  }

  handle-event: func(input: event) -> result<list<effect>, resident-error>;
}

world resident-component {
  export actor;
}