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/CHANGELOG.md b/CHANGELOG.md index fa46e80c..ad33bcce 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 #739](https://github.com/riverqueue/riverui/pull/739). + ## [v0.22.0] - 2026-10-24 ### Added 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 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..b30642b4 --- /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, });