Repository navigation
Add sequences UI - #740
Open
bgentry wants to merge 4 commits into
Open
Add sequences UI#740bgentry wants to merge 4 commits into
bgentry wants to merge 4 commits into
Conversation
bgentry
force-pushed
the
sequence-diagnostics-ui
branch
2 times, most recently
from
November 16, 2026 00:47
77266d3 to
4cf33d4
Compare
A pending job in a River Pro sequence looks the same whether it's
waiting its turn or stuck behind a cancelled or discarded job that
halts everything after it. Expose River Pro's sequence inspection so
the UI can tell those apart.
`GET /api/pro/jobs/{job_id}/sequence` returns a job's wait reason, the
job that explains it, whether the job is itself halting its sequence,
and the sequence's head, blockers, and halting job. A halting job also
gets a pending count, capped at 1,000, so a delete warning can say how
many jobs would run without it. Inspection and count share one
transaction so they describe the same snapshot.
`GET /api/pro/sequence?key=` inspects a sequence by key with its
pending count, and `GET /api/pro/sequence/jobs?key=` pages through its
jobs in ID order with `after_id`, `before_id`, and `limit`. An
`after_id` of zero lists from the first job, and each page says with
`has_earlier` and `has_later` whether jobs exist past either end. Keys
go in the query string because they're usually base64, whose `/` and
`+` don't survive every proxy in a path. IDs are encoded as strings so
large IDs keep their precision in the browser.
A new `sequence_queries` extension reports whether the indexes these
queries read through are installed. Each endpoint checks them once and
remembers the result, so a polling page doesn't query the catalog on
every request.
bgentry
force-pushed
the
sequence-diagnostics-ui
branch
4 times, most recently
from
November 16, 2026 01:10
0309342 to
d13e0cf
Compare
Operators chasing a stuck River Pro sequence have no way to see its jobs together. A sequence key is a base64 SHA-256 hash in practice, so a job list filter can't be typed by hand, and a sequence can hold thousands of completed jobs ahead of thousands of pending ones. Add a `/sequences/<key>` page backed by the Pro sequence endpoints. Like the job page, the header names the sequence by its jobs' kind, with a status badge (halted, waiting, up next, active, or idle) and the key shortened beside a copy button. The key hashes options that aren't stored, so the kind is the only reliable name. A details grid below names the job holding the sequence back, the next pending job, and how many jobs are pending. Jobs are listed in ID order, which is the order they run in, in two-line rows like the Jobs list: a titled state icon, ID, kind and time, then args. IDs share one width so kinds line up across digit counts. A job holding the sequence back gets a third line saying what happened to it in the state's color, like "Cancelled · halted the sequence" or "Retrying in 4 minutes · blocking the sequence". The job that halted the sequence is highlighted with compact Retry and Delete buttons in place. A `?job=` search param outlines the job the operator came from, like the Workflow page's selected task. The page opens at the earliest job that explains the sequence's state (the job that halted it, the first blocking job, or the next pending job), so a long completed history doesn't push the problem off screen. "Show earlier jobs" and "Show later jobs" widen one contiguous range, capped at the API's 1,000 job page so a refresh is always a single request. The status polls only while the sequence can change on its own, which is while a job in it is active or its next job isn't held by a halted job, and the list reloads whenever the status changes. Deleting the job that halted the sequence opens a dedicated dialog rather than the generic confirmation: it says how many pending jobs wait behind it and lays out Retry and Delete side by side, with Retry focused because it keeps the sequence in order.
A pending job in a River Pro sequence shows only "Pending", whether it's next in line or stuck behind a cancelled job that halts the whole sequence. An app keying a sequence per order can pile up thousands of pending jobs behind cancelled ones with no way to tell. The job details grid gets a Sequence field beside Created, loaded from the Pro sequence endpoint when the server reports `sequence_queries`: - A pending job shows "Halted by #7001 · Cancelled" with how to resume, "Waiting on #7002 · Retrying in 4 minutes", "Waiting behind #7003 · Pending", or "Up next". The blocking job's state follows its link as plain text, so the badge and link are the line's only accents. - A cancelled or discarded job that halts its sequence shows "Halted · #7003 and later jobs wait", or names an earlier job that also halts the sequence. - Other jobs link the sequence's next pending job. A "View" link opens the sequence page with the job selected. Phrases like "by #48213171" stay together, so a narrow field wraps between them rather than inside one. The timeline's wait step names the reason and is tinted red for a halted sequence and amber while waiting. A pending job's status polls with the page's refresh setting. Other jobs load it once per job state, since their status only changes when they do. Retrying or cancelling the job reloads its status and any cached sequence page. Deleting a job that halted its sequence uses the sequence page's dialog, which says how many jobs would run without it and offers Retry in place. Other jobs keep the generic confirmation.
bgentry
force-pushed
the
sequence-diagnostics-ui
branch
from
November 16, 2026 02:21
d13e0cf to
0e6eeb4
Compare
bgentry
marked this pull request as ready for review
November 16, 2026 02:32
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
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.
The Sequences feature has not had a UI integration to date. This has led to stuck sequences being harder to debug than some other River features.
For a real-world example: say an app runs each order's jobs in a River Pro sequence keyed by order ID, so they run one at a time. If one of an order's jobs is cancelled, every job queued after it for that order stays pending until someone retries or deletes the cancelled job. River UI shows those jobs as just "Pending", the same as a job that's simply next in line, so there's no way to tell which jobs are stuck or what they're stuck behind. There's also no easy way to see a sequence's jobs together.
This adds three things for River Pro sequences:
Job page. A Sequence field says where the job stands: "Up next", "Waiting on #7002 · Running", "Waiting behind #7003", or "Halted by #7001 · Cancelled" with how to resume. The timeline's wait step now shows the reason, tinted red when halted and amber when waiting. A cancelled or discarded job that halted its sequence says which jobs wait behind it.
I originally started riffing on top of Add sequences information to job detail page #739 primarily to try other ideas here, because I didn't want to push the args so far down the page (especially on mobile).
Sequence page (
/sequences/<key>). Lists a sequence's jobs in the order they run. It opens itself at the job that explains the sequence's state rather than the start of a long completed history. The job that halted the sequence is highlighted with Retry and Delete in place.Delete warning. Deleting a job that halted its sequence opens a dialog that says how many pending jobs wait behind it and offers Retry instead.
Why the queries live in River Pro
This is an alternative to #739, which set out to solve the same problem and gets a lot right about what to show. The main structural difference is where the sequence queries live. #739 adds them to River UI's own drivers. This PR calls new River Pro client APIs instead:
SequenceJobInspect,SequenceInspect,SequenceJobListandSequenceCountPending.It's not just query colocation that benefits from this arrangement, though. Whether a pending job can run depends on River Pro's promotion rules. Those cover which earlier jobs hold it back, and when a cancelled or discarded job lets the sequence continue. If River UI has its own copy of those rules, the two can drift apart, and the UI would then show the wrong reason for a stuck job. Keeping the queries in River Pro means:
database/sqland SQLite. Benchmarks there follow our existing patterns and illustrate the safety of these queries even at scale.Rollout
This PR can't have passing CI until we release the Pro side it depends on and bump riverpro accordingly. The UI shows sequence status only when the server reports the new
sequence_queriesextension, which checks that River Pro's sequence indexes are installed.Screenshots
A pending job whose sequence is halted by a cancelled job:
Each section below shows desktop, tablet and mobile widths in light and dark.
Job page: pending job halted by a cancelled job
Job page: pending job waiting on a running job
Job page: pending job that's up next
Job page: cancelled job that halted its sequence
Delete warning for a job that halted its sequence
Sequence page: halted
Sequence page: waiting on a running job