`HttpApiSchema` streams: declare every media type a stream can be sent as

クローズ
  • 何か問題がありますか？
#9,909 コメント 0 件 リアクション 0 件 担当者 1 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

@effect-bot がすでに取り組んでいます。

2026年10月25日 から。

  • #9941 @effect-bot による — マージ済み

評価

この issue はまだ評価されていません。

説明

docker-made-me-do-it enhancement

Problem

Some APIs send one stream under one of several media types, depending on the resource or the API version:

  • Docker's container logs answer 200 with application/vnd.docker.raw-stream when the container has a TTY, and with application/vnd.docker.multiplexed-stream otherwise.
  • Docker's GET /events is NDJSON sent as application/json up to API 1.51, and as application/jsonl from API 1.52 (measured on Docker 29).

OpenAPI describes this directly: a response's content maps each media type to its schema, and Docker's own API document lists both stream types under the logs' 200. A stream schema has exactly one contentType, though. So the generated OpenAPI document lists one media type the API may not send. For logs, declared as StreamUint8Array, it lists application/octet-stream, which the API never sends:

HttpApiEndpoint.get("logs", "/containers/:id/logs", {
  params: { id: Schema.String },
  success: HttpApiSchema.WithHeaders(HttpApiSchema.StreamUint8Array(), {
    "content-type": Schema.Literals([
      "application/vnd.docker.raw-stream",
      "application/vnd.docker.multiplexed-stream"
    ])
  })
})
// OpenAPI: 200 → content: { "application/octet-stream": … }

Declaring two stream successes instead isn't allowed ("Multiple streaming success responses are not supported", HttpApiEndpoint.ts L1403), and would need a way for a handler to pick one.

Proposal

Let StreamUint8Array and StreamNdjson take a list of media types:

success: HttpApiSchema.WithHeaders(
  HttpApiSchema.StreamUint8Array({
    contentType: ["application/vnd.docker.raw-stream", "application/vnd.docker.multiplexed-stream"]
  }),
  {
    "content-type": Schema.Literals(["application/vnd.docker.raw-stream", "application/vnd.docker.multiplexed-stream"])
  }
)

HttpApiSchema.StreamNdjson({ schema: EventMessage, contentType: ["application/jsonl", "application/json"] })
  • OpenAPI: each media type is listed under the status, with the same stream schema.
  • Client: unchanged. A status with one stream alternative is decoded whatever its Content-Type today, so any of the listed types is read the same way.
  • Server: the first media type is the default. A handler that sets a content-type declared with WithHeaders sends that one. This already works today: a handler's header replaces the stream's default Content-Type (tested with NodeHttpServer).
  • Payloads: a streaming request payload with several media types accepts any of them.

It's still one stream per status, so there's no new handler API and no union of stream types.

Scope

In scope: StreamUint8Array and StreamNdjson, as successes and as payloads.

Out of scope: StreamSse (always text/event-stream), and several stream schemas for one status.

Open questions

  • Should the server check that a handler's content-type is one of the listed types, or leave that to the declared header's schema?
主要言語
TypeScript
スター
16.7k
フォーク
808
平均マージ
11時間 3分
マージ済み PR（30日）
840

環境構築

このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

Effect-TS/effect のほかの issue

Effect-TS/effect の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。