wasmkeep 0.2.0__py3-none-any.whl

wasmkeep/wit/actor.wit

@@ -0,0 +1,273 @@
+/// The `wasmkeep:actor` package: everything an actor can call on the host, and
+/// everything the host calls on an actor.
+///
+/// An actor is addressed as `tenant/class/name`. One component implements one
+/// class; each distinct name is an independent instance with its own SQLite
+/// database. The host delivers events (requests, alarms) to an instance one at
+/// a time, in arrival order: an actor never runs concurrently with itself.
+///
+/// Versioning: 0.x minor versions may break guests; every change comes with a
+/// migration note (docs/adr). See docs/adr/0002-wasmkeep-actor-wit-v0.1.md and
+/// docs/adr/0003-websockets-wit-v0.2.md.
+package wasmkeep:actor@0.2.0;
+
+/// Types shared by several interfaces.
+interface types {
+    /// A SQL value, mapping one to one onto SQLite's storage classes.
+    variant value {
+        null,
+        integer(s64),
+        real(f64),
+        text(string),
+        blob(list<u8>),
+    }
+
+    /// The result set of a query: column names, then one list of values per
+    /// row, in column order.
+    record rows {
+        columns: list<string>,
+        values: list<list<value>>,
+    }
+
+    /// Why a statement failed.
+    enum sql-error-kind {
+        /// The SQL did not parse, or referred to a missing table or column.
+        syntax,
+        /// A constraint failed (UNIQUE, NOT NULL, CHECK, FOREIGN KEY).
+        constraint,
+        /// Parameter count or types do not match the statement.
+        bind,
+        /// The text held more than one statement; send one at a time.
+        multiple-statements,
+        /// The database reached its size cap (default 1 GB); reads still work.
+        quota-exceeded,
+        /// The statement tried something actors may not do (ATTACH, a
+        /// PRAGMA outside the allowed set, loading extensions).
+        not-allowed,
+        /// The host failed (disk, I/O). The event should fail.
+        internal,
+    }
+
+    record sql-error {
+        kind: sql-error-kind,
+        /// Human-readable detail, usually SQLite's own message.
+        message: string,
+    }
+}
+
+/// The actor's own SQLite database. Nothing else can read or write it.
+///
+/// Each call runs one statement. Outside an explicit transaction every
+/// statement commits on its own. `BEGIN` ... `COMMIT` across several calls
+/// within one event is allowed; a transaction still open when the event ends
+/// (or traps) is rolled back. A statement that fails in a way that rolls the
+/// open transaction back (it ran past its deadline or the event's SQL CPU
+/// budget, say) ends that transaction: nothing of it is kept, and every
+/// later storage statement of the event is refused with `not-allowed`
+/// (but a `ROLLBACK`, which is what already happened, succeeds).
+interface storage {
+    use types.{value, rows, sql-error};
+
+    /// Runs a statement that returns no rows; returns the number of rows
+    /// changed. Returns once the write is committed to the local database.
+    exec: func(sql: string, params: list<value>) -> result<u64, sql-error>;
+
+    /// Like `exec`, but returns only once the write is durable: replicated to
+    /// the bucket when the node has one, fsynced locally when it does not.
+    /// Inside a transaction it takes only `COMMIT` (or `END`), and makes the
+    /// whole transaction durable; any other statement there is refused with
+    /// `not-allowed` before it runs. Outside one it does not take a
+    /// statement that opens or controls a transaction (`BEGIN`, `SAVEPOINT`):
+    /// run those with `exec`.
+    exec-durable: func(sql: string, params: list<value>) -> result<u64, sql-error>;
+
+    /// Runs a statement and returns its rows.
+    query: func(sql: string, params: list<value>) -> result<rows, sql-error>;
+
+    /// Deletes this actor: its database is removed once the current event
+    /// ends, and its pending alarm is cleared. The next event to this address
+    /// starts a fresh actor.
+    delete-self: func();
+}
+
+/// One pending alarm per actor. Alarms survive restarts and fire at least
+/// once: an `on-alarm` that fails or traps is retried, so handlers must be
+/// idempotent.
+interface alarms {
+    /// Schedules `on-alarm` at `at` (milliseconds since the Unix epoch),
+    /// replacing any pending alarm. A time in the past fires as soon as
+    /// possible.
+    set-alarm: func(at: u64);
+
+    /// The pending alarm time, if any.
+    get-alarm: func() -> option<u64>;
+
+    /// Cancels the pending alarm, if any.
+    clear-alarm: func();
+}
+
+/// Calls between actors of the same tenant.
+interface actors {
+    /// A fully buffered request, delivered to the callee's
+    /// `wasi:http/incoming-handler` like any other request.
+    record request {
+        method: string,
+        /// Path and query, starting with `/`.
+        path: string,
+        headers: list<tuple<string, string>>,
+        body: list<u8>,
+    }
+
+    record response {
+        status: u16,
+        headers: list<tuple<string, string>>,
+        body: list<u8>,
+    }
+
+    variant call-error {
+        /// The address is not `class/name`, or the class does not exist.
+        invalid-address(string),
+        /// The call would re-enter an actor already waiting in this call
+        /// chain (including the caller itself), which would deadlock.
+        reentrant,
+        /// The request or response exceeded the body limit (16 MB).
+        too-large,
+        /// The callee did not answer within the event's wall-clock limit.
+        timeout,
+        /// The callee trapped, or the host could not deliver the call.
+        failed(string),
+    }
+
+    /// Sends `request` to the actor at `address` (`class/name`, within the
+    /// caller's tenant) and waits for its response. The caller's own event
+    /// stays in progress meanwhile: other events to the caller wait.
+    ///
+    /// The callee sees `x-wasmkeep-caller: <tenant>/<class>/<name>`, the name
+    /// percent-encoded (every byte but ASCII letters, digits and `-._~`), so
+    /// `room 1` arrives as `room%201`. The host removes that header from
+    /// requests coming from outside, so the callee can trust it.
+    call: func(address: string, request: request) -> result<response, call-error>;
+
+    /// An actor's address. Within a tenant, `class/name` is what `call`
+    /// takes; the name is decoded (any text without `/` or control characters).
+    record actor-address {
+        tenant: string,
+        class: string,
+        name: string,
+    }
+
+    /// This actor's own address: an actor does not otherwise know its name
+    /// or class (requests arrive with `/actor/<class>/<name>` removed, and
+    /// alarms carry nothing). For links to itself, for telling other actors
+    /// who it is, and for anything keyed by its name.
+    self-address: func() -> actor-address;
+}
+
+/// WebSocket connections to this actor.
+///
+/// The host accepts upgrades on the actor's path and owns the sockets, so a
+/// connection stays open while the actor hibernates; the next message wakes
+/// it. A connection id is only valid in the actor it was opened on.
+interface websockets {
+    /// A WebSocket message.
+    variant message {
+        text(string),
+        binary(list<u8>),
+    }
+
+    variant send-error {
+        /// The connection is closed, or belongs to another actor.
+        unknown-connection,
+        /// The client is not reading fast enough; the message was dropped.
+        backpressure,
+    }
+
+    /// Queues `msg` on the connection.
+    send: func(conn: u64, msg: message) -> result<_, send-error>;
+
+    /// Closes the connection with a close code (1000 = normal) and reason.
+    close: func(conn: u64, code: u16, reason: string);
+
+    /// This actor's open connections, oldest first.
+    connections: func() -> list<u64>;
+}
+
+/// Configuration and secrets the operator gives an actor class: an API
+/// key, a webhook URL, a feature flag. Values come, by name, last wins,
+/// from the deployed version's plain configuration (`wasmkeep deploy
+/// --config CLASS=FILE`), the app's secrets sealed in the bucket (`wasmkeep
+/// secrets set`), and files on the node (`wasmkeep serve --env CLASS=FILE`),
+/// never from the component. They are the same for every actor of the class
+/// and read-only, and change only between events, never during one: when a
+/// deploy or a secrets change lands (the next event runs in a new instance)
+/// or the node restarts.
+interface env {
+    /// The value of `name`, or none if it is not set.
+    get: func(name: string) -> option<string>;
+}
+
+/// WasmKeep's own part of the actor world: what the host bindings and the
+/// guest SDK are generated from.
+world actor-core {
+    import storage;
+    import alarms;
+    import actors;
+    import websockets;
+    import env;
+    use websockets.{message};
+
+    /// Runs before the first event an instance handles with this component
+    /// version: once for a new actor, and again after each deploy. Use it to
+    /// create or migrate tables. An error fails the event; it is retried with
+    /// the next event.
+    export on-init: func() -> result<_, string>;
+
+    /// Runs when the pending alarm is due. An error or trap schedules a retry.
+    export on-alarm: func() -> result<_, string>;
+
+    /// A client upgraded a GET to `path` (the part after the actor's name,
+    /// with its query). Return an error to refuse it: the connection is then
+    /// closed with code 1008 and the error as reason. It runs before the host
+    /// answers the upgrade (101), so the client is connected only once the
+    /// actor has accepted it. What the actor sends meanwhile waits in the
+    /// socket's queue, with its usual cap (`backpressure` past 4 MiB). A
+    /// client that leaves before the 101 (or a node relaying for it, which
+    /// gives up after 30 s) still gets this event if it was already queued,
+    /// followed by `on-websocket-close` with code 1006.
+    export on-websocket-open: func(conn: u64, path: string) -> result<_, string>;
+
+    /// A message arrived on one of this actor's connections.
+    export on-websocket-message: func(conn: u64, msg: message);
+
+    /// A connection closed (by the client, by `close`, or by the host).
+    export on-websocket-close: func(conn: u64, code: u16, reason: string);
+}
+
+/// The world actor components target: WasmKeep's interfaces plus the standard
+/// `wasi:http/proxy` world, whose `incoming-handler` receives requests and
+/// whose imports provide outbound HTTP, clocks, randomness and stdio.
+///
+/// This is also the capability list. Toolchains import more than they use
+/// (ComponentizeJS and componentize-py import `wasi:filesystem`, Python also
+/// `wasi:sockets`), so the host links those too, inert: no preopened
+/// directories, and sockets and name lookups refused.
+world actor {
+    include actor-core;
+    include wasi:http/proxy@0.2.12;
+
+    // Imported by the standard library of Rust (and most languages) on
+    // wasm32-wasip2. The host provides them empty: no arguments, no
+    // environment variables, no terminal. Configuration arrives through
+    // the `env` interface instead.
+    import wasi:cli/environment@0.2.12;
+    import wasi:cli/exit@0.2.12;
+    import wasi:cli/terminal-input@0.2.12;
+    import wasi:cli/terminal-output@0.2.12;
+    import wasi:cli/terminal-stdin@0.2.12;
+    import wasi:cli/terminal-stdout@0.2.12;
+    import wasi:cli/terminal-stderr@0.2.12;
+    // Seeds the standard library's hash maps (Rust's `HashMap`, used by the
+    // SDK's key-value client among others). The host provides it, as every
+    // WASI 0.2 interface it links.
+    import wasi:random/insecure-seed@0.2.12;
+}

