Skip to content

feat(compilers/openapi): populate the operation streaming fields - #352

Open
OmarAlJarrah wants to merge 1 commit into
mainfrom
feat/openapi-streaming-media
Open

feat(compilers/openapi): populate the operation streaming fields#352
OmarAlJarrah wants to merge 1 commit into
mainfrom
feat/openapi-streaming-media

Conversation

@OmarAlJarrah

Copy link
Copy Markdown
Member

Summary

Operation.Streaming, Operation.RequestStream and Operation.ResponseStream were written by no
compiler at any version. An SSE or NDJSON API declares what it does by naming a media type, and the
media type was copied to Content.MediaType and never read; a 3.2 itemSchema set Content.Item
and stopped there. Compiling either shape produced streaming: null with no diagnostic, so nothing
downstream could tell a stream from an ordinary body.

This adds the reading, in two halves that are deliberately not the same kind of fact:

  • A 3.2 itemSchema declares the stream. The keyword states that the body is a sequence of
    items, so the operation streams and the declared item schema is the element type. Nothing is
    guessed, so no heuristic marker is stamped.
  • A media type implies one. text/event-stream, application/x-ndjson and application/jsonl
    are read as frame formats through a new Options.StreamingMedia policy — default on, replaceable,
    and switchable off — with Provenance.Inferred naming the heuristic. That is architecture
    principle 6: the list is a default, not a standard, and a caller who wants only what a document
    declares turns it off. Matching ignores case and media-type parameters.

For a frame format the schema under the media type describes one frame rather than the whole body,
which is the opposite of how an ordinary content is read; StreamDetail.Events is what says so.
Where a direction offers several streaming contents the direction still streams but the element type
is left unnamed, with an info diagnostic: StreamDetail holds one Events per direction while the
payload keeps every media type, so electing one of them would be the primary-content selection a
compiler must not make.

Two notes on the issue as filed. Its acceptance item about an itemSchema "not double-applying"
assumed an existing 3.2 writer — there was none, so the gap was wider than reported rather than
narrower, and the two paths here cannot both fire because a declaration at a content wins over the
reading of its media type. And Provenance.Inferred holds a single string that path-prefix grouping
already used, so an operation reached by both heuristics now lists both rather than losing one.

Merge ordering: #345 also rewrites testdata/conformance/openapi/unwitnessed.golden.txt, and #341
adds DecodeOptions to the compiler contract. Whichever of the three lands first, the others rebase;
once #341 is in, StreamingMedia should gain textual option names there so the CLI's -opt path can
reach it.

Test plan

  • New corpus rows streaming-media-30 and streaming-media-31 cover a 3.0 media-type-only stream, a
    bidirectional operation, a charset parameter on the media type, and the several-contents refusal.
  • unwitnessed.golden.txt loses five entries — Operation.Streaming, Operation.RequestStream,
    Operation.ResponseStream, StreamDetail.Events and Provenance.Inferred, the last of which no
    corpus spec witnessed at all before.
  • sequential-media now records the stream its itemSchema declares; its assertion pins that it is
    declared rather than inferred.
  • A two-order test compiles the two streaming media types either way round and requires the streaming
    fields to agree, which is what an implementation electing the first candidate would fail.
  • Policy tests cover the off switch, a caller's list replacing the defaults rather than extending
    them, and the exported default list being the one the lowering applies.
  • Full gate: gofmt, vet, golangci-lint, build, and the 100% coverage gate.

Closes #250

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

openapi: SSE and NDJSON streaming is invisible below OpenAPI 3.2

1 participant