search

WebAssembly / wasi-http

Other
149 stars 24 forks source link

Terminology: "field key" vs "field name" #107

Closed yoshuawuyts closed 2 months ago

yoshuawuyts commented 8 months ago

Preface

Hi hi, I've been working with wasi:http a fair bit recently and have been enjoying it a lot. Thank you for that! Given we're currently still in a preview and we intend to make breaking changes, I'm going to interpret that as: "Now is the time to give feedback on APIs, however small, because we can still make changes if we want to."

"field-key" vs "field-name"

Something small which stood out to me was the usage of the name field-key to refer to the name of a field. I was expecting this to be called field-name instead. The reason for this is that in RFC 9112: HTTP Semantics (2023), each field is described as being composed of a field-name and a field-value:

field-line = field-name ":" OWS field-value OWS

There is no mention of field-key anywhere in the RFC. The IANA Field Name Registry also refers to them as "fields", not "keys". I would like to propose we consider changing our terminology from "field-key" to "field-name".

Navigating deprecations within a WASI release family

If we assume for a second this is a change we want to make, that opens up the question of how we would want to navigate a change like this. WASI 0.2 was just ratified, and WASI 0.3 is likely still a while out. And if we were to implement for example https://github.com/WebAssembly/wasi-http/issues/94 (add a fields.keys method), we'd be doubling-down on the existing terminology instead of the terminology we would prefer.

This is a question which is generally broader than this issue, but I think it would be good if we could establish a process for making changes like these within a minor WASI version. An example flow I'm thinking of is:

  1. Introduce a new alias type field-name = field-key (or alias it directly to string if that's legal in our projections).
  2. Change all APIs which take field-key to take a field-name instead.
  3. Mark field-key as deprecated for WASI 0.2.
  4. When we release WASI 0.3 we remove field-key from the API surface.

If we were able to do something like this we could release the changes as part of a WASI 0.2.x release without breaking any existing code. And then in a WASI 0.3.0 release we could finalize the changes by actually removing deprecated APIs. I don't know whether we already have a way to support deprecating APIs in WIT; but if we don't that may be a good thing to consider adding.

lukewagner commented 8 months ago

I think you're right that field-name is the correct RFC 9110-aligned type-name to use, and also the deprecation path you described makes sense and I think fits into the semver scheme we've discussed for for 0.2/0.3.

yoshuawuyts commented 8 months ago

Oh oops, realizing now that I linked to RFC 9112, I indeed meant to link to RFC 9110. I'm glad both the proposed change and the way to implement it make sense, and thank you for the correction!

I think what we depend on then to implement this change is to have some notation to mark APIs as deprecated. Which I think may in turn depend on some way to annotate APIs with metadata?