wasmkeep/wit/deps/cli.wit

@@ -0,0 +1,233 @@
+package wasi:cli@0.2.12;
+
+@since(version = 0.2.0)
+interface environment {
+  /// 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.
+  @since(version = 0.2.0)
+  get-environment: func() -> list<tuple<string, string>>;
+
+  /// Get the POSIX-style arguments to the program.
+  @since(version = 0.2.0)
+  get-arguments: func() -> list<string>;
+
+  /// Return a path that programs should use as their initial current working
+  /// directory, interpreting `.` as shorthand for this.
+  @since(version = 0.2.0)
+  initial-cwd: func() -> option<string>;
+}
+
+@since(version = 0.2.0)
+interface exit {
+  /// Exit the current instance and any linked instances.
+  @since(version = 0.2.0)
+  exit: func(status: result);
+
+  /// Exit the current instance and any linked instances, reporting the
+  /// specified status code to the host.
+  ///
+  /// The meaning of the code depends on the context, with 0 usually meaning
+  /// "success", and other values indicating various types of failure.
+  ///
+  /// This function does not return; the effect is analogous to a trap, but
+  /// without the connotation that something bad has happened.
+  @since(version = 0.2.12)
+  exit-with-code: func(status-code: u8);
+}
+
+@since(version = 0.2.0)
+interface run {
+  /// Run the program.
+  @since(version = 0.2.0)
+  run: func() -> result;
+}
+
+@since(version = 0.2.0)
+interface stdin {
+  @since(version = 0.2.0)
+  use wasi:io/streams@0.2.12.{input-stream};
+
+  @since(version = 0.2.0)
+  get-stdin: func() -> input-stream;
+}
+
+@since(version = 0.2.0)
+interface stdout {
+  @since(version = 0.2.0)
+  use wasi:io/streams@0.2.12.{output-stream};
+
+  @since(version = 0.2.0)
+  get-stdout: func() -> output-stream;
+}
+
+@since(version = 0.2.0)
+interface stderr {
+  @since(version = 0.2.0)
+  use wasi:io/streams@0.2.12.{output-stream};
+
+  @since(version = 0.2.0)
+  get-stderr: func() -> output-stream;
+}
+
+/// Terminal input.
+///
+/// In the future, this may include functions for disabling echoing,
+/// disabling input buffering so that keyboard events are sent through
+/// immediately, querying supported features, and so on.
+@since(version = 0.2.0)
+interface terminal-input {
+  /// The input side of a terminal.
+  @since(version = 0.2.0)
+  resource terminal-input;
+}
+
+/// Terminal output.
+///
+/// In the future, this may include functions for querying the terminal
+/// size, being notified of terminal size changes, querying supported
+/// features, and so on.
+@since(version = 0.2.0)
+interface terminal-output {
+  /// The output side of a terminal.
+  @since(version = 0.2.0)
+  resource terminal-output;
+}
+
+/// An interface providing an optional `terminal-input` for stdin as a
+/// link-time authority.
+@since(version = 0.2.0)
+interface terminal-stdin {
+  @since(version = 0.2.0)
+  use terminal-input.{terminal-input};
+
+  /// If stdin is connected to a terminal, return a `terminal-input` handle
+  /// allowing further interaction with it.
+  @since(version = 0.2.0)
+  get-terminal-stdin: func() -> option<terminal-input>;
+}
+
+/// An interface providing an optional `terminal-output` for stdout as a
+/// link-time authority.
+@since(version = 0.2.0)
+interface terminal-stdout {
+  @since(version = 0.2.0)
+  use terminal-output.{terminal-output};
+
+  /// If stdout is connected to a terminal, return a `terminal-output` handle
+  /// allowing further interaction with it.
+  @since(version = 0.2.0)
+  get-terminal-stdout: func() -> option<terminal-output>;
+}
+
+/// An interface providing an optional `terminal-output` for stderr as a
+/// link-time authority.
+@since(version = 0.2.0)
+interface terminal-stderr {
+  @since(version = 0.2.0)
+  use terminal-output.{terminal-output};
+
+  /// If stderr is connected to a terminal, return a `terminal-output` handle
+  /// allowing further interaction with it.
+  @since(version = 0.2.0)
+  get-terminal-stderr: func() -> option<terminal-output>;
+}
+
+@since(version = 0.2.0)
+world imports {
+  @since(version = 0.2.0)
+  import environment;
+  @since(version = 0.2.0)
+  import exit;
+  @since(version = 0.2.0)
+  import wasi:io/error@0.2.12;
+  @since(version = 0.2.0)
+  import wasi:io/poll@0.2.12;
+  @since(version = 0.2.0)
+  import wasi:io/streams@0.2.12;
+  @since(version = 0.2.0)
+  import stdin;
+  @since(version = 0.2.0)
+  import stdout;
+  @since(version = 0.2.0)
+  import stderr;
+  @since(version = 0.2.0)
+  import terminal-input;
+  @since(version = 0.2.0)
+  import terminal-output;
+  @since(version = 0.2.0)
+  import terminal-stdin;
+  @since(version = 0.2.0)
+  import terminal-stdout;
+  @since(version = 0.2.0)
+  import terminal-stderr;
+  import wasi:clocks/monotonic-clock@0.2.12;
+  import wasi:clocks/wall-clock@0.2.12;
+  @unstable(feature = clocks-timezone)
+  import wasi:clocks/timezone@0.2.12;
+  import wasi:filesystem/types@0.2.12;
+  import wasi:filesystem/preopens@0.2.12;
+  import wasi:sockets/network@0.2.12;
+  import wasi:sockets/instance-network@0.2.12;
+  import wasi:sockets/udp@0.2.12;
+  import wasi:sockets/udp-create-socket@0.2.12;
+  import wasi:sockets/tcp@0.2.12;
+  import wasi:sockets/tcp-create-socket@0.2.12;
+  import wasi:sockets/ip-name-lookup@0.2.12;
+  import wasi:random/random@0.2.12;
+  import wasi:random/insecure@0.2.12;
+  import wasi:random/insecure-seed@0.2.12;
+}
+@since(version = 0.2.0)
+world command {
+  @since(version = 0.2.0)
+  import environment;
+  @since(version = 0.2.0)
+  import exit;
+  @since(version = 0.2.0)
+  import wasi:io/error@0.2.12;
+  @since(version = 0.2.0)
+  import wasi:io/poll@0.2.12;
+  @since(version = 0.2.0)
+  import wasi:io/streams@0.2.12;
+  @since(version = 0.2.0)
+  import stdin;
+  @since(version = 0.2.0)
+  import stdout;
+  @since(version = 0.2.0)
+  import stderr;
+  @since(version = 0.2.0)
+  import terminal-input;
+  @since(version = 0.2.0)
+  import terminal-output;
+  @since(version = 0.2.0)
+  import terminal-stdin;
+  @since(version = 0.2.0)
+  import terminal-stdout;
+  @since(version = 0.2.0)
+  import terminal-stderr;
+  import wasi:clocks/monotonic-clock@0.2.12;
+  import wasi:clocks/wall-clock@0.2.12;
+  @unstable(feature = clocks-timezone)
+  import wasi:clocks/timezone@0.2.12;
+  import wasi:filesystem/types@0.2.12;
+  import wasi:filesystem/preopens@0.2.12;
+  import wasi:sockets/network@0.2.12;
+  import wasi:sockets/instance-network@0.2.12;
+  import wasi:sockets/udp@0.2.12;
+  import wasi:sockets/udp-create-socket@0.2.12;
+  import wasi:sockets/tcp@0.2.12;
+  import wasi:sockets/tcp-create-socket@0.2.12;
+  import wasi:sockets/ip-name-lookup@0.2.12;
+  import wasi:random/random@0.2.12;
+  import wasi:random/insecure@0.2.12;
+  import wasi:random/insecure-seed@0.2.12;
+
+  @since(version = 0.2.0)
+  export run;
+}

