Documentation
¶
Overview ¶
Package workers provides a long-poll runtime for BPMN external service tasks. Register a handler per task type, then call Run; the runtime owns polling, lock heartbeats, dispatch, and outcome mapping (Complete on success, ThrowError on a BpmnError, ThrowError with a generic code on any other handler error).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HandleTyped ¶
func HandleTyped[T any](w *Worker, taskType string, handler func(ctx context.Context, job *Job, in T) (variables.Vars, error), opts ...HandleOption)
HandleTyped registers a handler that decodes the job's input variables into a value of type T before invoking handler. Use it for opt-in typed dispatch when the producing service task has a known variable schema.
Types ¶
type BpmnError ¶
BpmnError is a typed error a handler can return to fail a job with a BPMN error code. The runtime translates it into a ThrowError call against the originating service task - matching boundary error events on the task can then route the exception in the model.
Variables, when provided, are merged into the instance scope as part of the error throw.
func NewBpmnError ¶
NewBpmnError constructs a BpmnError. Pass nil for vars when there are no supplementary variables.
type Config ¶
type Config struct {
// ClientID is the worker's stable identity. Used to attribute job locks
// and counted as one of the active workers per task type. If empty,
// derived from the host name.
ClientID string
// Logger receives lifecycle messages (poll errors, fatal handler errors).
// Nil disables logging.
Logger *log.Logger
// MaxErrorMessageBytes caps the byte length of the auto-built
// WORKER_ERROR message attached when a handler returns a non-BpmnError.
// Zero falls back to 2048. User-thrown BpmnError variables are not clamped.
MaxErrorMessageBytes int
}
Config configures a Worker.
type HandleOption ¶
type HandleOption func(*handleOpts)
HandleOption tunes per-task-type registration.
func WithLockDuration ¶
func WithLockDuration(d time.Duration) HandleOption
WithLockDuration sets the exclusive lock duration on each acquired job. The runtime renews the lock automatically while the handler runs.
func WithMaxJobs ¶
func WithMaxJobs(n int) HandleOption
WithMaxJobs caps how many jobs the runtime acquires per poll for the task type. Higher values amortize the round-trip; lower values share the queue with other workers.
func WithPollTimeout ¶
func WithPollTimeout(d time.Duration) HandleOption
WithPollTimeout sets how long each long-poll call waits before returning 204. Defaults to 30s.
type Handler ¶
Handler processes a single job. Return value semantics:
- (vars, nil) → Complete with vars merged into instance
- (_, *BpmnError) → ThrowError with the supplied code as a business error (retryable=false): routed to a matching boundary error event immediately, bypassing the retry budget
- (_, any other error) → ThrowError with a generic code as a retryable technical failure: the retry budget is consumed before the error surfaces
type Job ¶
type Job struct {
*generated.ExternalJob
// Vars holds the input variables resolved by the service task. Use
// variables.Get[T] or variables.As[T] to decode into typed values.
Vars variables.Vars
}
Job is the work unit handed to a Handler. It wraps the generated ExternalJob and exposes the variables decoded into a Vars value.
type Worker ¶
type Worker struct {
// contains filtered or unexported fields
}
Worker is a long-poll runtime owning a set of handlers, one per task type. Use Worker.Handle to register a handler; Worker.Run starts the polling goroutines and blocks until ctx is cancelled.
func New ¶
func New(api *generated.ClientWithResponses, projectID openapi_types.UUID, cfg Config) *Worker
New constructs a Worker bound to projectID. api should be an authenticated client (typically obtained from auth.NewClient).
func (*Worker) Handle ¶
func (w *Worker) Handle(taskType string, handler Handler, opts ...HandleOption)
Handle registers handler as the processor for taskType. Re-registering an existing taskType replaces the previous handler.
func (*Worker) Run ¶
Run starts the polling loops and blocks until ctx is cancelled. Each registered task type is polled in its own goroutine; jobs are dispatched concurrently per task type up to maxJobs.
Returns nil when ctx is cancelled (graceful shutdown after in-flight jobs finish), or an error if Run is invoked with no registered handlers.
Source Files