Update types.wit with some documentation improvements.

[brendandburns]

Ref #24

cc @lukewagner

[lukewagner]

Makes sense to me. I'll wait a bit for more feedback before merging, though.

[eduardomourar]

Wouldn't the same apply to trailers and headers? Those are also dependent resources that have their lifetime bound to the parent.

[lukewagner]

Good point, I think these are also child resources.

[brendandburns]

I'm less clear that a header is a child resource (or should be a child resource). The reason for this is that the stream of bytes is inherently tied to the TCP connection, but the headers are an in-memory hash-map that has been allocated separately.

In particular, in the case of an outgoing request, the headers are definitively allocated ahead of time and passed into the request by new-fields and then passing that object to new-outgoing-request

So unless new-outgoing-request takes ownership of the fields resource (which is a little wonky imho), the lifetime of the fields/headers is not tied to a request at all.

[lukewagner]

That's a good point and I spent some time wrestling with the same question. I think there are two additional reasons to suggest that, while the allocations are separate, making headers a child resource of the request/response makes sense:

1. From a performance perspective, when a request is passed to outgoing-handler.handle or a response is passed to set-response-outparam, it would be useful if the host could reliably take ownership of the headers memory so that the host can modify and free the headers as needed without having to keep an original copy in case the guest held onto a reference and accessed the headers in the future. In particular, one scenario that seems likely to happen in a GC language context is that the guest first accesses the headers, creating a GC object wrapper that owns the handle, and then the guest sends off the request/response, but the GC hasn't run yet to finalize the wrapper and drop the handle, so the host is forced to unnecessarily maintain an original copy.
2. From a composability perspective, if I chain two components together as middleware proxies (which seems like it will be a popular application of the http proxy world): are components allowed to hold onto headers when passing on a request/request to the next component? If yes, then simply mutating headers for a request that you currently own may possibly break other components in unpredictable ways, so it seems like the answer should be no (or else noone can mutate headers without conservatively making a clone first), which returning a child handle ensures.

[brendandburns]

@lukewagner

Given the additional docs on headers and trailers, I think that this is ready to merge specifically about streams.

[brendandburns]

@lukewagner sorry for the delay, added your suggestion. Thanks!

[lukewagner]

Thanks!