fix(http): use @bodyRoot in HttpStream to eliminate spurious metadata-ignored warnings

[n-sviridenko]

Thanks for creating such a lovely thing, that's something I was looking for for a while.

Problem

HttpStream defines @header contentType alongside @body body in the same model. This triggers the @typespec/http/metadata-ignored warning on every instantiation of HttpStream — including SSEStream from @typespec/sse:

node_modules/@typespec/http/lib/streams/main.tsp:22:11 - warning @typespec/http/metadata-ignored:
header property will be ignored as it is inside of a @body property. Use @bodyRoot instead if wanting to mix.
  occurred while instantiating template SSEStream<...>

This warning fires from library code that users cannot modify, making it impossible to use --warn-as-error without suppressing a warning they didn't cause.

Fix

Change @body body to @bodyRoot body in HttpStream. This is exactly what the warning message recommends, and it allows @header and body to coexist correctly.

Test plan

• Existing HTTP stream tests pass
• No @typespec/http/metadata-ignored warning when instantiating SSEStream

[n-sviridenko]

@microsoft-github-policy-service agree

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/http@10423

commit: 37700b7

[github-actions]

All changed packages have been documented.

• ✅ @typespec/http

Show changes

@typespec/http - fix ✏️

Fix HttpStream to use @bodyRoot instead of @body so that the @header contentType property is not silently ignored, eliminating spurious @typespec/http/metadata-ignored warnings on every SSEStream instantiation.

[timotheeguerin]

@n-sviridenko can you show a repro of what you are seeing, I am not sure this is a correct fix.

Just using the stream as it is doesn't emit the warning. the content type header doesn't conflict as its not underneath that body. Do you have another header maybe inside the type, is that on purpose?

[n-sviridenko]

Here's a minimal repro.

Versions

• @typespec/compiler: 1.11.0
• @typespec/http: 1.11.0
• @typespec/sse: 0.81.0

Minimal TypeSpec

import "@typespec/http";
import "@typespec/sse";

using TypeSpec.SSE;

union MyEvent {
  ping: { type: "ping" };
}

@route("/events")
interface Events {
  subscribe(): SSEStream<MyEvent>;
}

Warning produced

node_modules/@typespec/http/lib/streams/main.tsp:22:11 - warning @typespec/http/metadata-ignored:
header property will be ignored as it is inside of a @body property. Use @bodyRoot instead if wanting to mix.

  22 |   @header contentType: typeof ContentType;
     |           ^^^^^^^^^^^

  node_modules/@typespec/sse/lib/types.tsp:52:60 - occurred while instantiating template
  > 52 | model SSEStream<Type extends TypeSpec.Reflection.Union> is HttpStream<Type, "text/event-stream">;

  <your-file>.tsp:14:20 - occurred while instantiating template
  > 14 |   subscribe(): SSEStream<MyEvent>;

The warning fires from inside node_modules — code the user cannot modify — making --warn-as-error unusable in any project that uses SSEStream. The @header contentType is inside @body body in HttpStream at streams/main.tsp:22, which is exactly what this PR fixes by switching to @bodyRoot.

[timotheeguerin]

the repro you have above doesn't compile, with different errors. Fixing it with what is missing I still can't repro the issue so unsure how you are seeing this.

import "@typespec/http/streams";
import "@typespec/sse";
import "@typespec/events";

using Http;
using TypeSpec.SSE;

@TypeSpec.Events.events
union MyEvent {
  ping: {
    type: "ping",
  },
}

@route("/events")
interface Events {
  subscribe(): SSEStream<MyEvent>;
}

Using @bodyRoot here is wrong, it just would hide the actual problem/bug causing this warning. The type used here represent each item in a stream and it doesn't make sense that this would contain any http metadata attributes (like headers).