feat(spec,middleware): CloudEvents binary content mode

[ucekmez]

Summary

PR 18 of a stacked series. Base is #109. Not for merge without review.

EEP delivered only in CloudEvents structured mode: the whole envelope as one JSON document. Binary mode — context attributes as protocol metadata, body carrying only data — was not offered, so every subscriber parsed a full envelope to decide whether it wanted the payload.

First, a correction to my own audit

I reported this as EEP's largest wire optimisation at "62% smaller frames". That number was computed by dropping source, time, specversion and datacontenttype rather than relocating them — not a like-for-like comparison. Re-derived honestly against the spec's own §4.2 example:

	bytes	vs structured
SSE structured (today)	354	—
SSE binary, lossless	286	19% smaller
Webhook structured	315	—
Webhook binary (HTTP/1.1)	274	13% smaller
Webhook body alone	283 → 56	80% smaller

So: 19% and 13%, not 62%. Still worth having — the body shrinks ~80%, HTTP/2 HPACK indexes the ce-* names and non-varying values across deliveries on a connection, and a subscriber can route on headers without parsing the body — but it is not the headline optimisation I claimed.

§5.2.1 says this plainly and points publishers optimising bytes at conditional requests (#101), compression (#101) and subscription filters (#107) first: those remove whole responses and whole deliveries rather than shrinking them. I'd rather the spec be honest about the ordering than oversell a mode.

This also resolves the CloudEvents naming problem

CloudEvents excludes the underscore from context attribute names, so ce-eep_version is not a legal header — the divergence flagged in #96 and #100. §5.2.1 resolves it for the binary path: underscores are removed (eep_version → ce-eepversion). Structured mode keeps the underscored spelling that every deployed implementation emits, so nothing breaks. Whether to rename in structured mode too stays open for v1.0.

What changed

• delivery_format gains cloudevents/v1.0-binary; structured remains the default.
• SSE binary mode relocates only the two attributes SSE natively frames (id:, event:) and stops repeating them in the body. SSE has no per-event header channel for the rest, and inventing one would not be CloudEvents.
• Binary mode relocates attributes and MUST NOT drop them. An object-valued attribute has no header representation, so the renderer keeps it in the body rather than losing it — with a test asserting every attribute survives the mode change.
• Signing is unchanged: the signature covers the raw body bytes, so a binary-mode subscriber verifies exactly what it received without reassembling an envelope. Tested.

Scope

• Spec / schema only
• TypeScript package(s)
• Python package(s)
• Tests / CI
• Docs / examples

Checklist

• I read CONTRIBUTING.md and CODE_OF_CONDUCT.md.
• Tests added or updated where appropriate.
• Breaking change? No. Opt-in per subscription; structured stays the default and is byte-identical to before.
• Documentation updated for user-visible behavior.

Verification

Suite	Result
@eep-dev/middleware	250 passed (was 233)
tests/	199 passed
tests/cross-impl/	56 passed, 3 skipped
openapi-route-parity	✓
codegen-schema-types --check	no drift

Notes for reviewers

The "no attribute is lost" test is the one that matters. Binary mode is a relocation, and the failure mode is silently dropping something that has no header representation. The test iterates every attribute on the event and asserts it is present in either a header or the body.

SSE binary mode is specified but not implemented — the middleware's SSE handler emits a single connection-hint frame rather than a real event stream, so there is nothing to render events through yet. The spec text is what an implementor needs.

No Python middleware parity — flagging rather than skipping silently.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.