Documentation
¶
Overview ¶
Package status implements the typed task-status publisher for sqi-worker.
A Publisher publishes task state-transition messages to the task.status.<job> NATS subject. It covers the four transitions the worker is responsible for: "running", "succeeded", "failed", and "canceled".
Fields ¶
Every message includes worker_id (injected from Config.WorkerID) and last_progress (the most-recently seen openjd_progress value, passed explicitly by the caller so the publisher remains stateless).
Retry logic ¶
[Publisher.publishWithRetry] retries transient NATS publish failures up to Config.MaxRetries times with exponential backoff starting at Config.RetryDelay. If the caller's context is canceled during a retry wait the retries are aborted immediately. After all retries are exhausted the failure is logged at warning level and the function returns — status loss is preferable to deadlocking the shutdown sequence.
Shutdown flush ¶
Publisher.ShutdownFailed publishes a "failed" status with message "worker_shutdown" for every task in a provided list. It must be called before draining the NATS connection so that the server learns about the task failures immediately rather than waiting for the heartbeat-timeout sweep.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// WorkerID is embedded in every outgoing status message.
WorkerID string
// MaxRetries is the number of retry attempts after an initial publish
// failure. Default: 3.
MaxRetries int
// RetryDelay is the base backoff duration before the first retry.
// Each subsequent retry doubles the delay (exponential backoff).
// Default: 100 ms.
RetryDelay time.Duration
}
Config holds tunable parameters for a Publisher. Zero-value fields are replaced with package defaults when New is called.
type Publisher ¶
type Publisher struct {
// contains filtered or unexported fields
}
Publisher publishes typed task-status messages to task.status.<job>.
It injects worker_id and last_progress into every message and retries transient NATS publish failures with exponential backoff.
Publisher is safe for concurrent use from multiple goroutines.
func New ¶
New returns a ready-to-use Publisher. Any zero or negative fields in cfg are replaced with defaults before use.
func (*Publisher) Running ¶
func (p *Publisher) Running( ctx context.Context, msg *protocol.AssignMsg, sessionID string, lastProgress *int, at time.Time, )
Running publishes a "running" status message immediately after the task process is successfully launched.
lastProgress is the most-recently seen openjd_progress value for this attempt, or nil if none has been emitted yet. For the initial "running" publish (before any process output is received) this is always nil.
func (*Publisher) ShutdownFailed ¶
func (p *Publisher) ShutdownFailed(ctx context.Context, tasks []ShutdownTask)
ShutdownFailed publishes a "failed" status with message "worker_shutdown" for every task in tasks.
This MUST be called before draining the NATS connection during worker shutdown so the server learns about task failures immediately rather than waiting for the heartbeat-timeout sweep to fire.
ctx should carry a deadline so the total flush time is bounded even if all retries are exhausted. Each publish uses publishWithRetry; if the context deadline is reached or all retries are exhausted the error is logged and the function proceeds to the next task — all tasks are attempted regardless of individual publish failures.
func (*Publisher) Terminal ¶
func (p *Publisher) Terminal( ctx context.Context, msg *protocol.AssignMsg, sessionID, status string, exitCode *int, failureReason string, lastProgress *int, at time.Time, )
Terminal publishes a terminal status message: "succeeded", "failed", or "canceled".
exitCode must be non-nil for "succeeded" and "failed" states; it should be nil for "canceled" where a meaningful exit code is unavailable (the process was killed by a signal, leaving no application exit code). failureReason is attached as the Message field for "failed" messages; it is ignored for other states. lastProgress is the most-recently seen openjd_progress value, or nil.
Source Files