WASI-http needs a sequence diagram

There's a number of functions that allocate/return values (e.g. get a stream for a response body) and methods which dispose of those values (e.g. drop_output_stream).

It's not very clear from the documentation or from the method signatures what is legal and what is a a problem.

e.g. if I call:

let body_stream = types::incoming_response_consume(incoming_response)
    .map_err(|()| anyhow!("incoming response has no body stream"))?;
types::drop_incoming_response(incoming_response);

let mut body = Vec::new();
let mut eof = false;
while !eof {
    let (mut body_chunk, stream_ended) = streams::read(body_stream, u64::MAX)?;
    eof = stream_ended;
    body.append(&mut body_chunk);
}
streams::drop_input_stream(body_stream);

Note I dropped the response before I dropped the stream from the response, is that legal? Who owns the stream? Is it the caller or is it the response object?

Similarly, given the code:

let request =
    types::new_outgoing_request(method, path, query, Some(scheme), authority, headers);
let request_body = types::outgoing_request_write(request)
    .map_err(|_| anyhow!("outgoing request write failed"))?;
let mut body_cursor = 0;
while body_cursor < body.len() {
    let written =
        streams::write(request_body, &body[body_cursor..]).context("writing request body")?;
    body_cursor += written as usize;
}
streams::drop_output_stream(request_body);

let future_response = default_outgoing_http::handle(request, None);
types::drop_outgoing_request(request);

Note that I dropped the output stream before I sent the request, so that seems to imply that the request object owns the output stream.

Given the complexity of the various methods to acquire things like streams and responses and requests and all of the methods to drop them, it is very difficult to know the correct way to either call the code or implement the WIT interface. This means that clients will be confused, and different implementations will behave differently.

We need to either publish a set of acceptance tests that all implementations must be able to run successfully, and/or document the sequence of calls that are "expected" or "acceptable" so that we can have consistency.

Start by reviewing the WASI-http operations shown in the examples, including incoming_response_consume, drop_incoming_response, outgoing_request_write, handle, and the stream drop methods. Determine the ownership and permitted call sequences, then document them with sequence diagrams and/or define acceptance tests that implementations must pass.