Skip to content

Commit 94e017f

Browse files
alexcrichtondicej
alexcrichton
and
dicej
authored
Update proposals/http/wit-0.3.0-draft/worlds.wit
Co-authored-by: Joel Dice <joel.dice@akamai.com>
1 parent d587e82 commit 94e017f

1 file changed

Lines changed: 117 additions & 117 deletions

File tree

‎proposals/http/wit-0.3.0-draft/worlds.wit‎

Lines changed: 117 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -1,118 +1,118 @@
1-
package wasi:http@0.3.0-rc-2026-03-15;
2-
3-
/// The `wasi:http/service` world captures a broad category of HTTP services
4-
/// including web applications, API servers, and proxies. It may be `include`d
5-
/// in more specific worlds such as `wasi:http/middleware`.
6-
@since(version = 0.3.0-rc-2026-03-15)
7-
world service {
8-
/// HTTP services have access to time and randomness.
9-
include wasi:clocks/imports@0.3.0-rc-2026-03-15;
10-
include wasi:random/imports@0.3.0-rc-2026-03-15;
11-
12-
/// Services have standard output and error streams which are expected to
13-
/// terminate in a developer-facing console provided by the host.
14-
import wasi:cli/stdout@0.3.0-rc-2026-03-15;
15-
import wasi:cli/stderr@0.3.0-rc-2026-03-15;
16-
17-
/// TODO: this is a temporary workaround until component tooling is able to
18-
/// gracefully handle the absence of stdin. Hosts must return an eof stream
19-
/// for this import, which is what wasi-libc + tooling will do automatically
20-
/// when this import is properly removed.
21-
import wasi:cli/stdin@0.3.0-rc-2026-03-15;
22-
23-
/// This is the default `client` to use when user code simply wants to make an
24-
/// HTTP request (e.g., via `fetch()`).
25-
import client;
26-
27-
/// The host delivers incoming HTTP requests to a component by calling the
28-
/// `handle` function of this exported interface. A host may arbitrarily reuse
29-
/// or not reuse component instance when delivering incoming HTTP requests and
30-
/// thus a component must be able to handle 0..N calls to `handle`.
31-
///
32-
/// This may also be used to receive synthesized or forwarded requests from
33-
/// another component.
34-
///
35-
/// # Concurrent instance reuse
36-
///
37-
/// Hosts may concurrently invoke this `handler` interface multiple times,
38-
/// even when previous requests have yet to finish processing. This means that
39-
/// the guest, if it becomes idle while being blocked on I/O, may be required
40-
/// to service multiple requests at the same time. Guests can opt-out of
41-
/// this behavior with component-model backpressure to avoid sending more
42-
/// requests to this instance while a previous one is being processed,
43-
/// however.
44-
///
45-
/// In some contexts, correct attribution of resource usage and I/O operations
46-
/// is an important requirement. For example, correct implementation of the
47-
/// CDN-Loop header in the context of a proxy server requires that outgoing
48-
/// HTTP requests can be attributed to the incoming HTTP request that induced
49-
/// them.
50-
///
51-
/// Hosts with this requirement must associate work happening on the same
52-
/// component model task that the `handler` was originally invoked on with the
53-
/// same incoming HTTP request.
54-
///
1+
package wasi:http@0.3.0-rc-2026-03-15;
2+
3+
/// The `wasi:http/service` world captures a broad category of HTTP services
4+
/// including web applications, API servers, and proxies. It may be `include`d
5+
/// in more specific worlds such as `wasi:http/middleware`.
6+
@since(version = 0.3.0-rc-2026-03-15)
7+
world service {
8+
/// HTTP services have access to time and randomness.
9+
include wasi:clocks/imports@0.3.0-rc-2026-03-15;
10+
include wasi:random/imports@0.3.0-rc-2026-03-15;
11+
12+
/// Services have standard output and error streams which are expected to
13+
/// terminate in a developer-facing console provided by the host.
14+
import wasi:cli/stdout@0.3.0-rc-2026-03-15;
15+
import wasi:cli/stderr@0.3.0-rc-2026-03-15;
16+
17+
/// TODO: this is a temporary workaround until component tooling is able to
18+
/// gracefully handle the absence of stdin. Hosts must return an eof stream
19+
/// for this import, which is what wasi-libc + tooling will do automatically
20+
/// when this import is properly removed.
21+
import wasi:cli/stdin@0.3.0-rc-2026-03-15;
22+
23+
/// This is the default `client` to use when user code simply wants to make an
24+
/// HTTP request (e.g., via `fetch()`).
25+
import client;
26+
27+
/// The host delivers incoming HTTP requests to a component by calling the
28+
/// `handle` function of this exported interface. A host may arbitrarily reuse
29+
/// or not reuse component instance when delivering incoming HTTP requests and
30+
/// thus a component must be able to handle 0..N calls to `handle`.
31+
///
32+
/// This may also be used to receive synthesized or forwarded requests from
33+
/// another component.
34+
///
35+
/// # Concurrent instance reuse
36+
///
37+
/// Hosts may concurrently invoke this `handler` interface multiple times,
38+
/// even when previous requests have yet to finish processing. This means that
39+
/// the guest, if it becomes idle while being blocked on I/O, may be required
40+
/// to service multiple requests at the same time. Guests can opt-out of
41+
/// this behavior with component-model backpressure to avoid sending more
42+
/// requests to this instance while a previous one is being processed,
43+
/// however.
44+
///
45+
/// In some contexts, correct attribution of resource usage and I/O operations
46+
/// is an important requirement. For example, correct implementation of the
47+
/// CDN-Loop header in the context of a proxy server requires that outgoing
48+
/// HTTP requests can be attributed to the incoming HTTP request that induced
49+
/// them.
50+
///
51+
/// Hosts with this requirement must associate work happening on the same
52+
/// component model task that the `handler` was originally invoked on with the
53+
/// same incoming HTTP request.
54+
///
5555
/// Conversely, guests should ensure that calls to imported interfaces happen on
56-
/// the same component model task that the `handler` was originally invoked
57-
/// on. Guest runtime implementations that do not provide this guarantee are
58-
/// encouraged to opt-out of concurrent through the component model's
59-
/// backpressure mechanisms.
60-
///
61-
/// Note that hosts can't rely on this guarantee being upheld by all guests,
62-
/// and shouldn't treat it as part of their security model. Instead, the
63-
/// combination of the above host and guest requirements enable hosts to
64-
/// enforce correctness properties on behalf of the overall system a guest is
65-
/// part of.
66-
export handler;
67-
}
68-
69-
/// The `wasi:http/middleware` world captures HTTP services that forward HTTP
70-
/// Requests to another handler.
71-
///
72-
/// Components may implement this world to allow them to participate in handler
73-
/// "chains" where a `request` flows through handlers on its way to some terminal
74-
/// `service` and corresponding `response` flows in the opposite direction.
75-
@since(version = 0.3.0-rc-2026-03-15)
76-
world middleware {
77-
include service;
78-
import handler;
79-
}
80-
81-
/// This interface defines a handler of HTTP Requests.
82-
///
83-
/// In a `wasi:http/service` this interface is exported to respond to an
84-
/// incoming HTTP Request with a Response.
85-
///
86-
/// In `wasi:http/middleware` this interface is both exported and imported as
87-
/// the "downstream" and "upstream" directions of the middleware chain.
88-
@since(version = 0.3.0-rc-2026-03-15)
89-
interface handler {
90-
use types.{request, response, error-code};
91-
92-
/// This function may be called with either an incoming request read from the
93-
/// network or a request synthesized or forwarded by another component.
94-
handle: async func(
95-
request: request,
96-
) -> result<response, error-code>;
97-
}
98-
99-
/// This interface defines an HTTP client for sending "outgoing" requests.
100-
///
101-
/// Most components are expected to import this interface to provide the
102-
/// capability to send HTTP requests to arbitrary destinations on a network.
103-
///
104-
/// The type signature of `client.send` is the same as `handler.handle`. This
105-
/// duplication is currently necessary because some Component Model tooling
106-
/// (including WIT itself) is unable to represent a component importing two
107-
/// instances of the same interface. A `client.send` import may be linked
108-
/// directly to a `handler.handle` export to bypass the network.
109-
@since(version = 0.3.0-rc-2026-03-15)
110-
interface client {
111-
use types.{request, response, error-code};
112-
113-
// This function may be used to either send an outgoing request over the
114-
// network or to forward it to another component.
115-
send: async func(
116-
request: request,
117-
) -> result<response, error-code>;
118-
}
56+
/// the same component model task that the `handler` was originally invoked
57+
/// on. Guest runtime implementations that do not provide this guarantee are
58+
/// encouraged to opt-out of concurrent reuse through the component model's
59+
/// backpressure mechanisms.
60+
///
61+
/// Note that hosts can't rely on this guarantee being upheld by all guests,
62+
/// and shouldn't treat it as part of their security model. Instead, the
63+
/// combination of the above host and guest requirements enable hosts to
64+
/// enforce correctness properties on behalf of the overall system a guest is
65+
/// part of.
66+
export handler;
67+
}
68+
69+
/// The `wasi:http/middleware` world captures HTTP services that forward HTTP
70+
/// Requests to another handler.
71+
///
72+
/// Components may implement this world to allow them to participate in handler
73+
/// "chains" where a `request` flows through handlers on its way to some terminal
74+
/// `service` and corresponding `response` flows in the opposite direction.
75+
@since(version = 0.3.0-rc-2026-03-15)
76+
world middleware {
77+
include service;
78+
import handler;
79+
}
80+
81+
/// This interface defines a handler of HTTP Requests.
82+
///
83+
/// In a `wasi:http/service` this interface is exported to respond to an
84+
/// incoming HTTP Request with a Response.
85+
///
86+
/// In `wasi:http/middleware` this interface is both exported and imported as
87+
/// the "downstream" and "upstream" directions of the middleware chain.
88+
@since(version = 0.3.0-rc-2026-03-15)
89+
interface handler {
90+
use types.{request, response, error-code};
91+
92+
/// This function may be called with either an incoming request read from the
93+
/// network or a request synthesized or forwarded by another component.
94+
handle: async func(
95+
request: request,
96+
) -> result<response, error-code>;
97+
}
98+
99+
/// This interface defines an HTTP client for sending "outgoing" requests.
100+
///
101+
/// Most components are expected to import this interface to provide the
102+
/// capability to send HTTP requests to arbitrary destinations on a network.
103+
///
104+
/// The type signature of `client.send` is the same as `handler.handle`. This
105+
/// duplication is currently necessary because some Component Model tooling
106+
/// (including WIT itself) is unable to represent a component importing two
107+
/// instances of the same interface. A `client.send` import may be linked
108+
/// directly to a `handler.handle` export to bypass the network.
109+
@since(version = 0.3.0-rc-2026-03-15)
110+
interface client {
111+
use types.{request, response, error-code};
112+
113+
// This function may be used to either send an outgoing request over the
114+
// network or to forward it to another component.
115+
send: async func(
116+
request: request,
117+
) -> result<response, error-code>;
118+
}

0 commit comments

Comments
 (0)