docs(web): design gateway-backed web library - #749
Draft
behinddwalls wants to merge 4 commits into
Draft
behinddwalls wants to merge 4 commits into
behinddwalls wants to merge 4 commits into
Conversation
## Summary ### Why? SubmitQueue has gateway APIs and a terminal client but no reusable browser UX. Shipping one fixed Next application would couple the UI to a deployment's authentication, telemetry, routing, and process policy, forcing other deployers to fork it. ### What? Define a gateway-backed web package analogous to `submitqueue/client`: generated Connect clients, server-only gateway helpers, presentation models, components, and link helpers live in a pnpm workspace under `web/`, while host-owned Next applications provide routes, authorization, telemetry, configuration, transport, and deployment. The RFC specifies the Node/server boundary, Next 16 packaging and security constraints, TypeScript proto generation, additive gateway prerequisites, status and error compatibility, telemetry ownership, testing, CI isolation from Go/Bazel, a read-only first phase, and the promotion path for additional domain UX packages. Co-authored-by: Cursor <cursoragent@cursor.com>
## Summary ### Why? The RFC had grown into an implementation guide, with migration steps, build targets, file-by-file host instructions, and code samples, which buried the design decisions reviewers need to evaluate. ### What? Recast the RFC around package, gateway, host-composition, wire, and error boundaries plus ownership invariants. Library components are synchronous and props-only, polling uses `router.refresh()`, multi-gateway queue collisions fail at startup, and server actions are covered by an authorization lint. Adds a layered UX testing strategy covering contracts, components, browser UX and accessibility, host authorization, and end-to-end flows. Co-authored-by: Cursor <cursoragent@cursor.com>
## Summary ### Why? Review found contracts that would mis-route requests, emit phishing links, or fail to build as published packages: sqids contain a slash, the gateway speaks native gRPC, speculation runs sibling builds, and helpers cannot install interceptors on an already-created client. ### What? Require percent-encoding of path segments, a scheme-and-authority allowlist, history-only build URLs, `createGrpcTransport` with TLS by default, an exported tracing interceptor, one `@submitqueue/api` package, RSC export invariants, a structural `Logger`, a Node-owned Compose end-to-end check, and a `pnpm pack` test against an external Next app. Co-authored-by: Cursor <cursoragent@cursor.com>
## Summary ### Why? The RFC restated the same host and library boundaries and specified phase-one machinery the host already owns or that a read-only release does not need. ### What? State each boundary once. Keep phase one read-only, with queue names configured by the host. Record proxy-safe base64url paths, request-time rendering, stable list windows, and polling limits, and move build and test detail into acceptance criteria. Co-authored-by: Cursor <cursoragent@cursor.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Why?
The RFC restated the same host and library boundaries and specified phase-one machinery the host already owns or that a read-only release does not need.
What?
State each boundary once. Keep phase one read-only, with queue names configured by the host. Record proxy-safe base64url paths, request-time rendering, stable list windows, and polling limits, and move build and test detail into acceptance criteria.
Stack