camel-wit 0.23.0

WIT interface definitions for rust-camel WASM plugins
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

package camel:plugin;

// TODO(WIT-001): This file is a canonical source; camel-all.wit duplicates its content.
// TODO(WIT-006): WIT interface versioning strategy is not yet defined. When the
// WIT tooling supports it, add `@since(version = X.Y.Z)` annotations to each
// interface and world definition to enable compatibility checks.

/// Host-provided capabilities for guest-driven sources.
interface source-host {
    use types.{wasm-exchange, wasm-error, stream-body-handle};

    /// Host-owned HTTP listener handle. Created by the host when
    /// the guest requests an http-listener capability in configure().
    resource http-listener;

    /// Incoming HTTP request delivered to the guest.
    record http-request {
        method: string,
        path: string,
        headers: list<tuple<string, string>>,
        body: stream-body-handle,
    }

    /// Specification for an HTTP listener capability request.
    record http-listener-spec {
        bind: string,
        path: option<string>,
    }

    /// What the guest requests from the host during configure().
    variant capability-request {
        http-listener(http-listener-spec),
    }

    /// The guest's concurrency model declaration.
    variant concurrency-model {
        sequential,
        concurrent(u16),
    }

    /// Result of configure() — declares what the guest needs.
    /// Host rejects if capabilities.len() > 1 or unsupported capability.
    record source-plan {
        capabilities: list<capability-request>,
        concurrency: concurrency-model,
    }

    /// Outcome of submit-exchange.
    variant submit-outcome {
        accepted,
        stopped,
    }

    /// Accept the next HTTP request, or none if cancelled. Async: the guest
    /// `await`s, yielding back to the host until a request arrives (or the run
    /// is cancelled). The body is a `stream-body-handle` — the guest reads
    /// incrementally via `stream<u8>.read`, removing the materialization cap.
    accept-http: async func(listener: borrow<http-listener>)
        -> result<option<http-request>, wasm-error>;

    /// Push an exchange into the pipeline. Returns once the pipeline accepts
    /// the envelope (before full body drain). The guest MUST keep `run` alive
    /// while a submitted body stream is still draining; the stream's terminal
    /// future resolves when the body finished.
    submit-exchange: async func(exchange: wasm-exchange)
        -> result<submit-outcome, wasm-error>;

    /// Check if the host has cancelled the run loop. Stays sync — a quick
    /// peek that must not yield (called in tight guest loops).
    is-cancelled: func() -> bool;
}

/// The guest source world.
world source {
    import source-host;
    use types.{wasm-exchange, wasm-error};
    use source-host.{source-plan, http-listener};

    export configure: func(config: list<tuple<string, string>>)
        -> result<source-plan, wasm-error>;

    export run: async func(listener: borrow<http-listener>) -> result<_, wasm-error>;
}