Skip to content

Add sequences UI - #740

Open
bgentry wants to merge 4 commits into
masterfrom
sequence-diagnostics-ui
Open

bgentry wants to merge 4 commits into
masterfrom
sequence-diagnostics-ui

Conversation

@bgentry

@bgentry bgentry commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

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, SequenceJobList and SequenceCountPending.

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:

  • One source of truth. The inspection queries sit next to the promotion logic they describe, and are tested against it.
  • Every driver and database. River Pro tests them on pgx, database/sql and SQLite. Benchmarks there follow our existing patterns and illustrate the safety of these queries even at scale.
  • Available outside the UI. Apps can ask "why is this job pending?" in code, from the same API the UI uses (in all supported languages).

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_queries extension, which checks that River Pro's sequence indexes are installed.

Screenshots

A pending job whose sequence is halted by a cancelled job:

Job page for a pending job, showing its sequence halted by cancelled job #7001 and a red wait step on the timeline

Each section below shows desktop, tablet and mobile widths in light and dark.

Job page: pending job halted by a cancelled job
Light Dark
Job page with a halted sequence, desktop, light Job page with a halted sequence, desktop, dark
Job page with a halted sequence, tablet, light Job page with a halted sequence, tablet, dark
Job page with a halted sequence, mobile, light Job page with a halted sequence, mobile, dark
Job page: pending job waiting on a running job
Light Dark
Job page waiting on a running job, desktop, light Job page waiting on a running job, desktop, dark
Job page waiting on a running job, tablet, light Job page waiting on a running job, tablet, dark
Job page waiting on a running job, mobile, light Job page waiting on a running job, mobile, dark
Job page: pending job that's up next
Light Dark
Job page for the next job in its sequence, desktop, light Job page for the next job in its sequence, desktop, dark
Job page for the next job in its sequence, tablet, light Job page for the next job in its sequence, tablet, dark
Job page for the next job in its sequence, mobile, light Job page for the next job in its sequence, mobile, dark
Job page: cancelled job that halted its sequence
Light Dark
Job page for a job that halted its sequence, desktop, light Job page for a job that halted its sequence, desktop, dark
Job page for a job that halted its sequence, tablet, light Job page for a job that halted its sequence, tablet, dark
Job page for a job that halted its sequence, mobile, light Job page for a job that halted its sequence, mobile, dark
Delete warning for a job that halted its sequence
Light Dark
Delete warning dialog, desktop, light Delete warning dialog, desktop, dark
Delete warning dialog, tablet, light Delete warning dialog, tablet, dark
Delete warning dialog, mobile, light Delete warning dialog, mobile, dark
Sequence page: halted
Light Dark
Sequence page for a halted sequence, desktop, light Sequence page for a halted sequence, desktop, dark
Sequence page for a halted sequence, tablet, light Sequence page for a halted sequence, tablet, dark
Sequence page for a halted sequence, mobile, light Sequence page for a halted sequence, mobile, dark
Sequence page: waiting on a running job
Light Dark
Sequence page waiting on a running job, desktop, light Sequence page waiting on a running job, desktop, dark
Sequence page waiting on a running job, tablet, light Sequence page waiting on a running job, tablet, dark
Sequence page waiting on a running job, mobile, light Sequence page waiting on a running job, mobile, dark

@bgentry
bgentry force-pushed the sequence-diagnostics-ui branch 2 times, most recently from 77266d3 to 4cf33d4 Compare November 16, 2026 00:47
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
bgentry force-pushed the sequence-diagnostics-ui branch 4 times, most recently from 0309342 to d13e0cf Compare November 16, 2026 01:10
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
bgentry force-pushed the sequence-diagnostics-ui branch from d13e0cf to 0e6eeb4 Compare November 16, 2026 02:21
@bgentry bgentry changed the title Show why River Pro sequence jobs are pending Add sequences UI Nov 16, 2026
@bgentry
bgentry marked this pull request as ready for review November 16, 2026 02:32
@bgentry
bgentry requested a review from brandur November 16, 2026 02:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant