Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@
.tool-versions
/riverui
/riverproui/riverproui
/go.work
/go.work.sum

# Logs
logs
Expand Down
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions Dockerfile.pro
Original file line number Diff line number Diff line change
Expand Up @@ -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

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Codex keeps finding workarounds like this one to CI passing properly when API changes between UI and Pro UI. This seems to work okay and gets CI to pass, so left it.


# Build the riverproui binary
WORKDIR /go/src/riverui/riverproui
# Pass metadata from the original checkout; this partial copy is not a Git checkout.
Expand Down
12 changes: 9 additions & 3 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions internal/riveruidriver/river_ui_driver_interface.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 (
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
142 changes: 142 additions & 0 deletions internal/riveruidriver/riveruidrivertest/sequence.go
Original file line number Diff line number Diff line change
@@ -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())
})
})
}

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
105 changes: 105 additions & 0 deletions internal/riveruidriver/riveruipostgres/internal/dbsqlc/sequence.sql
Original file line number Diff line number Diff line change
@@ -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;
Loading
Loading