pgqueue enhancements and CLI tool

[djthorpe]

This pull request implements significant enhancements to the PostgreSQL-backed task queue system, focusing on API improvements, a new command-line interface, and better documentation.

Key Changes:

• Simplified ticker polling algorithm that drains matured tickers immediately instead of using adaptive timing
• Refactored task retention API from query parameter-based to path-based routing (GET /task/{queue}?worker=XX)
• Unified task completion interface with a single ReleaseTask method using a fail boolean flag
• Added comprehensive CLI tool (cmd/pgqueue) for server and client operations
• Enhanced error handling throughout the codebase using httpresponse.Err* patterns
• Improved namespace listing to include namespaces with only tickers

[Copilot]

Pull request overview

This pull request implements significant enhancements to the PostgreSQL-backed task queue system, focusing on API improvements, a new command-line interface, and better documentation.

Key Changes:

• Simplified ticker polling algorithm that drains matured tickers immediately instead of using adaptive timing
• Refactored task retention API from query parameter-based to path-based routing (GET /task/{queue}?worker=XX)
• Unified task completion interface with a single ReleaseTask method using a fail boolean flag
• Added comprehensive CLI tool (cmd/pgqueue) for server and client operations
• Enhanced error handling throughout the codebase using httpresponse.Err* patterns
• Improved namespace listing to include namespaces with only tickers

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pkg/queue/ticker.go	Simplified RunTickerLoop with immediate drain strategy when tickers are found
pkg/queue/task.go	Added ListTasks method for filtering and pagination
pkg/queue/schema/task.go	Replaced fmt.Errorf with httpresponse error types for consistent error handling
pkg/queue/httphandler/task.go	Refactored API routing to use path parameters for queue names and task IDs
pkg/queue/httphandler/ticker.go	Updated to use schema.TickerPeriod constant
pkg/queue/httphandler/frontend_excluded.go	New fallback handler for when frontend is not included
pkg/queue/httphandler/doc.go	Updated documentation to reflect new API structure
pkg/queue/httpclient/task.go	Unified ReleaseTask method replacing separate CompleteTask; added ListTasks
pkg/queue/httpclient/queue.go	Removed deprecated CleanQueue method
pkg/queue/httpclient/opts.go	Added WithOffset, WithLimit, and WithStatus helper functions
pkg/queue/httpclient/*_test.go	Updated tests for new API patterns and added comprehensive ticker tests
pkg/queue/httphandler/task_test.go	Removed DELETE method test as API no longer supports it
pkg/queue/sql/queries.sql	Enhanced namespace_list query to include ticker-only namespaces
cmd/pgqueue/*.go	New comprehensive CLI tool with commands for all queue operations
opts.go	Added WithApplicationName option for connection identification
go.mod	Updated dependencies including grpc-ecosystem packages
doc.go	Removed root-level package doc (superseded by comprehensive READMEs)
README.md	Improved documentation formatting and added new WithApplicationName option
pkg/queue/README.md	New comprehensive documentation for the queue package with architecture, examples, and CLI usage

Comments suppressed due to low confidence (1)

pkg/queue/httphandler/task.go:55

• The routing logic has a potential ambiguity issue. The code uses a single path parameter {queue_or_id} to handle both queue names (for GET) and task IDs (for PATCH). The GET handler checks if the path value is a valid identifier and rejects it if not. However, this means GET requests with numeric paths will be rejected as invalid queue names, when they might be intended as task IDs.

Consider what happens with GET /task/12345?worker=XX - this will fail with "invalid queue name" because "12345" is not a valid identifier. While the API design may intend for queue names to never be purely numeric, this creates a confusing error message for users.

A clearer approach would be to either:

1. Use different path patterns (e.g., /task/retain/{queue} for retention, /task/{id} for release)
2. Check the HTTP method before validating the path value format
3. Provide a more descriptive error that explains queue names cannot be numeric

	router.HandleFunc(joinPath(prefix, "task/{queue_or_id}"), func(w http.ResponseWriter, r *http.Request) {
		pathValue := r.PathValue("queue_or_id")

		switch r.Method {
		case http.MethodGet:
			if !types.IsIdentifier(pathValue) {
				_ = httpresponse.Error(w, httpresponse.ErrBadRequest.With("invalid queue name"), pathValue)
				return
			}
			_ = taskRetain(w, r, manager, pathValue)
		case http.MethodPatch:
			id, err := strconv.ParseUint(pathValue, 10, 64)
			if err != nil {
				_ = httpresponse.Error(w, httpresponse.ErrBadRequest.With("invalid task id"), pathValue)
				return
			}
			_ = taskRelease(w, r, manager, id)
		default:
			_ = httpresponse.Error(w, httpresponse.Err(http.StatusMethodNotAllowed), r.Method)
		}
	})

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.