Skip to content

Add get-* prefix to getters #170

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.

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

Open
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

badeend
Copy link

@badeend badeend commented Jul 5, 2025

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
Copy link
Member

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
Copy link
Member

@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
Copy link
Author

badeend commented Jul 10, 2025

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants