Repeatable for DISTINCT names. The same name twice is refused at
register() — Headers.set overwrites, so the second declaration would
silently erase the first, and a multi-valued header (Set-Cookie, Vary)
wants ctx.response.appendHeader(...) through @Params(Ctx()) instead. Names
are
compared case-insensitively, per RFC 9110 §5.1.
The name and value are validated at register() by the runtime's own rule:
an invalid pair throws TypeError while the response headers are written,
which would answer 500 on every request to the route.
Cost note. Writing a header materialises the response's Headers object,
ending the fast path by which the common terminal shapes hand a
snapshot-local header init straight to the native Response constructor. A
bare @HttpCode route pays nothing — setting a status is an assignment that
touches no header state. This is the correct trade for a route that asked for
a header; it is stated here so the cost is visible at the declaration.
Deliberately NOT derived into the OpenAPI document: an OpenAPI response
header entry needs a schema and a description this declaration does not
carry, so deriving one would put an under-specified headers object into
every document that used the decorator.
Declares a fixed response header for a handler.
Repeatable for DISTINCT names. The same name twice is refused at
register()—Headers.setoverwrites, so the second declaration would silently erase the first, and a multi-valued header (Set-Cookie,Vary) wantsctx.response.appendHeader(...)through@Params(Ctx())instead. Names are compared case-insensitively, per RFC 9110 §5.1.The name and value are validated at
register()by the runtime's own rule: an invalid pair throwsTypeErrorwhile the response headers are written, which would answer500on every request to the route.Cost note. Writing a header materialises the response's
Headersobject, ending the fast path by which the common terminal shapes hand a snapshot-local header init straight to the nativeResponseconstructor. A bare@HttpCoderoute pays nothing — setting a status is an assignment that touches no header state. This is the correct trade for a route that asked for a header; it is stated here so the cost is visible at the declaration.Deliberately NOT derived into the OpenAPI document: an OpenAPI response header entry needs a schema and a description this declaration does not carry, so deriving one would put an under-specified
headersobject into every document that used the decorator.