conceptadev / conceptadev/rockets

feat(core): SSE and Range transport primitives for operationResource

Open
#52 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
TypeScript
Stars
1
Forks
2
Avg merge
2d 10h
Merged PRs (30d)
23

Description

## Summary

Add first-class **SSE** and **HTTP Range** support so long-lived / media streams are not forced into handwritten Nest controllers.

From the field report (#46): chat, video, and PDF domains stayed fully app-owned in both rebuilds because Rockets has **zero** transport primitives beyond request/response JSON. OpenAPI can describe the route and DTOs; framing (SSE event stream, `Accept-Ranges` / partial content) cannot be fully expressed there — but the **route, auth, ACL, and input validation** still can live on `operationResource`.

## Motivation

- ~2/3 of a real product surface is not owned-entity CRUD (#46).
- `operationResource` (#43 / #50) covers RPC-style JSON; streaming/binary is the next compression gap.
- Without this, Stargate micro-apps keep escaping to raw Nest for the highest-value UX paths.

## Proposal (sketch)

- Extend `operationResource` (or a sibling op kind) with explicit output modes, e.g. `output: 'sse' | 'range' | schema` (exact API TBD).
- Keep Zod `input` validation + auth/`acl` (#51) on the same bundle.
- Document what OpenAPI can and cannot represent; ship a sample (chat-style SSE and/or file Range).

## Non-goals

- Full OpenAPI fidelity for SSE event schemas.
- Replacing app-owned stream business logic (tokens, backpressure policy) — only the Nest transport wiring.

## Acceptance criteria

- [ ] Documented authoring for at least one SSE operation and one Range/partial response path.
- [ ] Auth / public / ACL behave like other operations (boot fail-fast where applicable).
- [ ] E2E covers happy path + unauthenticated rejection.
- [ ] Sample or fixture in-repo; `CONFIGURATION.md` updated.

## References

- Parent: #46 (Transport primitives: SSE and Range)
- Related: #43 / #50 (`operationResource`), #51 (ACL first-class)

Contributor guide

Open the contributing guide

Research direction

Start by reading the operationResource work in #43/#50, ACL expectations in #51, and the field report in #46. Define and document authoring for one SSE operation and one Range path, preserve auth/public/ACL behavior, add happy-path and unauthenticated E2E coverage plus an in-repo sample or fixture, and update CONFIGURATION.md.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.