Document concurrent instance reuse in wasi:http/service (#920)

* Document concurrent instance reuse in `wasi:http/service`

This commit adds a documentation block to the `wasi:http/service` world
that's the result of discussions in today's WASI subgroup meeting, #918,
and #919. The documentation here indicates a few properties around
concurrent instance reuse, namely:

* Guests should expect to be concurrently reused. If this is not
  acceptable then guests should disable reuse through backpressure
  mechanisms.

* Guests should ensure that outgoing HTTP requests are done within the
  context of the original root task, or the original invocation of
  `handler`. If guests can't implement this then they're expected to use
  backpressure mechanisms instead.

The overall conclusion of the various discussions that have happened
over the past week or so is that it's not possible to provide the
attribute behavior some hosts require exclusively through either
in-guest interactions or pure-host interactions. Instead being able to
reliably provide accurate attribution requires specifically outlining
guidelines for both guests and hosts. The mechanism intended to be used
for attribution is then:

* For hosts such as Wasmtime calls to imports will be able to reflect on
  the current async call stack, notably the root export task. Hosts can
  then use this to correlate an identifier provided when a root task is
  created, providing a strong link from the import call to whatever
  export initiated it. This is expected to work as-is for some guest
  languages, such as Rust, but this is also not a bulletproof solution.
  Guests can always internally call imports from any currently-running
  task, and additionally languages such as JS and Go at this time are
  structured in such a way where imports are not always naturally called
  from the originating export task.

* To enable languages like JS and Go to be able to leverage concurrent
  reuse while providing accurate attribution of outgoing requests to
  incoming requests, the plan is to eventually add and specify
  intrinsics on the component model level to, in a scoped fashion,
  mutate the async call stack. For example a guest would be able to say
  "I'm about to do some work for this component model task". When
  Wasmtime reflects on the async call graph at that time it'd see this
  and understand that the attribution needs to be slightly adjusted to
  what it would otherwise by default be.

The goal with these addition is to enable hosts to be able to reliably
expect to attribute outgoing requests to incoming requests (via async
call graph inspection), provide guests the ability to work today (either
naturally or disabling concurrent reuse via backpressure), and ensure
that well-behaved and idiomatic guests can work reliably with concurrent
reuse in the long-run (via component model intrinsics to massage the
async backtrace that hosts operate with). When this is all combined it's
expected to resolve the concerns of #918 and #919 with idiomatic
bindings in guests and hosts alike.

Closes #918
Closes #919

* Review comments

* Apply suggestions from code review

Co-authored-by: Joel Dice <joel.dice@akamai.com>

* Update proposals/http/wit-0.3.0-draft/worlds.wit

Co-authored-by: Joel Dice <joel.dice@akamai.com>

* fix(http): depend on latest fs in dep lock

* fix(http): renormalize to LF

---------

Co-authored-by: Joel Dice <joel.dice@akamai.com>
Co-authored-by: Bailey Hayes <bailey@cosmonic.com>

Author: 3 people

proposals/http/wit-0.3.0-draft/deps.lock

@@ -1,22 +1,24 @@
 [cli]
 path = "../../cli/wit-0.3.0-draft"
-sha256 = "5be8d35b6397517777497279f1978c71aea0d91c7d63d4f4e0b54d0c1d33efd3"
-sha512 = "faf89924d5d5210d3b4df52d634deb8507c44c632bc0fd1a6fa4351a15ac36e92a039daf945c59c862ea002a748ac213b27c51affa68a90dbe529551f3d63a9b"
-deps = ["filesystem", "random", "sockets"]
+sha256 = "ba19261a3c370fcafd06b549ffb0bbcc7efa10f2dd0c1c33ed36c07a25ea6471"
+sha512 = "121d0a87bdc9b4bd780a542b3efb74e6d9c972e8c537bde0bb471e06e2d9ca250a30f586d6d94c130c4b4664f9698afa452cc9650a13680c3dc1cf81318da676"
 
 [clocks]
 path = "../../clocks/wit-0.3.0-draft"
 sha256 = "a8702c42e23c22a458207d0efa38cc1b64c8c6299b0e3152aa84327a7c1c952b"
 sha512 = "da69a5d498b6afe0facf77ec3d21f6e8a2a4d4661ebfec310a2ce6f943cb01f92131a746765648febf96563ddac788e9f218941d3db2b905f3746dc8e05cf54d"
 
 [filesystem]
+path = "../../filesystem/wit-0.3.0-draft"
 sha256 = "d9db43c43b4e09899a9e54c76544eef17439fb42e2f730ed96d40eac994b0dfd"
 sha512 = "3b7a1bef322ba36b1e9df768d740e4238f58d3c15d3e4c51fe899b93cf1e6641a79b5a8665ae71d38a80e1e0f852b30b023ecf318f4cbeacb36dd1ae0ac7e37b"
 
 [random]
+path = "../../random/wit-0.3.0-draft"
 sha256 = "d44de4e427505fdfd584a23479dba5899ad80aa8e174dc0528df840db8ae9a43"
 sha512 = "6b08b32a197aee74076d0cdca6a09f78da9040eedd9ab3f64e5f14901ad5a0c5bbc592ad46a0d575dc6705249b3e10a413e09835616f753788aa598af605c776"
 
 [sockets]
+path = "../../sockets/wit-0.3.0-draft"
 sha256 = "ee64b45d3826b6ff2cd27f6ac24fe23c41e65ba4d155294671dc7d0a0b47ddfe"
 sha512 = "dd797ab47b899aee52799f797497fa286f5e217307e8a451a7ba89bd05b7b9bfe2a6e0cf39c0e609ed4c76ed102487adff6e73156340f14baf70a9cc9e48ecbc"

proposals/http/wit-0.3.0-draft/deps.toml

@@ -1,2 +1,5 @@
 cli = "../../cli/wit-0.3.0-draft"
 clocks = "../../clocks/wit-0.3.0-draft"
+filesystem = "../../filesystem/wit-0.3.0-draft"
+random = "../../random/wit-0.3.0-draft"
+sockets = "../../sockets/wit-0.3.0-draft"

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

@@ -31,6 +31,38 @@ world service {
   ///
   /// This may also be used to receive synthesized or forwarded requests from
   /// another component.
+  ///
+  /// # Concurrent instance reuse
+  ///
+  /// Hosts may concurrently invoke this `handler` interface multiple times,
+  /// even when previous requests have yet to finish processing. This means that
+  /// the guest, if it becomes idle while being blocked on I/O, may be required
+  /// to service multiple requests at the same time. Guests can opt-out of
+  /// this behavior with component-model backpressure to avoid sending more
+  /// requests to this instance while a previous one is being processed,
+  /// however.
+  ///
+  /// In some contexts, correct attribution of resource usage and I/O operations
+  /// is an important requirement. For example, correct implementation of the
+  /// CDN-Loop header in the context of a proxy server requires that outgoing
+  /// HTTP requests can be attributed to the incoming HTTP request that induced
+  /// them.
+  ///
+  /// Hosts with this requirement must associate work happening on the same
+  /// component model task that the `handler` was originally invoked on with the
+  /// same incoming HTTP request.
+  ///
+  /// Conversely, guests should ensure that calls to imported interfaces happen on
+  /// the same component model task that the `handler` was originally invoked
+  /// on. Guest runtime implementations that do not provide this guarantee are
+  /// encouraged to opt-out of concurrent reuse through the component model's
+  /// backpressure mechanisms.
+  ///
+  /// Note that hosts can't rely on this guarantee being upheld by all guests,
+  /// and shouldn't treat it as part of their security model. Instead, the
+  /// combination of the above host and guest requirements enable hosts to
+  /// enforce correctness properties on behalf of the overall system a guest is
+  /// part of.
   export handler;
 }