From 5e60bb76a8f6d6022c884e2363f33d6926024440 Mon Sep 17 00:00:00 2001 From: Brandur Date: Sun, 15 Nov 2026 00:23:13 -0600 Subject: [PATCH 1/3] Add sequences information to job detail page Adds more detail about sequences to the job detail page in River UI. It'll show information like the sequence that the job is a member of, the reason the current job is waiting, the sequence head, and the next pending job. This is done at the request of one of our Pro users, who found that introspectability of sequences as they're currently implemented is lacing. All information is about to hit existing sequences indexes with no new migrations needed. With 1.1 million synthetic jobs, lookup times were in the range of 0.1-3.3 ms. --- CHANGELOG.md | 4 + .../river_ui_driver_interface.go | 3 + .../riveruidrivertest/riveruidrivertest.go | 1 + .../riveruidrivertest/sequence.go | 142 ++++++++++++++++++ .../riveruipostgres/internal/dbsqlc/models.go | 2 + .../internal/dbsqlc/river_job.sql | 2 + .../internal/dbsqlc/river_queries.go | 8 + .../internal/dbsqlc/sequence.sql | 105 +++++++++++++ .../internal/dbsqlc/sequence.sql.go | 124 +++++++++++++++ .../internal/dbsqlc/sequence_test.go | 71 +++++++++ .../riveruipostgres/internal/dbsqlc/sqlc.yaml | 1 + .../river_ui_postgres_driver.go | 15 ++ .../riveruisqlite/internal/dbsqlc/models.go | 2 + .../internal/dbsqlc/river_job.sql | 2 + .../internal/dbsqlc/river_queries.go | 8 + .../internal/dbsqlc/sequence.sql | 105 +++++++++++++ .../internal/dbsqlc/sequence.sql.go | 124 +++++++++++++++ .../internal/dbsqlc/sequence_test.go | 47 ++++++ .../riveruisqlite/internal/dbsqlc/sqlc.yaml | 1 + .../riveruisqlite/river_ui_sqlite_driver.go | 15 ++ internal/riveruidriver/sequence.go | 63 ++++++++ riverproui/endpoints.go | 7 + .../prohandler/dead_letter_endpoints.go | 6 +- .../internal/prohandler/sequence_endpoints.go | 110 ++++++++++++++ .../prohandler/sequence_endpoints_test.go | 82 ++++++++++ riverproui/pro_handler_test.go | 7 + src/components/JobDetail.tsx | 6 + src/components/SequenceDetails.test.tsx | 113 ++++++++++++++ src/components/SequenceDetails.tsx | 126 ++++++++++++++++ src/components/WorkflowDetail.test.tsx | 1 + src/routes/jobs/$jobId.tsx | 44 +++++- src/routes/jobs/jobSequence.test.tsx | 122 +++++++++++++++ src/services/features.test.ts | 2 + src/services/features.ts | 1 + src/services/sequences.test.ts | 40 +++++ src/services/sequences.ts | 81 ++++++++++ src/test/utils/features.ts | 1 + 37 files changed, 1584 insertions(+), 10 deletions(-) create mode 100644 internal/riveruidriver/riveruidrivertest/sequence.go create mode 100644 internal/riveruidriver/riveruipostgres/internal/dbsqlc/sequence.sql create mode 100644 internal/riveruidriver/riveruipostgres/internal/dbsqlc/sequence.sql.go create mode 100644 internal/riveruidriver/riveruipostgres/internal/dbsqlc/sequence_test.go create mode 100644 internal/riveruidriver/riveruisqlite/internal/dbsqlc/sequence.sql create mode 100644 internal/riveruidriver/riveruisqlite/internal/dbsqlc/sequence.sql.go create mode 100644 internal/riveruidriver/riveruisqlite/internal/dbsqlc/sequence_test.go create mode 100644 internal/riveruidriver/sequence.go create mode 100644 riverproui/internal/prohandler/sequence_endpoints.go create mode 100644 riverproui/internal/prohandler/sequence_endpoints_test.go create mode 100644 src/components/SequenceDetails.test.tsx create mode 100644 src/components/SequenceDetails.tsx create mode 100644 src/routes/jobs/jobSequence.test.tsx create mode 100644 src/services/sequences.test.ts create mode 100644 src/services/sequences.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index fa46e80c..8cd7cf7a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- Show sequence wait reasons, the sequence head, and blocking jobs with links on job detail pages. Diagnostics use sequence scheduling indexes and exclude completed job history. [PR #XXX](https://github.com/riverqueue/riverui/pull/XXX). + ## [v0.22.0] - 2026-10-24 ### Added diff --git a/internal/riveruidriver/river_ui_driver_interface.go b/internal/riveruidriver/river_ui_driver_interface.go index 0f694c62..1ada10e9 100644 --- a/internal/riveruidriver/river_ui_driver_interface.go +++ b/internal/riveruidriver/river_ui_driver_interface.go @@ -44,6 +44,9 @@ type Executor interface { // bytes. Only Pro endpoints call this query; it requires the dead letter // table. JobDeadLetterAutocomplete(ctx context.Context, params *JobDeadLetterAutocompleteParams) ([]string, error) + // JobSequenceGet inspects one sequence using its scheduling indexes. A nil + // result means the job does not exist or has no sequence key. + JobSequenceGet(ctx context.Context, params *JobSequenceGetParams) (*JobSequence, error) } const ( diff --git a/internal/riveruidriver/riveruidrivertest/riveruidrivertest.go b/internal/riveruidriver/riveruidrivertest/riveruidrivertest.go index e58b7386..e5c3d897 100644 --- a/internal/riveruidriver/riveruidrivertest/riveruidrivertest.go +++ b/internal/riveruidriver/riveruidrivertest/riveruidrivertest.go @@ -25,6 +25,7 @@ func Exercise( ) { t.Helper() + exerciseJobSequenceGet(ctx, t, driver, executorWithTx) exerciseGetExecutor(ctx, t, driver, executorWithTx) exerciseJobCountByAllStatesCapped(ctx, t, driver, executorWithTx) exerciseJobCountEstimate(ctx, t, databaseName, driver, executorWithTx) diff --git a/internal/riveruidriver/riveruidrivertest/sequence.go b/internal/riveruidriver/riveruidrivertest/sequence.go new file mode 100644 index 00000000..df6990a4 --- /dev/null +++ b/internal/riveruidriver/riveruidrivertest/sequence.go @@ -0,0 +1,142 @@ +package riveruidrivertest + +import ( + "context" + "fmt" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/riverqueue/river/riverdriver" + "github.com/riverqueue/river/rivershared/testfactory" + "github.com/riverqueue/river/rivershared/util/dbutil" + "github.com/riverqueue/river/rivertype" + + "riverqueue.com/riverui/internal/riveruidriver" +) + +func exerciseJobSequenceGet(ctx context.Context, t *testing.T, driver riveruidriver.Driver, executorWithTx func(context.Context, *testing.T) (riverdriver.Executor, string)) { + t.Helper() + + t.Run("JobSequenceGet", func(t *testing.T) { + t.Parallel() + + type testBundle struct { + exec riveruidriver.Executor + insert func(rivertype.JobState, string) *rivertype.JobRow + inspect func(int64) *riveruidriver.JobSequence + prefix string + } + setup := func(t *testing.T) *testBundle { + t.Helper() + exec, schema := executorWithSchema(ctx, t, driver, executorWithTx) + prefix := "" + if schema != "" { + prefix = dbutil.SafeIdentifier(schema) + "." + } + return &testBundle{ + exec: exec, + insert: func(state rivertype.JobState, metadata string) *rivertype.JobRow { + return testfactory.Job(ctx, t, exec, &testfactory.JobOpts{Metadata: []byte(metadata), Schema: schema, State: &state}) + }, + inspect: func(id int64) *riveruidriver.JobSequence { + result, err := exec.JobSequenceGet(ctx, &riveruidriver.JobSequenceGetParams{ID: id, Schema: schema}) + require.NoError(t, err) + return result + }, + prefix: prefix, + } + } + + for _, state := range []rivertype.JobState{rivertype.JobStateAvailable, rivertype.JobStateCancelled, rivertype.JobStateDiscarded, rivertype.JobStateRetryable, rivertype.JobStateRunning, rivertype.JobStateScheduled} { + t.Run(string(state), func(t *testing.T) { + t.Parallel() + bundle := setup(t) + // Completed history and other keys must never become blockers. + bundle.insert(rivertype.JobStateCompleted, `{"seq_key":"invoice"}`) + bundle.insert(rivertype.JobStateCancelled, `{"seq_key":"other"}`) + blocker := bundle.insert(state, `{"seq_key":"invoice"}`) + first := bundle.insert(rivertype.JobStatePending, `{"seq_key":"invoice","seq_continue_cancelled":true,"seq_continue_discarded":true}`) + last := bundle.insert(rivertype.JobStatePending, `{"seq_key":"invoice"}`) + result := bundle.inspect(last.ID) + require.Equal(t, "invoice", result.Key) + require.Equal(t, last.ID, result.JobID) + require.Equal(t, first.ID, result.FirstPending.ID) + require.Len(t, result.Blockers, 1) + require.Equal(t, blocker.ID, result.Blockers[0].ID) + require.Equal(t, blocker.Kind, result.Blockers[0].Kind) + require.Equal(t, blocker.Queue, result.Blockers[0].Queue) + require.Equal(t, state, result.Blockers[0].State) + if state == rivertype.JobStateCancelled || state == rivertype.JobStateDiscarded { + require.Equal(t, "halted", result.WaitReason()) + } else { + require.Equal(t, "waiting", result.WaitReason()) + } + require.Equal(t, "none", bundle.inspect(blocker.ID).WaitReason()) + }) + } + + t.Run("ActiveAfterPendingHead", func(t *testing.T) { + t.Parallel() + bundle := setup(t) + first := bundle.insert(rivertype.JobStatePending, `{"seq_key":"invoice"}`) + active := bundle.insert(rivertype.JobStateRunning, `{"seq_key":"invoice"}`) + result := bundle.inspect(first.ID) + require.Equal(t, "waiting", result.WaitReason()) + require.Len(t, result.Blockers, 1) + require.Equal(t, active.ID, result.Blockers[0].ID) + }) + + t.Run("ContinuationAndTerminalPosition", func(t *testing.T) { + t.Parallel() + bundle := setup(t) + bundle.insert(rivertype.JobStateCancelled, `{"seq_key":"invoice","seq_continue_cancelled":true}`) + bundle.insert(rivertype.JobStateDiscarded, `{"seq_key":"invoice","seq_continue_discarded":true}`) + first := bundle.insert(rivertype.JobStatePending, `{"seq_key":"invoice"}`) + bundle.insert(rivertype.JobStateCancelled, `{"seq_key":"invoice"}`) + bundle.insert(rivertype.JobStateDiscarded, `{"seq_key":"invoice"}`) + last := bundle.insert(rivertype.JobStatePending, `{"seq_key":"invoice"}`) + result := bundle.inspect(first.ID) + require.Empty(t, result.Blockers) + require.Equal(t, "awaiting_promotion", result.WaitReason()) + require.Equal(t, "waiting", bundle.inspect(last.ID).WaitReason()) + }) + + t.Run("EarliestBlockerPerState", func(t *testing.T) { + t.Parallel() + bundle := setup(t) + cancelled := bundle.insert(rivertype.JobStateCancelled, `{"seq_key":"invoice"}`) + bundle.insert(rivertype.JobStateCancelled, `{"seq_key":"invoice"}`) + discarded := bundle.insert(rivertype.JobStateDiscarded, `{"seq_key":"invoice"}`) + pending := bundle.insert(rivertype.JobStatePending, `{"seq_key":"invoice"}`) + result := bundle.inspect(pending.ID) + require.Len(t, result.Blockers, 2) + require.Equal(t, cancelled.ID, result.Blockers[0].ID) + require.Equal(t, discarded.ID, result.Blockers[1].ID) + }) + + t.Run("MissingAndNonSequence", func(t *testing.T) { + t.Parallel() + bundle := setup(t) + require.Nil(t, bundle.inspect(9223372036854775807)) + for _, metadata := range []string{`{}`, `{"seq_key":null}`, `{"seq_key":123}`, `{"seq_key":""}`} { + job := bundle.insert(rivertype.JobStatePending, metadata) + require.Nil(t, bundle.inspect(job.ID)) + } + }) + + t.Run("Recovery", func(t *testing.T) { + t.Parallel() + bundle := setup(t) + blocker := bundle.insert(rivertype.JobStateDiscarded, `{"seq_key":"invoice"}`) + pending := bundle.insert(rivertype.JobStatePending, `{"seq_key":"invoice"}`) + require.Equal(t, "halted", bundle.inspect(pending.ID).WaitReason()) + require.NoError(t, bundle.exec.Exec(ctx, fmt.Sprintf("UPDATE %sriver_job SET state = 'pending', finalized_at = NULL WHERE id = %d", bundle.prefix, blocker.ID))) + result := bundle.inspect(pending.ID) + require.Equal(t, blocker.ID, result.FirstPending.ID) + require.Equal(t, "waiting", result.WaitReason()) + require.NoError(t, bundle.exec.Exec(ctx, fmt.Sprintf("DELETE FROM %sriver_job WHERE id = %d", bundle.prefix, blocker.ID))) + require.Equal(t, "awaiting_promotion", bundle.inspect(pending.ID).WaitReason()) + }) + }) +} diff --git a/internal/riveruidriver/riveruipostgres/internal/dbsqlc/models.go b/internal/riveruidriver/riveruipostgres/internal/dbsqlc/models.go index b073149f..5c8d65a8 100644 --- a/internal/riveruidriver/riveruipostgres/internal/dbsqlc/models.go +++ b/internal/riveruidriver/riveruipostgres/internal/dbsqlc/models.go @@ -67,6 +67,8 @@ type PgStatAllTables struct { type RiverJob struct { ID int64 + Kind string + Metadata []byte Priority int16 Queue string State RiverJobState diff --git a/internal/riveruidriver/riveruipostgres/internal/dbsqlc/river_job.sql b/internal/riveruidriver/riveruipostgres/internal/dbsqlc/river_job.sql index 146f957a..57b9e21e 100644 --- a/internal/riveruidriver/riveruipostgres/internal/dbsqlc/river_job.sql +++ b/internal/riveruidriver/riveruipostgres/internal/dbsqlc/river_job.sql @@ -14,6 +14,8 @@ CREATE TYPE river_job_state AS ENUM( -- table definition if future UI queries need additional columns. CREATE TABLE river_job ( id bigserial PRIMARY KEY, + kind text NOT NULL DEFAULT '', + metadata jsonb NOT NULL DEFAULT '{}', priority smallint NOT NULL DEFAULT 1, queue text NOT NULL DEFAULT 'default', state river_job_state NOT NULL DEFAULT 'available', diff --git a/internal/riveruidriver/riveruipostgres/internal/dbsqlc/river_queries.go b/internal/riveruidriver/riveruipostgres/internal/dbsqlc/river_queries.go index f28f55f1..e85b6a70 100644 --- a/internal/riveruidriver/riveruipostgres/internal/dbsqlc/river_queries.go +++ b/internal/riveruidriver/riveruipostgres/internal/dbsqlc/river_queries.go @@ -110,3 +110,11 @@ func JobDeadLetterAutocompleteRiver(ctx context.Context, db RowQuerier, facet, m } return values, nil } + +func JobSequenceGetRiver(ctx context.Context, db RowQuerier, jobID int64) (string, error) { + var sequence string + if err := db.QueryRow(ctx, jobSequenceGet, jobID).Scan(&sequence); err != nil { + return "", err + } + return sequence, nil +} diff --git a/internal/riveruidriver/riveruipostgres/internal/dbsqlc/sequence.sql b/internal/riveruidriver/riveruipostgres/internal/dbsqlc/sequence.sql new file mode 100644 index 00000000..81f501b0 --- /dev/null +++ b/internal/riveruidriver/riveruipostgres/internal/dbsqlc/sequence.sql @@ -0,0 +1,105 @@ +-- Each probe constrains state and sequence key before ordering by ID. This +-- matches River Pro's river_job_sequence_scheduling index and excludes completed +-- history. Separate active-state probes avoid sorting an entire sequence. +-- Terminal blockers must precede the first pending job and use their own +-- continuation flags, matching the sequence supervisor. Active jobs block from +-- anywhere in the sequence, including after its pending head. +-- name: JobSequenceGet :one +WITH target AS ( + SELECT job.id, job.state, job.metadata->>'seq_key' AS seq_key + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.id = @job_id::bigint + AND job.metadata ? 'seq_key' + AND jsonb_typeof(job.metadata->'seq_key') = 'string' + AND job.metadata->>'seq_key' <> '' +), +first_pending AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'pending' + AND job.metadata ? 'seq_key' + AND job.metadata->>'seq_key' = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +available_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'available' + AND job.metadata ? 'seq_key' + AND job.metadata->>'seq_key' = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +cancelled_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'cancelled' + AND job.metadata ? 'seq_key' + AND job.metadata->>'seq_key' = (SELECT seq_key FROM target) + AND job.id < (SELECT first_pending.id FROM first_pending) + AND NOT COALESCE((job.metadata->'seq_continue_cancelled')::boolean, false) + ORDER BY job.id + LIMIT 1 +), +discarded_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'discarded' + AND job.metadata ? 'seq_key' + AND job.metadata->>'seq_key' = (SELECT seq_key FROM target) + AND job.id < (SELECT first_pending.id FROM first_pending) + AND NOT COALESCE((job.metadata->'seq_continue_discarded')::boolean, false) + ORDER BY job.id + LIMIT 1 +), +retryable_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'retryable' + AND job.metadata ? 'seq_key' + AND job.metadata->>'seq_key' = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +running_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'running' + AND job.metadata ? 'seq_key' + AND job.metadata->>'seq_key' = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +scheduled_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'scheduled' + AND job.metadata ? 'seq_key' + AND job.metadata->>'seq_key' = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +blockers AS ( + SELECT * FROM available_blocker + UNION ALL + SELECT * FROM cancelled_blocker + UNION ALL + SELECT * FROM discarded_blocker + UNION ALL + SELECT * FROM retryable_blocker + UNION ALL + SELECT * FROM running_blocker + UNION ALL + SELECT * FROM scheduled_blocker +) +SELECT COALESCE(( + SELECT json_build_object( + 'job_id', target.id, + 'job_state', target.state, + 'key', target.seq_key, + 'first_pending', (SELECT row_to_json(first_pending) FROM first_pending), + 'blockers', COALESCE((SELECT json_agg(blockers ORDER BY id) FROM blockers), '[]'::json) + )::text + FROM target +), 'null')::text AS sequence; diff --git a/internal/riveruidriver/riveruipostgres/internal/dbsqlc/sequence.sql.go b/internal/riveruidriver/riveruipostgres/internal/dbsqlc/sequence.sql.go new file mode 100644 index 00000000..e9fd8883 --- /dev/null +++ b/internal/riveruidriver/riveruipostgres/internal/dbsqlc/sequence.sql.go @@ -0,0 +1,124 @@ +// Code generated by sqlc. DO NOT EDIT. +// versions: +// sqlc v1.31.0 +// source: sequence.sql + +package dbsqlc + +import ( + "context" +) + +const jobSequenceGet = `-- name: JobSequenceGet :one +WITH target AS ( + SELECT job.id, job.state, job.metadata->>'seq_key' AS seq_key + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.id = $1::bigint + AND job.metadata ? 'seq_key' + AND jsonb_typeof(job.metadata->'seq_key') = 'string' + AND job.metadata->>'seq_key' <> '' +), +first_pending AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'pending' + AND job.metadata ? 'seq_key' + AND job.metadata->>'seq_key' = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +available_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'available' + AND job.metadata ? 'seq_key' + AND job.metadata->>'seq_key' = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +cancelled_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'cancelled' + AND job.metadata ? 'seq_key' + AND job.metadata->>'seq_key' = (SELECT seq_key FROM target) + AND job.id < (SELECT first_pending.id FROM first_pending) + AND NOT COALESCE((job.metadata->'seq_continue_cancelled')::boolean, false) + ORDER BY job.id + LIMIT 1 +), +discarded_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'discarded' + AND job.metadata ? 'seq_key' + AND job.metadata->>'seq_key' = (SELECT seq_key FROM target) + AND job.id < (SELECT first_pending.id FROM first_pending) + AND NOT COALESCE((job.metadata->'seq_continue_discarded')::boolean, false) + ORDER BY job.id + LIMIT 1 +), +retryable_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'retryable' + AND job.metadata ? 'seq_key' + AND job.metadata->>'seq_key' = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +running_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'running' + AND job.metadata ? 'seq_key' + AND job.metadata->>'seq_key' = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +scheduled_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'scheduled' + AND job.metadata ? 'seq_key' + AND job.metadata->>'seq_key' = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +blockers AS ( + SELECT id, kind, queue, state, scheduled_at FROM available_blocker + UNION ALL + SELECT id, kind, queue, state, scheduled_at FROM cancelled_blocker + UNION ALL + SELECT id, kind, queue, state, scheduled_at FROM discarded_blocker + UNION ALL + SELECT id, kind, queue, state, scheduled_at FROM retryable_blocker + UNION ALL + SELECT id, kind, queue, state, scheduled_at FROM running_blocker + UNION ALL + SELECT id, kind, queue, state, scheduled_at FROM scheduled_blocker +) +SELECT COALESCE(( + SELECT json_build_object( + 'job_id', target.id, + 'job_state', target.state, + 'key', target.seq_key, + 'first_pending', (SELECT row_to_json(first_pending) FROM first_pending), + 'blockers', COALESCE((SELECT json_agg(blockers ORDER BY id) FROM blockers), '[]'::json) + )::text + FROM target +), 'null')::text AS sequence +` + +// Each probe constrains state and sequence key before ordering by ID. This +// matches River Pro's river_job_sequence_scheduling index and excludes completed +// history. Separate active-state probes avoid sorting an entire sequence. +// Terminal blockers must precede the first pending job and use their own +// continuation flags, matching the sequence supervisor. Active jobs block from +// anywhere in the sequence, including after its pending head. +func (q *Queries) JobSequenceGet(ctx context.Context, db DBTX, jobID int64) (string, error) { + row := db.QueryRow(ctx, jobSequenceGet, jobID) + var sequence string + err := row.Scan(&sequence) + return sequence, err +} diff --git a/internal/riveruidriver/riveruipostgres/internal/dbsqlc/sequence_test.go b/internal/riveruidriver/riveruipostgres/internal/dbsqlc/sequence_test.go new file mode 100644 index 00000000..68ee8945 --- /dev/null +++ b/internal/riveruidriver/riveruipostgres/internal/dbsqlc/sequence_test.go @@ -0,0 +1,71 @@ +package dbsqlc + +import ( + "encoding/json" + "strings" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/riverqueue/river/rivershared/riversharedtest" +) + +func TestJobSequenceGetQueryPlan(t *testing.T) { + t.Parallel() + + ctx := t.Context() + tx, err := riversharedtest.DBPool(ctx, t).Begin(ctx) + require.NoError(t, err) + t.Cleanup(func() { _ = tx.Rollback(ctx) }) + + // A large completed history in the inspected sequence and many unrelated + // sequences must not turn a diagnostic request into a full table scan. + _, err = tx.Exec(ctx, ` +CREATE TEMP TABLE river_job ( + id bigint PRIMARY KEY, kind text NOT NULL DEFAULT 'invoice', queue text NOT NULL DEFAULT 'default', + state text NOT NULL, scheduled_at timestamptz NOT NULL DEFAULT now(), metadata jsonb NOT NULL +) ON COMMIT DROP; +CREATE INDEX river_job_sequence_scheduling ON river_job (state, (metadata->>'seq_key'), id) WHERE metadata ? 'seq_key'; +CREATE INDEX river_job_sequence_first_pending ON river_job ((metadata->>'seq_key'), id) INCLUDE (scheduled_at) WHERE metadata ? 'seq_key' AND state = 'pending'; +CREATE INDEX river_job_sequence_latest_active ON river_job ((metadata->>'seq_key'), id DESC) INCLUDE (state) WHERE metadata ? 'seq_key' AND state NOT IN ('pending', 'completed'); +INSERT INTO river_job (id, state, metadata) +SELECT i, 'completed', '{"seq_key":"invoice"}' FROM generate_series(1, 50000) i; +INSERT INTO river_job (id, state, metadata) +SELECT i, 'pending', jsonb_build_object('seq_key', 'other-' || i) FROM generate_series(50001, 100000) i; +INSERT INTO river_job (id, state, metadata) VALUES (100001, 'cancelled', '{"seq_key":"invoice"}'); +INSERT INTO river_job (id, state, metadata) +SELECT i, 'pending', '{"seq_key":"invoice"}' FROM generate_series(100002, 110001) i; +ANALYZE river_job; +SET LOCAL plan_cache_mode = force_generic_plan; +`) + require.NoError(t, err) + + query := strings.ReplaceAll(jobSequenceGet, "/* TEMPLATE: schema */", "") + var rawPlan []byte + require.NoError(t, tx.QueryRow(ctx, "EXPLAIN (ANALYZE, FORMAT JSON) "+query, int64(110001)).Scan(&rawPlan)) + type planNode struct { + IndexName string `json:"Index Name"` //nolint:tagliatelle // PostgreSQL defines these keys. + NodeType string `json:"Node Type"` //nolint:tagliatelle // PostgreSQL defines these keys. + Plans []planNode `json:"Plans"` //nolint:tagliatelle // PostgreSQL defines these keys. + RelationName string `json:"Relation Name"` //nolint:tagliatelle // PostgreSQL defines these keys. + } + var plans []struct { + Plan planNode `json:"Plan"` //nolint:tagliatelle // PostgreSQL defines these keys. + } + require.NoError(t, json.Unmarshal(rawPlan, &plans)) + require.Len(t, plans, 1) + scans := 0 + var visit func(planNode) + visit = func(node planNode) { + if node.RelationName == "river_job" { + scans++ + require.Contains(t, []string{"Index Scan", "Index Only Scan"}, node.NodeType, "%s", rawPlan) + require.NotEmpty(t, node.IndexName) + } + for _, child := range node.Plans { + visit(child) + } + } + visit(plans[0].Plan) + require.Equal(t, 8, scans, "one PK lookup, one pending head, and six blocker probes") +} diff --git a/internal/riveruidriver/riveruipostgres/internal/dbsqlc/sqlc.yaml b/internal/riveruidriver/riveruipostgres/internal/dbsqlc/sqlc.yaml index 91b1aa0a..820ef7f4 100644 --- a/internal/riveruidriver/riveruipostgres/internal/dbsqlc/sqlc.yaml +++ b/internal/riveruidriver/riveruipostgres/internal/dbsqlc/sqlc.yaml @@ -2,6 +2,7 @@ version: "2" sql: - engine: "postgresql" queries: + - sequence.sql - river_job.sql - river_job_dead_letter.sql schema: diff --git a/internal/riveruidriver/riveruipostgres/river_ui_postgres_driver.go b/internal/riveruidriver/riveruipostgres/river_ui_postgres_driver.go index 04157ecf..ab99fa6b 100644 --- a/internal/riveruidriver/riveruipostgres/river_ui_postgres_driver.go +++ b/internal/riveruidriver/riveruipostgres/river_ui_postgres_driver.go @@ -188,3 +188,18 @@ func (e *Executor) JobDeadLetterAutocomplete(ctx context.Context, params *riveru slices.Sort(values) return values, nil } + +func (e *Executor) JobSequenceGet(ctx context.Context, params *riveruidriver.JobSequenceGetParams) (*riveruidriver.JobSequence, error) { + raw, err := dbsqlc.JobSequenceGetRiver(schemaTemplateParam(ctx, params.Schema), e.dbtx, params.ID) + if err != nil { + return nil, fmt.Errorf("error inspecting job sequence: %w", err) + } + var sequence *riveruidriver.JobSequence + if err := json.Unmarshal([]byte(raw), &sequence); err != nil { + return nil, fmt.Errorf("error decoding job sequence: %w", err) + } + if sequence != nil { + sequence.Normalize() + } + return sequence, nil +} diff --git a/internal/riveruidriver/riveruisqlite/internal/dbsqlc/models.go b/internal/riveruidriver/riveruisqlite/internal/dbsqlc/models.go index 8529d6ac..af1810f1 100644 --- a/internal/riveruidriver/riveruisqlite/internal/dbsqlc/models.go +++ b/internal/riveruidriver/riveruisqlite/internal/dbsqlc/models.go @@ -10,6 +10,8 @@ import ( type RiverJob struct { ID int64 + Kind string + Metadata string Priority int64 Queue string State string diff --git a/internal/riveruidriver/riveruisqlite/internal/dbsqlc/river_job.sql b/internal/riveruidriver/riveruisqlite/internal/dbsqlc/river_job.sql index 4f5dc25e..79193d4c 100644 --- a/internal/riveruidriver/riveruisqlite/internal/dbsqlc/river_job.sql +++ b/internal/riveruidriver/riveruisqlite/internal/dbsqlc/river_job.sql @@ -3,6 +3,8 @@ -- table definition if future UI queries need additional columns. CREATE TABLE river_job ( id integer PRIMARY KEY, + kind text NOT NULL DEFAULT '', + metadata text NOT NULL DEFAULT '{}', priority integer NOT NULL DEFAULT 1, queue text NOT NULL DEFAULT 'default', state text NOT NULL DEFAULT 'available', diff --git a/internal/riveruidriver/riveruisqlite/internal/dbsqlc/river_queries.go b/internal/riveruidriver/riveruisqlite/internal/dbsqlc/river_queries.go index 71023799..2850bdf6 100644 --- a/internal/riveruidriver/riveruisqlite/internal/dbsqlc/river_queries.go +++ b/internal/riveruidriver/riveruisqlite/internal/dbsqlc/river_queries.go @@ -60,3 +60,11 @@ func JobDeadLetterAutocompleteRiver(ctx context.Context, db RowQuerier, facet, m } return values, nil } + +func JobSequenceGetRiver(ctx context.Context, db RowQuerier, jobID int64) (string, error) { + var sequence string + if err := db.QueryRow(ctx, jobSequenceGet, jobID).Scan(&sequence); err != nil { + return "", err + } + return sequence, nil +} diff --git a/internal/riveruidriver/riveruisqlite/internal/dbsqlc/sequence.sql b/internal/riveruidriver/riveruisqlite/internal/dbsqlc/sequence.sql new file mode 100644 index 00000000..5b32a4ea --- /dev/null +++ b/internal/riveruidriver/riveruisqlite/internal/dbsqlc/sequence.sql @@ -0,0 +1,105 @@ +-- Each probe constrains state and sequence key before ordering by ID. This +-- matches River Pro's river_job_sequence_scheduling index and excludes completed +-- history. Separate active-state probes avoid sorting an entire sequence. +-- Terminal blockers must precede the first pending job and use their own +-- continuation flags, matching the sequence supervisor. Active jobs block from +-- anywhere in the sequence, including after its pending head. +-- name: JobSequenceGet :one +WITH target AS ( + SELECT job.id, job.state, json_extract(job.metadata, '$.seq_key') AS seq_key + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.id = @job_id + AND json_type(job.metadata, '$.seq_key') IS NOT NULL + AND json_type(job.metadata, '$.seq_key') = 'text' + AND json_extract(job.metadata, '$.seq_key') <> '' +), +first_pending AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'pending' + AND json_type(job.metadata, '$.seq_key') IS NOT NULL + AND json_extract(job.metadata, '$.seq_key') = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +available_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'available' + AND json_type(job.metadata, '$.seq_key') IS NOT NULL + AND json_extract(job.metadata, '$.seq_key') = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +cancelled_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'cancelled' + AND json_type(job.metadata, '$.seq_key') IS NOT NULL + AND json_extract(job.metadata, '$.seq_key') = (SELECT seq_key FROM target) + AND job.id < (SELECT first_pending.id FROM first_pending) + AND COALESCE(json_extract(job.metadata, '$.seq_continue_cancelled'), 0) != 1 + ORDER BY job.id + LIMIT 1 +), +discarded_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'discarded' + AND json_type(job.metadata, '$.seq_key') IS NOT NULL + AND json_extract(job.metadata, '$.seq_key') = (SELECT seq_key FROM target) + AND job.id < (SELECT first_pending.id FROM first_pending) + AND COALESCE(json_extract(job.metadata, '$.seq_continue_discarded'), 0) != 1 + ORDER BY job.id + LIMIT 1 +), +retryable_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'retryable' + AND json_type(job.metadata, '$.seq_key') IS NOT NULL + AND json_extract(job.metadata, '$.seq_key') = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +running_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'running' + AND json_type(job.metadata, '$.seq_key') IS NOT NULL + AND json_extract(job.metadata, '$.seq_key') = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +scheduled_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'scheduled' + AND json_type(job.metadata, '$.seq_key') IS NOT NULL + AND json_extract(job.metadata, '$.seq_key') = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +blockers AS ( + SELECT * FROM available_blocker + UNION ALL + SELECT * FROM cancelled_blocker + UNION ALL + SELECT * FROM discarded_blocker + UNION ALL + SELECT * FROM retryable_blocker + UNION ALL + SELECT * FROM running_blocker + UNION ALL + SELECT * FROM scheduled_blocker +) +SELECT COALESCE(( + SELECT json_object( + 'job_id', target.id, + 'job_state', target.state, + 'key', target.seq_key, + 'first_pending', json((SELECT json_object('id', id, 'kind', kind, 'queue', queue, 'state', state, 'scheduled_at', strftime('%Y-%m-%dT%H:%M:%fZ', scheduled_at)) FROM first_pending)), + 'blockers', json((SELECT json_group_array(json(job)) FROM (SELECT json_object('id', id, 'kind', kind, 'queue', queue, 'state', state, 'scheduled_at', strftime('%Y-%m-%dT%H:%M:%fZ', scheduled_at)) AS job FROM blockers ORDER BY id))) + ) + FROM target +), 'null') AS sequence; diff --git a/internal/riveruidriver/riveruisqlite/internal/dbsqlc/sequence.sql.go b/internal/riveruidriver/riveruisqlite/internal/dbsqlc/sequence.sql.go new file mode 100644 index 00000000..4dfe247d --- /dev/null +++ b/internal/riveruidriver/riveruisqlite/internal/dbsqlc/sequence.sql.go @@ -0,0 +1,124 @@ +// Code generated by sqlc. DO NOT EDIT. +// versions: +// sqlc v1.31.0 +// source: sequence.sql + +package dbsqlc + +import ( + "context" +) + +const jobSequenceGet = `-- name: JobSequenceGet :one +WITH target AS ( + SELECT job.id, job.state, json_extract(job.metadata, '$.seq_key') AS seq_key + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.id = ?1 + AND json_type(job.metadata, '$.seq_key') IS NOT NULL + AND json_type(job.metadata, '$.seq_key') = 'text' + AND json_extract(job.metadata, '$.seq_key') <> '' +), +first_pending AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'pending' + AND json_type(job.metadata, '$.seq_key') IS NOT NULL + AND json_extract(job.metadata, '$.seq_key') = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +available_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'available' + AND json_type(job.metadata, '$.seq_key') IS NOT NULL + AND json_extract(job.metadata, '$.seq_key') = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +cancelled_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'cancelled' + AND json_type(job.metadata, '$.seq_key') IS NOT NULL + AND json_extract(job.metadata, '$.seq_key') = (SELECT seq_key FROM target) + AND job.id < (SELECT first_pending.id FROM first_pending) + AND COALESCE(json_extract(job.metadata, '$.seq_continue_cancelled'), 0) != 1 + ORDER BY job.id + LIMIT 1 +), +discarded_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'discarded' + AND json_type(job.metadata, '$.seq_key') IS NOT NULL + AND json_extract(job.metadata, '$.seq_key') = (SELECT seq_key FROM target) + AND job.id < (SELECT first_pending.id FROM first_pending) + AND COALESCE(json_extract(job.metadata, '$.seq_continue_discarded'), 0) != 1 + ORDER BY job.id + LIMIT 1 +), +retryable_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'retryable' + AND json_type(job.metadata, '$.seq_key') IS NOT NULL + AND json_extract(job.metadata, '$.seq_key') = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +running_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'running' + AND json_type(job.metadata, '$.seq_key') IS NOT NULL + AND json_extract(job.metadata, '$.seq_key') = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +scheduled_blocker AS ( + SELECT job.id, job.kind, job.queue, job.state, job.scheduled_at + FROM /* TEMPLATE: schema */river_job AS job + WHERE job.state = 'scheduled' + AND json_type(job.metadata, '$.seq_key') IS NOT NULL + AND json_extract(job.metadata, '$.seq_key') = (SELECT seq_key FROM target) + ORDER BY job.id + LIMIT 1 +), +blockers AS ( + SELECT id, kind, queue, state, scheduled_at FROM available_blocker + UNION ALL + SELECT id, kind, queue, state, scheduled_at FROM cancelled_blocker + UNION ALL + SELECT id, kind, queue, state, scheduled_at FROM discarded_blocker + UNION ALL + SELECT id, kind, queue, state, scheduled_at FROM retryable_blocker + UNION ALL + SELECT id, kind, queue, state, scheduled_at FROM running_blocker + UNION ALL + SELECT id, kind, queue, state, scheduled_at FROM scheduled_blocker +) +SELECT COALESCE(( + SELECT json_object( + 'job_id', target.id, + 'job_state', target.state, + 'key', target.seq_key, + 'first_pending', json((SELECT json_object('id', id, 'kind', kind, 'queue', queue, 'state', state, 'scheduled_at', strftime('%Y-%m-%dT%H:%M:%fZ', scheduled_at)) FROM first_pending)), + 'blockers', json((SELECT json_group_array(json(job)) FROM (SELECT json_object('id', id, 'kind', kind, 'queue', queue, 'state', state, 'scheduled_at', strftime('%Y-%m-%dT%H:%M:%fZ', scheduled_at)) AS job FROM blockers ORDER BY id))) + ) + FROM target +), 'null') AS sequence +` + +// Each probe constrains state and sequence key before ordering by ID. This +// matches River Pro's river_job_sequence_scheduling index and excludes completed +// history. Separate active-state probes avoid sorting an entire sequence. +// Terminal blockers must precede the first pending job and use their own +// continuation flags, matching the sequence supervisor. Active jobs block from +// anywhere in the sequence, including after its pending head. +func (q *Queries) JobSequenceGet(ctx context.Context, db DBTX, jobID int64) (interface{}, error) { + row := db.QueryRowContext(ctx, jobSequenceGet, jobID) + var sequence interface{} + err := row.Scan(&sequence) + return sequence, err +} diff --git a/internal/riveruidriver/riveruisqlite/internal/dbsqlc/sequence_test.go b/internal/riveruidriver/riveruisqlite/internal/dbsqlc/sequence_test.go new file mode 100644 index 00000000..37d5878a --- /dev/null +++ b/internal/riveruidriver/riveruisqlite/internal/dbsqlc/sequence_test.go @@ -0,0 +1,47 @@ +package dbsqlc + +import ( + "database/sql" + "strings" + "testing" + + "github.com/stretchr/testify/require" + _ "modernc.org/sqlite" +) + +func TestJobSequenceGetQueryPlan(t *testing.T) { + t.Parallel() + + ctx := t.Context() + db, err := sql.Open("sqlite", ":memory:") + require.NoError(t, err) + t.Cleanup(func() { require.NoError(t, db.Close()) }) + _, err = db.ExecContext(ctx, ` +CREATE TABLE river_job (id INTEGER PRIMARY KEY, kind TEXT, queue TEXT, state TEXT, scheduled_at TEXT, metadata TEXT); +CREATE INDEX river_job_sequence_scheduling ON river_job(state, json_extract(metadata, '$.seq_key'), id) WHERE json_type(metadata, '$.seq_key') IS NOT NULL; +CREATE INDEX river_job_sequence_first_pending ON river_job(json_extract(metadata, '$.seq_key'), id, scheduled_at) WHERE json_type(metadata, '$.seq_key') IS NOT NULL AND state = 'pending'; +CREATE INDEX river_job_sequence_latest_active ON river_job(json_extract(metadata, '$.seq_key'), id DESC, state) WHERE json_type(metadata, '$.seq_key') IS NOT NULL AND state NOT IN ('pending', 'completed'); +WITH RECURSIVE ids(id) AS (SELECT 1 UNION ALL SELECT id + 1 FROM ids WHERE id < 10000) +INSERT INTO river_job SELECT id, 'invoice', 'default', 'completed', '2026-11-13T12:00:00Z', '{"seq_key":"invoice"}' FROM ids; +INSERT INTO river_job VALUES (10001, 'invoice', 'default', 'cancelled', '2026-11-13T12:00:00Z', '{"seq_key":"invoice"}'); +INSERT INTO river_job VALUES (10002, 'invoice', 'default', 'pending', '2026-11-13T12:00:00Z', '{"seq_key":"invoice"}'); +ANALYZE; +`) + require.NoError(t, err) + rows, err := db.QueryContext(ctx, "EXPLAIN QUERY PLAN "+jobSequenceGet, int64(10002)) + require.NoError(t, err) + defer rows.Close() + scans := 0 + for rows.Next() { + var id, parent, unused int + var detail string + require.NoError(t, rows.Scan(&id, &parent, &unused, &detail)) + require.NotContains(t, detail, "SCAN job", "base-table reads must use sequence indexes") + if strings.HasPrefix(detail, "SEARCH job ") { + scans++ + require.Contains(t, detail, "USING") + } + } + require.NoError(t, rows.Err()) + require.GreaterOrEqual(t, scans, 8, "SQLite may inline the target CTE, repeating indexed PK lookups") +} diff --git a/internal/riveruidriver/riveruisqlite/internal/dbsqlc/sqlc.yaml b/internal/riveruidriver/riveruisqlite/internal/dbsqlc/sqlc.yaml index 00624ae4..cf368252 100644 --- a/internal/riveruidriver/riveruisqlite/internal/dbsqlc/sqlc.yaml +++ b/internal/riveruidriver/riveruisqlite/internal/dbsqlc/sqlc.yaml @@ -2,6 +2,7 @@ version: "2" sql: - engine: "sqlite" queries: + - sequence.sql - river_job.sql - river_job_dead_letter.sql schema: diff --git a/internal/riveruidriver/riveruisqlite/river_ui_sqlite_driver.go b/internal/riveruidriver/riveruisqlite/river_ui_sqlite_driver.go index 8e4a6096..af9656d8 100644 --- a/internal/riveruidriver/riveruisqlite/river_ui_sqlite_driver.go +++ b/internal/riveruidriver/riveruisqlite/river_ui_sqlite_driver.go @@ -290,3 +290,18 @@ func (e *Executor) JobDeadLetterAutocomplete(ctx context.Context, params *riveru slices.Sort(values) return values, nil } + +func (e *Executor) JobSequenceGet(ctx context.Context, params *riveruidriver.JobSequenceGetParams) (*riveruidriver.JobSequence, error) { + raw, err := dbsqlc.JobSequenceGetRiver(schemaTemplateParam(ctx, params.Schema), e.dbtx, params.ID) + if err != nil { + return nil, fmt.Errorf("error inspecting job sequence: %w", err) + } + var sequence *riveruidriver.JobSequence + if err := json.Unmarshal([]byte(raw), &sequence); err != nil { + return nil, fmt.Errorf("error decoding job sequence: %w", err) + } + if sequence != nil { + sequence.Normalize() + } + return sequence, nil +} diff --git a/internal/riveruidriver/sequence.go b/internal/riveruidriver/sequence.go new file mode 100644 index 00000000..35a043e0 --- /dev/null +++ b/internal/riveruidriver/sequence.go @@ -0,0 +1,63 @@ +package riveruidriver + +import ( + "cmp" + "slices" + "time" + + "github.com/riverqueue/river/rivertype" +) + +// JobSequenceGetParams identifies the job whose sequence should be inspected. +type JobSequenceGetParams struct { + ID int64 + Schema string +} + +// JobSequence contains a snapshot of the sequence's pending head and earliest +// blocker in each state. It deliberately excludes counts and completed history. +type JobSequence struct { + Blockers []*SequenceJob `json:"blockers"` + FirstPending *SequenceJob `json:"first_pending"` + JobID int64 `json:"job_id"` + JobState rivertype.JobState `json:"job_state"` + Key string `json:"key"` +} + +// Normalize orders blockers and normalizes timestamps across database drivers. +func (s *JobSequence) Normalize() { + slices.SortFunc(s.Blockers, func(a, b *SequenceJob) int { return cmp.Compare(a.ID, b.ID) }) + for _, job := range s.Blockers { + job.ScheduledAt = job.ScheduledAt.UTC() + } + if s.FirstPending != nil { + s.FirstPending.ScheduledAt = s.FirstPending.ScheduledAt.UTC() + } +} + +// WaitReason describes why the inspected job is pending. A later pending job +// still waits for the pending head even when that head is ready for promotion. +func (s *JobSequence) WaitReason() string { + if s.JobState != rivertype.JobStatePending { + return "none" + } + for _, job := range s.Blockers { + if job.State == rivertype.JobStateCancelled || job.State == rivertype.JobStateDiscarded { + return "halted" + } + } + if len(s.Blockers) > 0 || (s.FirstPending != nil && s.FirstPending.ID != s.JobID) { + return "waiting" + } + return "awaiting_promotion" +} + +// SequenceJob is the small set of fields needed to identify and explain a +// sequence blocker without loading its arguments, errors, or full metadata. +type SequenceJob struct { + ID int64 `json:"id"` + Kind string `json:"kind"` + Queue string `json:"queue"` + ScheduledAt time.Time `json:"scheduled_at"` + State rivertype.JobState `json:"state"` +} diff --git a/riverproui/endpoints.go b/riverproui/endpoints.go index 00cf7f4a..156136d3 100644 --- a/riverproui/endpoints.go +++ b/riverproui/endpoints.go @@ -119,6 +119,11 @@ func (e *endpoints[TTx]) Extensions(ctx context.Context) (map[string]bool, error return nil, err } + hasSequenceDiagnostics, err := prohandler.HasSequenceDiagnostics(ctx, execTx, schema) + if err != nil { + return nil, err + } + hasWorkflowV2Tables, err := prohandler.HasWorkflowV2Tables(ctx, execTx, schema) if err != nil { return nil, err @@ -131,6 +136,7 @@ func (e *endpoints[TTx]) Extensions(ctx context.Context) (map[string]bool, error "workflow_queries": hasWorkflowV2Tables, "has_producer_table": hasProducerTable, "has_sequence_table": hasSequenceTable, + "sequence_queries": hasSequenceDiagnostics, }, nil } @@ -167,6 +173,7 @@ func (e *endpoints[TTx]) MountEndpoints(archetype *baseservice.Archetype, logger apiendpoint.Mount(mux, prohandler.NewDeadLetterAutocompleteEndpoint(bundle), mountOpts), apiendpoint.Mount(mux, prohandler.NewDeadLetterJobGetEndpoint(bundle), mountOpts), apiendpoint.Mount(mux, prohandler.NewDeadLetterJobRetryEndpoint(bundle), mountOpts), + apiendpoint.Mount(mux, prohandler.NewJobSequenceGetEndpoint(bundle), mountOpts), apiendpoint.Mount(mux, prohandler.NewPeriodicJobListEndpoint(bundle), mountOpts), apiendpoint.Mount(mux, prohandler.NewProducerListEndpoint(bundle), mountOpts), apiendpoint.Mount(mux, prohandler.NewWorkflowCancelEndpoint(bundle), mountOpts), diff --git a/riverproui/internal/prohandler/dead_letter_endpoints.go b/riverproui/internal/prohandler/dead_letter_endpoints.go index 7de38e7d..c1114385 100644 --- a/riverproui/internal/prohandler/dead_letter_endpoints.go +++ b/riverproui/internal/prohandler/dead_letter_endpoints.go @@ -95,10 +95,10 @@ type deadLetterJobListEndpoint[TTx any] struct { } func NewDeadLetterJobListEndpoint[TTx any](bundle ProAPIBundle[TTx]) *deadLetterJobListEndpoint[TTx] { - return &deadLetterJobListEndpoint[TTx]{ProAPIBundle: bundle, uiDriver: deadLetterUIDriver(bundle.Driver.DatabaseName())} + return &deadLetterJobListEndpoint[TTx]{ProAPIBundle: bundle, uiDriver: uiDriverForDatabase(bundle.Driver.DatabaseName())} } -func deadLetterUIDriver(databaseName string) riveruidriver.Driver { +func uiDriverForDatabase(databaseName string) riveruidriver.Driver { var uiDriver riveruidriver.Driver switch databaseName { case riverdriver.DatabaseNamePostgres: @@ -274,7 +274,7 @@ type deadLetterAutocompleteEndpoint[TTx any] struct { } func NewDeadLetterAutocompleteEndpoint[TTx any](bundle ProAPIBundle[TTx]) *deadLetterAutocompleteEndpoint[TTx] { - return &deadLetterAutocompleteEndpoint[TTx]{ProAPIBundle: bundle, uiDriver: deadLetterUIDriver(bundle.Driver.DatabaseName())} + return &deadLetterAutocompleteEndpoint[TTx]{ProAPIBundle: bundle, uiDriver: uiDriverForDatabase(bundle.Driver.DatabaseName())} } func (*deadLetterAutocompleteEndpoint[TTx]) Meta() *apiendpoint.EndpointMeta { diff --git a/riverproui/internal/prohandler/sequence_endpoints.go b/riverproui/internal/prohandler/sequence_endpoints.go new file mode 100644 index 00000000..3ccf95c8 --- /dev/null +++ b/riverproui/internal/prohandler/sequence_endpoints.go @@ -0,0 +1,110 @@ +package prohandler + +import ( + "context" + "fmt" + "net/http" + "strconv" + "time" + + "github.com/riverqueue/apiframe/apiendpoint" + "github.com/riverqueue/apiframe/apierror" + "github.com/riverqueue/river/riverdriver" + "github.com/riverqueue/river/rivertype" + + "riverqueue.com/riverui/internal/riveruidriver" +) + +// HasSequenceDiagnostics reports whether the sequence scheduling index is +// installed. Table existence alone is insufficient to promise an indexed lookup. +func HasSequenceDiagnostics(ctx context.Context, exec riverdriver.Executor, schema string) (bool, error) { + return exec.IndexExists(ctx, &riverdriver.IndexExistsParams{Index: "river_job_sequence_scheduling", Schema: schema}) +} + +type jobSequenceGetEndpoint[TTx any] struct { + ProAPIBundle[TTx] + apiendpoint.Endpoint[jobSequenceGetRequest, jobSequenceResponse] + + uiDriver riveruidriver.Driver +} + +// NewJobSequenceGetEndpoint returns the sequence diagnostics endpoint. +func NewJobSequenceGetEndpoint[TTx any](bundle ProAPIBundle[TTx]) *jobSequenceGetEndpoint[TTx] { + return &jobSequenceGetEndpoint[TTx]{ProAPIBundle: bundle, uiDriver: uiDriverForDatabase(bundle.Driver.DatabaseName())} +} + +func (a *jobSequenceGetEndpoint[TTx]) Execute(ctx context.Context, req *jobSequenceGetRequest) (*jobSequenceResponse, error) { + // Keep a diagnostic request from occupying a connection indefinitely when + // a sequence contains an unusually large retained failure history. + ctx, cancel := context.WithTimeout(ctx, 5*time.Second) + defer cancel() + + supported, err := HasSequenceDiagnostics(ctx, a.DB, a.Client.Schema()) + if err != nil { + return nil, fmt.Errorf("error checking sequence index: %w", err) + } + if !supported { + return nil, apierror.NewBadRequest("Sequence diagnostics require River Pro's sequence scheduling index. Run the Pro migrations.") + } + + sequence, err := a.uiDriver.GetExecutor(a.DB).JobSequenceGet(ctx, &riveruidriver.JobSequenceGetParams{ + ID: req.JobID, Schema: a.Client.Schema(), + }) + if err != nil { + return nil, fmt.Errorf("error getting job sequence: %w", err) + } + if sequence == nil { + return nil, apierror.NewNotFoundf("Sequence for job %d not found.", req.JobID) + } + blockers := make([]*sequenceJobResponse, 0, len(sequence.Blockers)) + for _, job := range sequence.Blockers { + blockers = append(blockers, sequenceJobFromDriver(job)) + } + return &jobSequenceResponse{ + Blockers: blockers, + FirstPending: sequenceJobFromDriver(sequence.FirstPending), + JobID: sequence.JobID, + Key: sequence.Key, + WaitReason: sequence.WaitReason(), + }, nil +} + +func (*jobSequenceGetEndpoint[TTx]) Meta() *apiendpoint.EndpointMeta { + return &apiendpoint.EndpointMeta{Pattern: "GET /api/pro/jobs/{job_id}/sequence", StatusCode: http.StatusOK} +} + +type jobSequenceGetRequest struct { + JobID int64 `json:"-" validate:"required,min=1"` +} + +func (req *jobSequenceGetRequest) ExtractRaw(r *http.Request) error { + id, err := strconv.ParseInt(r.PathValue("job_id"), 10, 64) + if err != nil { + return apierror.NewBadRequestf("Couldn't convert job ID to int64: %s.", err) + } + req.JobID = id + return nil +} + +type jobSequenceResponse struct { + Blockers []*sequenceJobResponse `json:"blockers"` + FirstPending *sequenceJobResponse `json:"first_pending"` + JobID int64 `json:"job_id,string"` + Key string `json:"key"` + WaitReason string `json:"wait_reason"` +} + +type sequenceJobResponse struct { + ID int64 `json:"id,string"` + Kind string `json:"kind"` + Queue string `json:"queue"` + ScheduledAt time.Time `json:"scheduled_at"` + State rivertype.JobState `json:"state"` +} + +func sequenceJobFromDriver(job *riveruidriver.SequenceJob) *sequenceJobResponse { + if job == nil { + return nil + } + return &sequenceJobResponse{ID: job.ID, Kind: job.Kind, Queue: job.Queue, ScheduledAt: job.ScheduledAt, State: job.State} +} diff --git a/riverproui/internal/prohandler/sequence_endpoints_test.go b/riverproui/internal/prohandler/sequence_endpoints_test.go new file mode 100644 index 00000000..fd6d35d2 --- /dev/null +++ b/riverproui/internal/prohandler/sequence_endpoints_test.go @@ -0,0 +1,82 @@ +package prohandler + +import ( + "encoding/json" + "fmt" + "net/http" + "net/http/httptest" + "testing" + "time" + + "github.com/stretchr/testify/require" + + "github.com/riverqueue/apiframe/apitest" + "github.com/riverqueue/river/rivershared/util/dbutil" + "github.com/riverqueue/river/rivertype" + + "riverqueue.com/riverui/internal/riverinternaltest/testfactory" +) + +func TestJobSequenceGet(t *testing.T) { + t.Parallel() + + t.Run("Halted", func(t *testing.T) { + t.Parallel() + ctx := t.Context() + endpoint, bundle := setupEndpoint(ctx, t, NewJobSequenceGetEndpoint) + insert := func(id int64, state rivertype.JobState) { + params := testfactory.Job_Build(t, &testfactory.JobOpts{Metadata: []byte(`{"seq_key":"invoice"}`), State: &state}) + params.Schema = bundle.schema + if state == rivertype.JobStateCancelled { + params.FinalizedAt = new(time.Now()) + } + job, err := bundle.exec.JobInsertFull(ctx, params) + require.NoError(t, err) + require.NoError(t, bundle.exec.Exec(ctx, fmt.Sprintf("UPDATE %s.river_job SET id = %d WHERE id = %d", dbutil.SafeIdentifier(bundle.schema), id, job.ID))) + } + const blockerID int64 = 1970670598291982290 + insert(blockerID, rivertype.JobStateCancelled) + insert(blockerID+1, rivertype.JobStatePending) + resp, err := apitest.InvokeHandler(ctx, endpoint.Execute, testMountOpts(t), &jobSequenceGetRequest{JobID: blockerID + 1}) + require.NoError(t, err) + require.Equal(t, "halted", resp.WaitReason) + require.Equal(t, "invoice", resp.Key) + require.Equal(t, blockerID+1, resp.FirstPending.ID) + require.Len(t, resp.Blockers, 1) + require.Equal(t, blockerID, resp.Blockers[0].ID) + encoded, err := json.Marshal(resp) + require.NoError(t, err) + require.Contains(t, string(encoded), `"id":"1970670598291982290"`) + require.Contains(t, string(encoded), `"job_id":"1970670598291982291"`) + require.NotContains(t, string(encoded), `"metadata"`) + }) + + t.Run("Missing", func(t *testing.T) { + t.Parallel() + endpoint, _ := setupEndpoint(t.Context(), t, NewJobSequenceGetEndpoint) + _, err := apitest.InvokeHandler(t.Context(), endpoint.Execute, testMountOpts(t), &jobSequenceGetRequest{JobID: 9223372036854775807}) + require.ErrorContains(t, err, "not found") + }) + + t.Run("MissingIndex", func(t *testing.T) { + t.Parallel() + endpoint, bundle := setupEndpoint(t.Context(), t, NewJobSequenceGetEndpoint) + require.NoError(t, bundle.exec.Exec(t.Context(), "DROP INDEX "+dbutil.SafeIdentifier(bundle.schema)+".river_job_sequence_scheduling")) + _, err := apitest.InvokeHandler(t.Context(), endpoint.Execute, testMountOpts(t), &jobSequenceGetRequest{JobID: 1}) + require.ErrorContains(t, err, "sequence scheduling index") + }) + + t.Run("Validation", func(t *testing.T) { + t.Parallel() + for _, value := range []string{"not-a-number", "9223372036854775808"} { + req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/", nil) + req.SetPathValue("job_id", value) + require.Error(t, new(jobSequenceGetRequest).ExtractRaw(req)) + } + endpoint, _ := setupEndpoint(t.Context(), t, NewJobSequenceGetEndpoint) + for _, id := range []int64{0, -1} { + _, err := apitest.InvokeHandler(t.Context(), endpoint.Execute, testMountOpts(t), &jobSequenceGetRequest{JobID: id}) + require.Error(t, err) + } + }) +} diff --git a/riverproui/pro_handler_test.go b/riverproui/pro_handler_test.go index 9adf41d0..7bc492de 100644 --- a/riverproui/pro_handler_test.go +++ b/riverproui/pro_handler_test.go @@ -262,12 +262,19 @@ func TestProMountedEndpointResponses(t *testing.T) { "dead_letter_jobs": true, // dynamic "durable_periodic_jobs": true, // dynamic "has_producer_table": true, // dynamic + "sequence_queries": true, "has_sequence_table": true, // dynamic "producer_queries": true, // static "workflow_queries": true, // dynamic } require.Equal(t, expectedExtensions, resp.Extensions) + sequenceRecorder := httptest.NewRecorder() + sequenceReq := httptest.NewRequestWithContext(ctx, http.MethodGet, "/api/pro/jobs/9223372036854775807/sequence", nil) + bundle.handler.ServeHTTP(sequenceRecorder, sequenceReq) + require.Equal(t, http.StatusNotFound, sequenceRecorder.Result().StatusCode) + require.Contains(t, sequenceRecorder.Body.String(), "Sequence for job") + recorder = httptest.NewRecorder() req = httptest.NewRequestWithContext( ctx, diff --git a/src/components/JobDetail.tsx b/src/components/JobDetail.tsx index ce26a29e..7929d312 100644 --- a/src/components/JobDetail.tsx +++ b/src/components/JobDetail.tsx @@ -25,6 +25,7 @@ type JobDetailProps = { deleteFn: () => void; job: Job; retry: () => void; + sequenceDetails?: ReactNode; }; type JobDetailViewProps = { @@ -32,6 +33,7 @@ type JobDetailViewProps = { job: Job; // Shown under the heading, for context that applies to the whole job. notice?: ReactNode; + sequenceDetails?: ReactNode; title: string; }; @@ -40,6 +42,7 @@ export default function JobDetail({ deleteFn, job, retry, + sequenceDetails, }: JobDetailProps) { return ( } job={job} + sequenceDetails={sequenceDetails} title="Job Details" /> ); @@ -63,6 +67,7 @@ export function JobDetailView({ actions, job, notice, + sequenceDetails, title, }: JobDetailViewProps) { const featureEnabledWorkflows = useFeature("ENABLE_WORKFLOWS", true); @@ -185,6 +190,7 @@ export function JobDetailView({ )} + {sequenceDetails} diff --git a/src/components/SequenceDetails.test.tsx b/src/components/SequenceDetails.test.tsx new file mode 100644 index 00000000..1e1a730b --- /dev/null +++ b/src/components/SequenceDetails.test.tsx @@ -0,0 +1,113 @@ +import type { JobSequence, SequenceJob } from "@services/sequences"; + +import { JobState } from "@services/types"; +import { + createMemoryHistory, + createRootRoute, + createRoute, + createRouter, + Outlet, + RouterProvider, +} from "@tanstack/react-router"; +import { act, render, screen } from "@testing-library/react"; +import { expect, test } from "vitest"; + +import SequenceDetails from "./SequenceDetails"; + +const pending: SequenceJob = { + id: 1970670598291982291n, + kind: "update_invoice", + queue: "invoices", + scheduledAt: new Date("2026-11-13T12:00:00Z"), + state: JobState.Pending, +}; + +const sequence: JobSequence = { + blockers: [ + { + ...pending, + id: pending.id - 1n, + kind: "process_invoice", + state: JobState.Cancelled, + }, + ], + firstPending: pending, + jobId: pending.id, + key: "invoice-sequence-key", + waitReason: "halted", +}; + +async function renderSequence(value: JobSequence) { + const root = createRootRoute({ component: Outlet }); + const index = createRoute({ + component: () => ( + + ), + getParentRoute: () => root, + path: "/", + }); + const job = createRoute({ getParentRoute: () => root, path: "/jobs/$jobId" }); + const router = createRouter({ + history: createMemoryHistory({ initialEntries: ["/"] }), + routeTree: root.addChildren([index, job]), + }); + await act(async () => { + render(); + }); +} + +test("identifies a halted sequence and links to its blocker and pending head", async () => { + await renderSequence(sequence); + expect( + screen.getByText("Sequence halted by a failed job"), + ).toBeInTheDocument(); + expect( + screen.getByRole("link", { name: "#1970670598291982290" }), + ).toHaveAttribute("href", "/jobs/1970670598291982290"); + expect( + screen.getByRole("link", { name: "#1970670598291982291" }), + ).toHaveAttribute("href", "/jobs/1970670598291982291"); + expect(screen.getByText("cancelled")).toBeInTheDocument(); + expect(screen.getByText("process_invoice · invoices")).toBeInTheDocument(); + expect(screen.getByText("(this job)")).toBeInTheDocument(); +}); + +test("distinguishes normal waiting from a halted sequence", async () => { + await renderSequence({ + ...sequence, + blockers: [{ ...sequence.blockers[0]!, state: JobState.Running }], + waitReason: "waiting", + }); + expect( + screen.getByText("Waiting for jobs in this sequence"), + ).toBeInTheDocument(); + expect(screen.getByText("running")).toBeInTheDocument(); + expect( + screen.queryByText("Sequence halted by a failed job"), + ).not.toBeInTheDocument(); +}); + +test("shows the pending head when it is awaiting scheduling", async () => { + await renderSequence({ + ...sequence, + blockers: [], + waitReason: "awaiting_promotion", + }); + expect( + screen.getByText("Waiting for sequence scheduling"), + ).toBeInTheDocument(); + expect(screen.getAllByRole("link")).toHaveLength(1); + expect(screen.queryByText("Next pending job")).not.toBeInTheDocument(); +}); + +test("does not present stale blockers when refreshing fails", () => { + render( + , + ); + expect(screen.getByRole("status")).toHaveTextContent( + "Sequence details could not be loaded.", + ); + expect( + screen.queryByText("Sequence halted by a failed job"), + ).not.toBeInTheDocument(); +}); diff --git a/src/components/SequenceDetails.tsx b/src/components/SequenceDetails.tsx new file mode 100644 index 00000000..ffe2b8ce --- /dev/null +++ b/src/components/SequenceDetails.tsx @@ -0,0 +1,126 @@ +import type { JobSequence, SequenceJob } from "@services/sequences"; + +import { Badge } from "@components/Badge"; +import CopyableHeadingText from "@components/CopyableHeadingText"; +import RelativeTimeFormatter from "@components/RelativeTimeFormatter"; +import { JobState } from "@services/types"; +import { Link } from "@tanstack/react-router"; + +type SequenceDetailsProps = { + error?: boolean; + sequence?: JobSequence; + sequenceKey: string; +}; + +const reasonLabels: Record = { + awaiting_promotion: "Waiting for sequence scheduling", + halted: "Sequence halted by a failed job", + none: "This job is not pending", + waiting: "Waiting for jobs in this sequence", +}; + +export default function SequenceDetails({ + error, + sequence, + sequenceKey, +}: SequenceDetailsProps) { + const head = sequence?.blockers[0] ?? sequence?.firstPending; + const otherBlockers = sequence?.blockers.filter((job) => job.id !== head?.id); + + return ( +
+

+ Sequence +

+
+ +
+ {error ? ( +

Sequence details could not be loaded.

+ ) : !sequence ? ( +

Loading sequence details…

+ ) : ( +
+
+
Wait reason
+
{reasonLabels[sequence.waitReason]}
+
+ {head ? ( +
+
Sequence head
+
+ +
+
+ ) : ( +
+
Sequence head
+
No pending or active jobs
+
+ )} + {sequence.firstPending && sequence.firstPending.id !== head?.id && ( +
+
Next pending job
+
+ +
+
+ )} + {otherBlockers && otherBlockers.length > 0 && ( +
+
Other blocking jobs
+
+ {otherBlockers.map((job) => ( + + ))} +
+
+ )} +
+ )} +
+ ); +} + +function SequenceJobSummary({ + currentJobId, + job, +}: { + currentJobId: bigint; + job: SequenceJob; +}) { + return ( +
+
+ + #{job.id.toString()} + + {job.state} + {job.id === currentJobId && (this job)} +
+

+ {job.kind} · {job.queue} +

+ {(job.state === JobState.Retryable || + job.state === JobState.Scheduled) && ( +

+ Scheduled +

+ )} +
+ ); +} diff --git a/src/components/WorkflowDetail.test.tsx b/src/components/WorkflowDetail.test.tsx index 06afe36e..cea8d198 100644 --- a/src/components/WorkflowDetail.test.tsx +++ b/src/components/WorkflowDetail.test.tsx @@ -47,6 +47,7 @@ const features: Features = { hasSequenceTable: false, jobListHideArgsByDefault: false, producerQueries: true, + sequenceQueries: false, workflowQueries: true, }; diff --git a/src/routes/jobs/$jobId.tsx b/src/routes/jobs/$jobId.tsx index f3a8415f..87f1407e 100644 --- a/src/routes/jobs/$jobId.tsx +++ b/src/routes/jobs/$jobId.tsx @@ -1,9 +1,16 @@ import JobDetail from "@components/JobDetail"; import JobNotFound from "@components/JobNotFound"; +import SequenceDetails from "@components/SequenceDetails"; +import { useFeatures } from "@contexts/Features.hook"; import { useRefreshSetting } from "@contexts/RefreshSettings.hook"; import { refreshQueryOptions } from "@contexts/RefreshSettings.query"; import { useRetryJobs } from "@hooks/use-retry-jobs"; import { cancelJobs, deleteJobs, getJob, getJobKey } from "@services/jobs"; +import { + getJobSequence, + getJobSequenceKey, + sequenceKeyFromMetadata, +} from "@services/sequences"; import { toastError } from "@services/toast"; import { JobState } from "@services/types"; import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"; @@ -47,7 +54,7 @@ export const Route = createFileRoute("/jobs/$jobId")({ component: JobComponent, }); -function JobComponent() { +export function JobComponent() { const { jobId } = Route.useParams(); const navigate = Route.useNavigate(); const { queryOptions } = Route.useRouteContext(); @@ -62,6 +69,24 @@ function JobComponent() { const queryClient = useQueryClient(); const jobQuery = useQuery(queryOptionsWithRefresh); + const { features } = useFeatures(); + const sequenceKey = + jobQuery.data && sequenceKeyFromMetadata(jobQuery.data.metadata); + const sequenceEnabled = features.sequenceQueries && !!sequenceKey; + const sequenceQuery = useQuery({ + queryKey: getJobSequenceKey(jobId), + queryFn: getJobSequence, + enabled: sequenceEnabled, + ...refreshQueryOptions(refreshSettings.intervalMs), + }); + + const invalidateJob = () => + Promise.all([ + queryClient.invalidateQueries({ + queryKey: queryOptionsWithRefresh.queryKey, + }), + queryClient.invalidateQueries({ queryKey: getJobSequenceKey(jobId) }), + ]); const cancelMutation = useMutation({ mutationFn: async (_variables, context) => @@ -72,9 +97,7 @@ function JobComponent() { message: "Job cancelled", duration: 2000, }); - return queryClient.invalidateQueries({ - queryKey: queryOptionsWithRefresh.queryKey, - }); + return invalidateJob(); }, }); @@ -96,9 +119,7 @@ function JobComponent() { const retryMutation = useRetryJobs({ onSuccess: () => { - return queryClient.invalidateQueries({ - queryKey: queryOptionsWithRefresh.queryKey, - }); + return invalidateJob(); }, successMessage: "Job enqueued for retry", }); @@ -115,6 +136,15 @@ function JobComponent() { deleteFn={deleteMutation.mutate} job={job} retry={() => retryMutation.mutate([jobId])} + sequenceDetails={ + sequenceEnabled && sequenceKey ? ( + + ) : undefined + } /> ); } diff --git a/src/routes/jobs/jobSequence.test.tsx b/src/routes/jobs/jobSequence.test.tsx new file mode 100644 index 00000000..cb146e32 --- /dev/null +++ b/src/routes/jobs/jobSequence.test.tsx @@ -0,0 +1,122 @@ +import type { ReactNode } from "react"; + +import { JobComponent, Route } from "@routes/jobs/$jobId"; +import { getJobKey } from "@services/jobs"; +import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; +import { jobFactory } from "@test/factories/job"; +import { createFeatures } from "@test/utils/features"; +import { fireEvent, render, screen, waitFor } from "@testing-library/react"; +import { afterEach, beforeEach, expect, test, vi } from "vitest"; + +const { getSequence, featureState, getJob } = vi.hoisted(() => ({ + featureState: { enabled: true }, + getJob: vi.fn(), + getSequence: vi.fn(), +})); + +vi.mock("@contexts/Features.hook", () => ({ + useFeatures: () => ({ + features: createFeatures({ sequenceQueries: featureState.enabled }), + }), +})); +vi.mock("@contexts/RefreshSettings.hook", () => ({ + useRefreshSetting: () => ({ intervalMs: 0 }), +})); +vi.mock("@services/sequences", async (original) => ({ + ...(await original()), + getJobSequence: getSequence, +})); +vi.mock("@components/JobDetail", () => ({ + default: ({ + retry, + sequenceDetails, + }: { + retry: () => void; + sequenceDetails?: ReactNode; + }) => ( +
+ Job details + {sequenceDetails} +
+ ), +})); +vi.mock("@components/SequenceDetails", () => ({ + default: ({ + error, + sequence, + }: { + error?: boolean; + sequence?: { waitReason: string }; + }) =>
{error ? "Diagnostics unavailable" : sequence?.waitReason}
, +})); +vi.mock("@hooks/use-retry-jobs", () => ({ + useRetryJobs: ({ onSuccess }: { onSuccess: () => void }) => ({ + mutate: onSuccess, + }), +})); + +const job = jobFactory.pending().build({ metadata: { seq_key: "invoice" } }); + +beforeEach(() => { + featureState.enabled = true; + getJob.mockReset().mockResolvedValue(job); + getSequence.mockReset().mockResolvedValue({ + blockers: [], + firstPending: null, + jobId: job.id, + key: "invoice", + waitReason: "waiting", + }); + vi.spyOn(Route, "useParams").mockReturnValue({ jobId: job.id }); + vi.spyOn(Route, "useNavigate").mockReturnValue(vi.fn()); + vi.spyOn(Route, "useRouteContext").mockReturnValue({ + queryOptions: { queryKey: getJobKey(job.id), queryFn: getJob }, + }); +}); + +afterEach(() => { + vi.restoreAllMocks(); +}); + +function renderJob() { + const client = new QueryClient({ + defaultOptions: { queries: { retry: false } }, + }); + render( + + + , + ); + return client; +} + +test("loads diagnostics for a sequence job and refreshes them after retry", async () => { + renderJob(); + await screen.findByText("waiting"); + expect(getSequence).toHaveBeenCalledTimes(1); + fireEvent.click(screen.getByRole("button", { name: "Retry" })); + await waitFor(() => { + expect(getSequence).toHaveBeenCalledTimes(2); + }); +}); + +test("does not request diagnostics from a backend without sequence support", async () => { + featureState.enabled = false; + renderJob(); + await screen.findByText("Job details"); + expect(getSequence).not.toHaveBeenCalled(); +}); + +test("does not request diagnostics for an ordinary job", async () => { + getJob.mockResolvedValue({ ...job, metadata: {} }); + renderJob(); + await screen.findByText("Job details"); + expect(getSequence).not.toHaveBeenCalled(); +}); + +test("keeps the job page usable when sequence diagnostics fail", async () => { + getSequence.mockRejectedValue(new Error("Query timed out")); + renderJob(); + await screen.findByText("Diagnostics unavailable"); + expect(screen.getByText("Job details")).toBeInTheDocument(); +}); diff --git a/src/services/features.test.ts b/src/services/features.test.ts index a33d9e70..26eaa864 100644 --- a/src/services/features.test.ts +++ b/src/services/features.test.ts @@ -22,6 +22,7 @@ describe("apiFeaturesToFeatures", () => { hasSequenceTable: false, jobListHideArgsByDefault: true, producerQueries: true, + sequenceQueries: false, workflowQueries: true, }; @@ -46,6 +47,7 @@ describe("apiFeaturesToFeatures", () => { hasSequenceTable: false, jobListHideArgsByDefault: false, producerQueries: false, + sequenceQueries: false, workflowQueries: false, }; diff --git a/src/services/features.ts b/src/services/features.ts index 20254d8f..4da4c8eb 100644 --- a/src/services/features.ts +++ b/src/services/features.ts @@ -19,6 +19,7 @@ const KNOWN_EXTENSIONS = [ "dead_letter_jobs", "durable_periodic_jobs", "producer_queries", + "sequence_queries", "workflow_queries", "has_producer_table", "has_sequence_table", diff --git a/src/services/sequences.test.ts b/src/services/sequences.test.ts new file mode 100644 index 00000000..d067f414 --- /dev/null +++ b/src/services/sequences.test.ts @@ -0,0 +1,40 @@ +import { JobState } from "@services/types"; +import { expect, test } from "vitest"; + +import { jobSequenceFromAPI, sequenceKeyFromMetadata } from "./sequences"; + +test("preserves sequence job IDs beyond the JavaScript integer range", () => { + const sequence = jobSequenceFromAPI({ + blockers: [ + { + id: "1970670598291982290", + kind: "invoice", + queue: "default", + scheduled_at: "2026-11-13T12:00:00Z", + state: JobState.Retryable, + }, + ], + first_pending: null, + job_id: "1970670598291982291", + key: "invoice", + wait_reason: "waiting", + }); + expect(sequence.jobId).toBe(1970670598291982291n); + expect(sequence.blockers[0]?.id).toBe(1970670598291982290n); + expect(sequence.blockers[0]?.scheduledAt).toEqual( + new Date("2026-11-13T12:00:00Z"), + ); +}); + +test("only requests sequence diagnostics for a nonempty sequence key", () => { + expect(sequenceKeyFromMetadata({ seq_key: "invoice" })).toBe("invoice"); + for (const metadata of [ + {}, + { seq_key: null }, + { seq_key: "" }, + { seq_key: 123 }, + { workflow_id: "workflow" }, + ]) { + expect(sequenceKeyFromMetadata(metadata)).toBeUndefined(); + } +}); diff --git a/src/services/sequences.ts b/src/services/sequences.ts new file mode 100644 index 00000000..5cd189a8 --- /dev/null +++ b/src/services/sequences.ts @@ -0,0 +1,81 @@ +import type { QueryFunction } from "@tanstack/react-query"; + +import { API } from "@utils/api"; + +import type { JobState } from "./types"; + +export type JobSequence = { + blockers: SequenceJob[]; + firstPending: null | SequenceJob; + jobId: bigint; + key: string; + waitReason: "awaiting_promotion" | "halted" | "none" | "waiting"; +}; + +export type JobSequenceFromAPI = { + blockers: SequenceJobFromAPI[]; + first_pending: null | SequenceJobFromAPI; + job_id: string; + key: string; + wait_reason: JobSequence["waitReason"]; +}; + +export type SequenceJob = { + id: bigint; + kind: string; + queue: string; + scheduledAt: Date; + state: JobState; +}; + +type SequenceJobFromAPI = { + id: string; + scheduled_at: string; +} & Omit; + +export const sequenceKeyFromMetadata = ( + metadata: object, +): string | undefined => { + if ( + typeof metadata === "object" && + metadata !== null && + "seq_key" in metadata && + typeof metadata.seq_key === "string" && + metadata.seq_key.length > 0 + ) { + return metadata.seq_key; + } + return undefined; +}; + +const sequenceJobFromAPI = (job: SequenceJobFromAPI): SequenceJob => ({ + id: BigInt(job.id), + kind: job.kind, + queue: job.queue, + scheduledAt: new Date(job.scheduled_at), + state: job.state, +}); + +export const jobSequenceFromAPI = ( + sequence: JobSequenceFromAPI, +): JobSequence => ({ + blockers: sequence.blockers.map(sequenceJobFromAPI), + firstPending: sequence.first_pending + ? sequenceJobFromAPI(sequence.first_pending) + : null, + jobId: BigInt(sequence.job_id), + key: sequence.key, + waitReason: sequence.wait_reason, +}); + +export const getJobSequenceKey = (jobId: bigint) => + ["jobSequence", jobId.toString()] as const; + +export const getJobSequence: QueryFunction< + JobSequence, + ReturnType +> = async ({ queryKey: [, jobId], signal }) => + API.get( + { path: `/pro/jobs/${jobId}/sequence` }, + { signal }, + ).then(jobSequenceFromAPI); diff --git a/src/test/utils/features.ts b/src/test/utils/features.ts index aed5d078..5ad7d0ed 100644 --- a/src/test/utils/features.ts +++ b/src/test/utils/features.ts @@ -9,6 +9,7 @@ export const createFeatures = ( hasSequenceTable: false, jobListHideArgsByDefault: false, producerQueries: false, + sequenceQueries: false, workflowQueries: false, ...overrides, }); From 38adf721abce514815d6bc377fe05f56082c6d96 Mon Sep 17 00:00:00 2001 From: Brandur Date: Sun, 15 Nov 2026 00:35:25 -0600 Subject: [PATCH 2/3] Build Pro UI against local modules The Pro module needs the new sequence queries from this checkout, but standalone module builds resolve the older published UI dependency. Create a local workspace for tests, lint, and the Pro Docker build so they use the checked-out modules without adding release-incompatible replace directives. --- .gitignore | 2 ++ Dockerfile.pro | 3 +++ Makefile | 12 +++++++++--- 3 files changed, 14 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index b618f663..9ed41e6a 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,8 @@ .tool-versions /riverui /riverproui/riverproui +/go.work +/go.work.sum # Logs logs diff --git a/Dockerfile.pro b/Dockerfile.pro index 75c26eb4..7cb9e801 100644 --- a/Dockerfile.pro +++ b/Dockerfile.pro @@ -38,6 +38,9 @@ COPY riverproui/ riverproui/ COPY --from=build-ui /app/dist ./dist +# Build both modules from this checkout, including unreleased shared UI queries. +RUN go work init . ./riverproui + # Build the riverproui binary WORKDIR /go/src/riverui/riverproui # Pass metadata from the original checkout; this partial copy is not a Git checkout. diff --git a/Makefile b/Makefile index dce6269c..c688012a 100644 --- a/Makefile +++ b/Makefile @@ -7,6 +7,12 @@ clean: # consider the current module, so they must run separately for every module. submodules := $(shell find . -name 'go\.mod' -exec dirname {} \;) +# Tests and lint must see changes in sibling modules before they're released. +# Keep this local to the checkout so published modules remain go-installable. +.PHONY: workspace +workspace: + @if [ -z "$$(go env GOWORK)" ]; then go work init $(submodules); fi + .PHONY: dev dev: fake_assets npm run dev @@ -46,21 +52,21 @@ docker-db/down: # produce the best/most comprehensible output by far (e.g. compared to a shell # loop). .PHONY: lint -lint:: ## Run linter (golangci-lint) for all submodules +lint:: workspace ## Run linter (golangci-lint) for all submodules define lint-target lint:: ; cd $1 && golangci-lint run --fix endef $(foreach mod,$(submodules),$(eval $(call lint-target,$(mod)))) .PHONY: test -test:: ## Run test suite for all submodules +test:: workspace ## Run test suite for all submodules define test-target test:: ; cd $1 && go test ./... -timeout 2m endef $(foreach mod,$(submodules),$(eval $(call test-target,$(mod)))) .PHONY: test/race -test/race:: ## Run test suite for all submodules with race detector +test/race:: workspace ## Run test suite for all submodules with race detector define test-race-target test/race:: ; cd $1 && go test ./... -race -timeout 2m endef From 4e096a37883b8193cf90a0eb163a68c09950671c Mon Sep 17 00:00:00 2001 From: Brandur Date: Sun, 15 Nov 2026 00:35:37 -0600 Subject: [PATCH 3/3] Fix sequence text colors and changelog link Give sequence details explicit text colors so labels and wait reasons remain readable in light and dark themes. Link the changelog entry to PR #739. --- CHANGELOG.md | 2 +- src/components/SequenceDetails.tsx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8cd7cf7a..ad33bcce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- Show sequence wait reasons, the sequence head, and blocking jobs with links on job detail pages. Diagnostics use sequence scheduling indexes and exclude completed job history. [PR #XXX](https://github.com/riverqueue/riverui/pull/XXX). +- Show sequence wait reasons, the sequence head, and blocking jobs with links on job detail pages. Diagnostics use sequence scheduling indexes and exclude completed job history. [PR #739](https://github.com/riverqueue/riverui/pull/739). ## [v0.22.0] - 2026-10-24 diff --git a/src/components/SequenceDetails.tsx b/src/components/SequenceDetails.tsx index ffe2b8ce..b30642b4 100644 --- a/src/components/SequenceDetails.tsx +++ b/src/components/SequenceDetails.tsx @@ -30,7 +30,7 @@ export default function SequenceDetails({ return (

Sequence