Skip to content

Update types.wit with some documentation improvements. #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jul 28, 2023
Merged

Update types.wit with some documentation improvements. #26

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cf59141
Update types.wit with some documentation improvements.
brendandburns Apr 18, 2023
dc0527c
Merge branch 'main' into main
brendandburns Jun 27, 2023
0d75f24
Update types.wit
brendandburns Jun 27, 2023
5860cd2
Update wit/types.wit
brendandburns Jul 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions wit/types.wit
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,12 @@ interface types {
// are shared with the request, with all mutations visible to all uses.
// Components MUST avoid updating `headers` and `trailers` after passing a
// request that points to them to the outside world.
// The streams returned by `consume` and `write` are owned by the request and
Copy link
Contributor

@eduardomourar eduardomourar Apr 19, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point, I think these are also child resources.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

// response objects. The streams are destroyed when the request/response is
// dropped, thus a client MUST drop any handle referring to a request/response stream
// before dropping the request/response or passing ownership of the request/response
// to the outside world. The caller can also call drop on the stream before the
// request/response is dropped if they want to release resources earlier.
type incoming-request = u32
type outgoing-request = u32
drop-incoming-request: func(request: incoming-request)
Expand Down