[hsjs/http-specs] Unspeakable status code property causes problems for HSJS

[witemple-msft]

In http-specs/specs/response/status-code-range we use _ to denote the status code of responses. This is a problem for HSJS because a property named _ is treated as "unspeakable" because it contains no text segments, only characters that it considers "separators." We produce the following error by design:

node_modules/@typespec/http-specs/specs/response/status-code-range/main.tsp:74:3 - error @typespec/http-server-js/unspeakable-status-code: Status code property '_' is unspeakable and does not have an exact value. Provide an exact status code value or rename the property.
> 74 |   _: int32;
     |   ^

These are status code ranges:

  @minValue(400)
  @maxValue(499)
  @statusCode
  _: int32;

HSJS relies on the presence of the status code property, because otherwise it does not know what status code to return, and if it's unspeakable, we drop it from the representation of the model, creating a conflict. I chose to remove these _ properties from models because I thought it was a bad experience for a user to have to return something like { _: 200, data } for a successful response, when the only options are { data } or an error.

We have some options:

1. Put a name on this status code property (code) and live with the HSJS limitation that operative properties like status code have to be named.
2. Don't drop "unspeakable" properties in HSJS, but this has consequences for developers who will have to specify these "pure metadata" properties that have strange names.
3. Only drop "unspeakable" properties if they are literal-valued, which would a breakage point if someone changes a status code property from @statusCode _: 400 to @minValue(400) @maxvalue(499) _: int32.
4. Change the HSJS business logic strategy fundamentally so that metadata is extracted into a separate strongly-typed object from the body data, and require the developer to return both the metadata object and the body data object separately in a wrapped data structure.

[markcowl]

A few thoughts:

• Usage of the _ as a property name for status code is widespread, outlawing this would be a significant breaking change
• I believe the intention of this is to represent a property that is intrinsic to the model, but not visible to the client except as metadata
• Using this property without value constraints has no valid usage that I can discern
• Using a union or enum of values or a single value with an unspeakable property name seems uncontroversially fine
  • We should consider whether open int unions should also be accepted
• I would argue that a set of value constraints provided by decorator also make sense
  • In C-Sharp we translate this as an internal property that can only be set at construction time
• Arguably, even @error communicates a value constraint of 400 -> 599 in Http responses
  • In C-Sharp we treat this the same way we treat value decorator constraints
• Having an unspeakable property marked as @statusCode without any kind of value constraint seems like it is a bit dubious. By 'dubious' I mean that emitters may emit a warning or error indicating that they don't know how to process such a property.

There was, originally, some thought of allowing string templates, like 4xx, 5xx as values, we should consider whether this makes sense as well.

[witemple-msft]

Some points for discussion as well:

• Eliminating literal-valued properties seems fine in general, since they can only have one value and we can just "fill them in", but for TypeScript specifically the presence of these properties is important for actually discriminating between union variants.
• There's no real reason we can't have a property named _ in TypeScript. It just isn't very nice to an author to actually state it in an object literal e.g. return { _: 200 } kind of sucks for an author compared to { statusCode: 200 } because there's no indication in TypeScript of what _ actually means. An option we have is to only eliminate these "unspeakable" properties if they are literal-valued.
• We don't do anything good for other properties that have "unspeakable" names but aren't metadata props, we just haven't hit this case because there aren't any specs like that.

the intention of this is to represent a property that is intrinsic to the model, but not visible to the client except as metadata

This is true from the client's perspective, but from the server's perspective it's a core part of the response information. If it was fixed and literal-valued, it wouldn't be a problem, but because it's operative and variable we have to provide some location for the business logic to put the status code. We could possibly wrap responses where the metadata properties are removed in a higher-level metadata envelope, but I wouldn't want to do this for all types (which could have deeply-nested metadata), only types where it's mandatory. Another option is to try to rename the properties.

Example: model Foo { @minValue(400) @maxValue(499) @statusCode _: uint16, ... } author returns { fooStatusCode: 404, ... }.

The main concern I have with this is the same concern I have with all other renamings and "smarts": eventually the names conflict with something else in the model, so the logic has to be somewhat smart about not conflicting, and then because it's smart about not conflicting it becomes unstable and introduces points where it can break, like this:

model Foo {
  @statusCode _: uint16;
}

// Becomes

model Foo {
  @statusCode _: uint16;
  fooStatusCode?: uint16;
}

It's not likely, but it can happen.