Repository navigation
docs(web): design gateway-backed web library - #749
Draft
behinddwalls wants to merge 8 commits into
Draft
behinddwalls wants to merge 8 commits into
behinddwalls wants to merge 8 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> # Conflicts: # doc/rfc/index.md # Please enter the commit message for your changes. Lines starting # with '#' will be kept; you may remove them yourself if you want to. # An empty message aborts the commit. # # interactive rebase in progress; onto 6916596 # Last command done (1 command done): # pick ff32728 # docs(web): design gateway-backed web library # Next commands to do (4 remaining commands): # pick a1afdc2 # docs(web): refocus web library RFC on design boundaries # pick d05545e # docs(web): tighten web library transport and link contracts # You are currently rebasing branch 'preetam/web-rfc' on '69165965'. # # Changes to be committed: # modified: doc/rfc/index.md # new file: doc/rfc/web-library.md # # Untracked files: # web/ #
## 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>
## Summary ### Why? The RFC still described deferred telemetry, link, transport, and test-matrix capabilities as shipped prerequisites and acceptance criteria. ### What? Limit the host/library contract and acceptance section to the implemented diagnostic, polling, package, and h2c E2E coverage. Record trusted links, typed build URLs, OpenTelemetry, TLS E2E, shared status fixtures, and broader browser/version matrices as deferred work.
## Summary ### Why? Queue-first URLs make request links easy to construct without coupling the UI to the request identifier format. ### What? Document /<queue> as the queue landing page and /<queue>/request/<full-request-id> as the detail route. Update the pagination and route-test descriptions to match the implementation.
## Summary ### Why? Reviewers need a concise visual reference for the queue, request, and change-submission experience and its library/host boundary. ### What? Add four illustrated UX mocks and readable queue-scoped URL examples. Document queue discovery, pinned versus across-version submissions, and the bounded demo lookup. Keep UX descriptions concise and Next.js integration host-owned. Allow only the four versioned RFC images through the binary-file linter. ## Test Plan Visually checked mockup images and passed git diff --check. Passed the binary-linter unit tests and lint-binary with all four images staged; repository formatting, lint, tidy, and Gazelle checks passed before splitting the commits.
## Summary ### Why? The URL reference should reflect seamless refresh behavior rather than timestamp-pinned list navigation. ### What? Document clean rolling-window URLs, opaque pagination snapshots, and git change navigation with fake-provider hints kept out of the browser URL. ## Test Plan Passed git diff --check and the repository pre-commit formatting, lint, tidy, and Gazelle checks before splitting the commits.
behinddwalls
force-pushed
the
preetam/web-rfc
branch
from
October 6, 2026 20:54
8617a07 to
1421aa9
Compare
This was referenced Oct 6, 2026
behinddwalls
added this pull request to stack #794
October 6, 2026 21:02
behinddwalls
removed this pull request from stack #794
October 6, 2026 22:08
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?
SubmitQueue needs a reusable, read-only browser UX with clear ownership boundaries: the library supplies presentation and gateway helpers, while deployers own the application host.
What?
Define the library/reference-host architecture, queue-first readable URLs, request summary and lifecycle history, logical-change submission history, gateway-backed queue discovery, refresh behavior, and acceptance criteria. Include the queue, request, event-history, and change-history mockups. Document Bazel tooling and demo-host responsibilities without changing gateway or storage wire contracts.
Stack