wasmkeep/wit/deps/clocks.wit

@@ -0,0 +1,162 @@
+package wasi:clocks@0.2.12;
+
+/// WASI Monotonic Clock is a clock API intended to let users measure elapsed
+/// time.
+///
+/// It is intended to be portable at least between Unix-family platforms and
+/// Windows.
+///
+/// A monotonic clock is a clock which has an unspecified initial value, and
+/// successive reads of the clock will produce non-decreasing values.
+@since(version = 0.2.0)
+interface monotonic-clock {
+  @since(version = 0.2.0)
+  use wasi:io/poll@0.2.12.{pollable};
+
+  /// An instant in time, in nanoseconds. An instant is relative to an
+  /// unspecified initial value, and can only be compared to instances from
+  /// the same monotonic-clock.
+  @since(version = 0.2.0)
+  type instant = u64;
+
+  /// A duration of time, in nanoseconds.
+  @since(version = 0.2.0)
+  type duration = u64;
+
+  /// Read the current value of the clock.
+  ///
+  /// The clock is monotonic, therefore calling this function repeatedly will
+  /// produce a sequence of non-decreasing values.
+  ///
+  /// For completeness, this function traps if it's not possible to represent
+  /// the value of the clock in an `instant`. Consequently, implementations
+  /// should ensure that the starting time is low enough to avoid the
+  /// possibility of overflow in practice.
+  @since(version = 0.2.0)
+  now: func() -> instant;
+
+  /// Query the resolution of the clock. Returns the duration of time
+  /// corresponding to a clock tick.
+  @since(version = 0.2.0)
+  resolution: func() -> duration;
+
+  /// Create a `pollable` which will resolve once the specified instant
+  /// has occurred.
+  @since(version = 0.2.0)
+  subscribe-instant: func(when: instant) -> pollable;
+
+  /// Create a `pollable` that will resolve after the specified duration has
+  /// elapsed from the time this function is invoked.
+  @since(version = 0.2.0)
+  subscribe-duration: func(when: duration) -> pollable;
+}
+
+/// WASI Wall Clock is a clock API intended to let users query the current
+/// time. The name "wall" makes an analogy to a "clock on the wall", which
+/// is not necessarily monotonic as it may be reset.
+///
+/// It is intended to be portable at least between Unix-family platforms and
+/// Windows.
+///
+/// A wall clock is a clock which measures the date and time according to
+/// some external reference.
+///
+/// External references may be reset, so this clock is not necessarily
+/// monotonic, making it unsuitable for measuring elapsed time.
+///
+/// It is intended for reporting the current date and time for humans.
+@since(version = 0.2.0)
+interface wall-clock {
+  /// A time and date in seconds plus nanoseconds.
+  @since(version = 0.2.0)
+  record datetime {
+    seconds: u64,
+    nanoseconds: u32,
+  }
+
+  /// Read the current value of the clock.
+  ///
+  /// This clock is not monotonic, therefore calling this function repeatedly
+  /// will not necessarily produce a sequence of non-decreasing values.
+  ///
+  /// The returned timestamps represent the number of seconds since
+  /// 1970-01-01T00:00:00Z, also known as [POSIX's Seconds Since the Epoch],
+  /// also known as [Unix Time].
+  ///
+  /// The nanoseconds field of the output is always less than 1000000000.
+  ///
+  /// [POSIX's Seconds Since the Epoch]: https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_16
+  /// [Unix Time]: https://en.wikipedia.org/wiki/Unix_time
+  @since(version = 0.2.0)
+  now: func() -> datetime;
+
+  /// Query the resolution of the clock.
+  ///
+  /// The nanoseconds field of the output is always less than 1000000000.
+  @since(version = 0.2.0)
+  resolution: func() -> datetime;
+}
+
+@unstable(feature = clocks-timezone)
+interface timezone {
+  @unstable(feature = clocks-timezone)
+  use wall-clock.{datetime};
+
+  /// Information useful for displaying the timezone of a specific `datetime`.
+  ///
+  /// This information may vary within a single `timezone` to reflect daylight
+  /// saving time adjustments.
+  @unstable(feature = clocks-timezone)
+  record timezone-display {
+    /// The number of seconds difference between UTC time and the local
+    /// time of the timezone.
+    ///
+    /// The returned value will always be less than 86400 which is the
+    /// number of seconds in a day (24*60*60).
+    ///
+    /// In implementations that do not expose an actual time zone, this
+    /// should return 0.
+    utc-offset: s32,
+    /// The abbreviated name of the timezone to display to a user. The name
+    /// `UTC` indicates Coordinated Universal Time. Otherwise, this should
+    /// reference local standards for the name of the time zone.
+    ///
+    /// In implementations that do not expose an actual time zone, this
+    /// should be the string `UTC`.
+    ///
+    /// In time zones that do not have an applicable name, a formatted
+    /// representation of the UTC offset may be returned, such as `-04:00`.
+    name: string,
+    /// Whether daylight saving time is active.
+    ///
+    /// In implementations that do not expose an actual time zone, this
+    /// should return false.
+    in-daylight-saving-time: bool,
+  }
+
+  /// Return information needed to display the given `datetime`. This includes
+  /// the UTC offset, the time zone name, and a flag indicating whether
+  /// daylight saving time is active.
+  ///
+  /// If the timezone cannot be determined for the given `datetime`, return a
+  /// `timezone-display` for `UTC` with a `utc-offset` of 0 and no daylight
+  /// saving time.
+  @unstable(feature = clocks-timezone)
+  display: func(when: datetime) -> timezone-display;
+
+  /// The same as `display`, but only return the UTC offset.
+  @unstable(feature = clocks-timezone)
+  utc-offset: func(when: datetime) -> s32;
+}
+
+@since(version = 0.2.0)
+world imports {
+  @since(version = 0.2.0)
+  import wasi:io/poll@0.2.12;
+  @since(version = 0.2.0)
+  import monotonic-clock;
+  @since(version = 0.2.0)
+  import wall-clock;
+  @unstable(feature = clocks-timezone)
+  import timezone;
+}