Validate SSEStream union parameter has @events decorator (#8951)

Copilot · baywet · timotheeguerin · web-flow · commit 8fde19b9bdbc · 2025-11-10T11:51:21.000Z
SSEStream accepted unions without `@events` decorator, generating incorrect schemas. This validation ensures proper event stream definitions at compile time. ## Changes - **Added validation** in `packages/sse/src/validate.ts`: - Traverse all models during validation phase - Check streams with `text/event-stream` content-type - Verify streamOf type is a union with `@events` decorator - Report `sse-stream-union-not-events` diagnostic on failure - **Added diagnostic** `sse-stream-union-not-events` in `packages/sse/src/lib.ts` - **Added tests** covering invalid/valid SSEStream usage and HttpStream with SSE content-type ## Example This now fails validation: ```typespec union BasicUnion { userconnect: UserConnect, } op subscribe(): SSEStream<BasicUnion>; // Error: union must have @events ``` This compiles: ```typespec @events union BasicUnion { userconnect: UserConnect, } op subscribe(): SSEStream<BasicUnion>; // OK ``` Fixes #8888 > [!WARNING] > > <details> > <summary>Firewall rules blocked me from connecting to one or more addresses (expand for details)</summary> > > #### I tried to connect to the following addresses, but was blocked by firewall rules: > > - `telemetry.astro.build` > - Triggering command: `node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build` (dns block) > > If you need me to access, download, or install something from one of these locations, you can either: > > - Configure [Actions setup steps](https://gh.io/copilot/actions-setup-steps) to set up my environment, which run before the firewall is enabled > - Add the appropriate URLs or hosts to the custom allowlist in this repository's [Copilot coding agent settings](https://github.com/microsoft/typespec/settings/copilot/coding_agent) (admins only) > > </details>  <details> <summary>Original prompt</summary> > > ---- > > *This section details on the original issue you should resolve* > > <issue_title>SSEStream should NOT accept a union model without the events decorator</issue_title> > <issue_description>This definition > > ```ts > import "@typespec/streams"; > import "@typespec/sse"; > import "@typespec/events"; > > using SSE; > > > model UserConnect { > name: string; > } > > union BasicUnion { > userconnect: UserConnect, > } > op subscribe(): SSEStream<BasicUnion>; > ``` > > Builds but generates the wrong schema (instead of item schema with all the right properties) > > ```ts > import "@typespec/streams"; > import "@typespec/sse"; > import "@typespec/events"; > > using SSE; > > > model UserConnect { > name: string; > } > > @TypeSpec.Events.events > union BasicUnion { > userconnect: UserConnect, > } > op subscribe(): SSEStream<BasicUnion>; > ``` > > Generates the correct itemSchema. > > Ultimately this is not a responsibility of the OpenAPI3 emitter to check for this, but rather the SSE library should fail building when being passed a union model as a generic type parameter value when that union model DOES NOT have the required decorator. > This will be handled in a separate issue/pull request > > _Originally posted by @baywet in #8888 (comment) > </issue_description> > > <agent_instructions>before committing any file, run `npx prettier --write filePath` to ensure they are formatted correctly. > once you're done with the changes, run `npx @chronus/chronus add` and select bugfix to add an entry in the changelog</agent_instructions> > > ## Comments on the Issue (you are @copilot in this section) > > <comments> > <comment_new><author>@timotheeguerin</author><body> > Also note that as `SSEStream` is just defined as `HttpStream<Type, "text/event-stream">;` > > that also might need to validate when `text/event-stream` is used</body></comment_new> > </comments> > </details> - Fixes #8950  --- 💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs. --------- Signed-off-by: Vincent Biret <vibiret@microsoft.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: baywet <7905502+baywet@users.noreply.github.com> Co-authored-by: Vincent Biret <vibiret@microsoft.com> Co-authored-by: Timothee Guerin <tiguerin@microsoft.com>
diff --git a/.chronus/changes/copilot-fix-sse-stream-union-model-2025-10-7-15-54-51.md b/.chronus/changes/copilot-fix-sse-stream-union-model-2025-10-7-15-54-51.md
@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/sse"
+---
+
+Validate SSE streams are defined as events unions
diff --git a/packages/sse/src/lib.ts b/packages/sse/src/lib.ts
@@ -7,7 +7,14 @@ export const $lib = createTypeSpecLibrary({
       severity: "error",
       messages: {
         default:
-          "A field marked as '@terminalEvent' must be a member of a type decorated with '@TpeSpec.Events.events'.",
+          "A field marked as '@terminalEvent' must be a member of a type decorated with '@TypeSpec.Events.events'.",
+      },
+    },
+    "sse-stream-union-not-events": {
+      severity: "error",
+      messages: {
+        default:
+          "SSEStream type parameter must be a union decorated with '@TypeSpec.Events.events'.",
       },
     },
   },
diff --git a/packages/sse/src/validate.ts b/packages/sse/src/validate.ts
@@ -1,9 +1,13 @@
-import type { Program, UnionVariant } from "@typespec/compiler";
+import type { Model, Program, UnionVariant } from "@typespec/compiler";
+import { navigateProgram } from "@typespec/compiler";
 import { isEvents } from "@typespec/events";
+import { getContentTypes } from "@typespec/http";
+import { getStreamOf } from "@typespec/streams";
 import { reportDiagnostic, SSEStateKeys } from "./lib.js";
 
 export function $onValidate(program: Program) {
   checkForIncorrectlyAssignedTerminalEvents(program);
+  checkForSSEStreamWithoutEventsDecorator(program);
 }
 
 function checkForIncorrectlyAssignedTerminalEvents(program: Program) {
@@ -24,3 +28,49 @@ export function validateTerminalEvent(program: Program, target: UnionVariant) {
     });
   }
 }
