Add get-* prefix to getters

[badeend]

As proposed in the last WASI meeting, this PR prefixes the following property-like methods with get-:

• request.method
• request.path-with-query
• request.scheme
• request.authority
• request-options.connect-timeout
• request-options.first-byte-timeout
• request-options.between-bytes-timeout
• response.status-code

I don't foresee any trouble with emitting these as properties in source languages.

---

However, the interface also contains:

• fields.entries
• request.options
• request.headers & response.headers
• request.body & response.body

I haven't prefixed these yet. Their names are standalone nouns so my OOP brain wants these to follow the property conventions too. E.g., I'd expect a Java binding generator to produce getEntries, getOptions, getHeaders & getBody.
But using the property convention/syntax generally comes with the implicit assumption that accessing it is cheap, idempotent and/or side-effect free. That's not the case here. For example, the following snippet would normally be idiomatic JavaScript code:

var host = request.headers.entries["Host"];
var forwardedFor = request.headers.entries["X-Forwarded-For"];

but actually, this creates two new owned fields handles that are never disposed of. And all the entries are copied over fully twice as well. So this seemingly fine code is actually inefficient & leaking resources.

I'm ignoring the existence of the fields.get method to get the point across :)

---

Ideas on this are welcome. Concretely I want to know how to proceed:

• Should we prefix those methods with get-* anyway and leave it for future selves to figure out?
• Should we assume these methods will never become properties and continue this PR as-is?

@lukewagner Thoughts?

[tschneidereit]

This might be too magical, but one possibility would be to emit bindings that cache returned resource handles for simple get- prefixed methods. Simple in this case could mean that the method either returns a handle directly, or maybe also option<handle-type>, but not complex things like result<..>, such as body.

This puts a decent amount of burden on bindings implementers, but that seems maybe manageable?

[lukewagner]

@badeend Great question!

I agree with the rule that getters shouldn't be effectful but I don't think returning an owned handle constitutes an "effect" since theoretically owned handles are just "linear" values. I also like @tschneidereit's idea about [get] annotations telling bindings generators that, under some circumstances, its valid to cache the returned value. So based on this, I think it's a good idea to get--prefix headers and options.

fields.entries is an interesting case because, as you said, it's likely a footgun to make it look like a property if every use is an O(n) copy. Even if we consider bindgen'd property caching, I think we still have problems in languages that bind list to a mutable array. I like the general naming principle of "no nouns in method names (only (future) getter/setter names)", so maybe we could rename this to copy-all (or something like that) to better communicate the cost model?

Lastly, body is quite effectful, so it seems like it also shouldn't be a property. Applying the same "no nouns in method names" rule, perhaps we should rename body to something with a verb like consume or consume-body?

[badeend]

I've updated the PR with your suggestions:

• entries -> fields.copy-all
• options -> get-options
• headers -> get-headers
• body -> consume-body

It is not clear to me yet how the bindings can reliably cache properties without the risk of returning stale information. That being said, this is not a problem we need to solve right now, and I do agree that ideally options & headers should be properties.

[lukewagner]

@badeend Thanks, lgtm!

It is not clear to me yet how the bindings can reliably cache properties without the risk of returning stale information. That being said, this is not a problem we need to solve right now, and I do agree that ideally options & headers should be properties.

Incidentally, I was just reading what Firefox does for property caching in WebIDL: there is a [Cached] annotation that must be accompanied with either Pure or Constant which tells the bindings generator and JIT it can cache the return value (in an internal slot of the JS object wrapping the browser's C++ object) (clearing if the setter is called). Extending to a component setting, we'd also have to clear if there is a setter and a borrowed handle was passed to an import (which the bindings generator could see and perform automatically). Anyhow, as you said, this can be a later discussion (and maybe caching is too magical?).