+
+function checkForSSEStreamWithoutEventsDecorator(program: Program) {
+  navigateProgram(program, {
+    model: (model) => {
+      validateSSEStream(program, model);
+    },
+  });
+}
+
+function validateSSEStream(program: Program, model: Model) {
+  // Check if this model is a stream
+  const streamOf = getStreamOf(program, model);
+  if (!streamOf) {
+    return;
+  }
+
+  // Check if the stream has the text/event-stream content type
+  const contentTypeProperty = model.properties.get("contentType");
+  if (!contentTypeProperty) {
+    return;
+  }
+
+  const [contentTypes] = getContentTypes(contentTypeProperty);
+  const isSSEStream = contentTypes.includes("text/event-stream");
+
+  if (!isSSEStream) {
+    return;
+  }
+
+  // The stream is an SSEStream, validate that streamOf is a union with @events
+  if (streamOf.kind !== "Union") {
+    // If streamOf is not a union, it's invalid for SSE streams
+    reportDiagnostic(program, {
+      code: "sse-stream-union-not-events",
+      target: model,
+    });
+    return;
+  }
+
+  if (!isEvents(program, streamOf)) {
+    reportDiagnostic(program, {
+      code: "sse-stream-union-not-events",
+      target: model,
+    });
+  }
+}
diff --git a/packages/sse/test/models.test.ts b/packages/sse/test/models.test.ts
@@ -1,4 +1,4 @@
-import { t } from "@typespec/compiler/testing";
+import { expectDiagnostics, t } from "@typespec/compiler/testing";
 import { getContentTypes } from "@typespec/http";
 import { getStreamOf } from "@typespec/streams";
 import { describe, expect, it } from "vitest";
@@ -23,4 +23,89 @@ describe("SSEStream", () => {
       name: "string",
     });
   });
+
+  it("should fail when union is not decorated with @events", async () => {
+    const diagnostics = await Tester.diagnose(`
+      model UserConnect {
+        name: string;
+      }
+
+      union BasicUnion {
+        userconnect: UserConnect,
+      }
+
+      op subscribe(): SSEStream<BasicUnion>;
+    `);
+
+    expectDiagnostics(diagnostics, {
+      code: "@typespec/sse/sse-stream-union-not-events",
+      severity: "error",
+    });
+  });
+
+  it("should pass when union is decorated with @events", async () => {
+    const diagnostics = await Tester.diagnose(`
+      model UserConnect {
+        name: string;
+      }
+
+      @events
+      union BasicUnion {
+        userconnect: UserConnect,
+      }
+
+      op subscribe(): SSEStream<BasicUnion>;
+    `);
+
+    expectDiagnostics(diagnostics, []);
+  });
+
+  it("should fail when HttpStream with text/event-stream is used without @events", async () => {
+    const diagnostics = await Tester.diagnose(`
+      model UserConnect {
+        name: string;
+      }
+
+      union BasicUnion {
+        userconnect: UserConnect,
+      }
+
+      model MyStream is Http.Streams.HttpStream<BasicUnion, "text/event-stream">;
+    `);
+
+    expectDiagnostics(diagnostics, {
+      code: "@typespec/sse/sse-stream-union-not-events",
+      severity: "error",
+    });
+  });
+
+  it("should fail when HttpStream with text/event-stream is a model", async () => {
+    const diagnostics = await Tester.diagnose(`
+      model UserConnect {
+        name: string;
+      }
+
+      model MyStream is Http.Streams.HttpStream<UserConnect, "text/event-stream">;
+    `);
+
+    expectDiagnostics(diagnostics, {
+      code: "@typespec/sse/sse-stream-union-not-events",
+      severity: "error",
+    });
+  });
+
+  it("should fail when SSEStream is used with a model", async () => {
+    const diagnostics = await Tester.diagnose(`
+      model UserConnect {
+        name: string;
+      }
+
+      model MyStream is SSEStream<UserConnect>;
+    `);
+
+    expectDiagnostics(diagnostics, {
+      code: "invalid-argument",
+      severity: "error",
+    });
+  });
 });
