Documentation
¶
Overview ¶
Package queueforge is a Go client for the QueueForge HTTP API.
Its main feature is safe retries. Enqueue sends an Idempotency-Key (generated automatically when you do not supply one) and reuses the SAME key on every retry, so a retry after a timeout or a 5xx cannot create a duplicate job: the server returns the original job with Idempotent-Replay.
c := queueforge.New("https://queue.example.com", os.Getenv("QUEUEFORGE_KEY"))
job, err := c.Enqueue(ctx, queueforge.EnqueueRequest{TaskType: "email.send", Payload: payload})
done, err := c.Wait(ctx, job.ID, queueforge.WaitOptions{})
Index ¶
- func IsConflict(err error) bool
- func IsNotFound(err error) bool
- type APIError
- type Client
- func (c *Client) Cancel(ctx context.Context, id string) error
- func (c *Client) Enqueue(ctx context.Context, req EnqueueRequest) (*Job, error)
- func (c *Client) EnqueueBatch(ctx context.Context, reqs []EnqueueRequest, idempotencyKey string) ([]*Job, error)
- func (c *Client) Get(ctx context.Context, id string) (*Job, error)
- func (c *Client) Wait(ctx context.Context, id string, o WaitOptions) (*Job, error)
- type EnqueueRequest
- type Job
- type Option
- type WaitOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsConflict ¶
func IsNotFound ¶
IsNotFound / IsConflict are convenience checks for errors.As targets.
Types ¶
type APIError ¶
type APIError struct {
Status int
Code string
Message string
RequestID string
RetryAfter time.Duration
}
APIError is returned for any non-2xx response.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client talks to one QueueForge deployment. It is safe for concurrent use.
func New ¶
New creates a client. Requests time out after 30 seconds unless you supply your own http.Client.
func (*Client) Enqueue ¶
Enqueue submits a job. It retries 429, 5xx and network errors with exponential backoff and full jitter (honouring Retry-After), always with the same idempotency key.
func (*Client) EnqueueBatch ¶
func (c *Client) EnqueueBatch(ctx context.Context, reqs []EnqueueRequest, idempotencyKey string) ([]*Job, error)
EnqueueBatch submits up to 100 jobs atomically: either every job is accepted or none is. Retries (429, 5xx, network) reuse one idempotency key, so a retried batch never creates duplicates. Pass your own idempotencyKey to make separate calls idempotent too; empty means one is generated.
type EnqueueRequest ¶
type EnqueueRequest struct {
TaskType string `json:"task_type"`
Queue string `json:"queue,omitempty"`
Payload json.RawMessage `json:"payload,omitempty"`
Priority *int `json:"priority,omitempty"`
RunAt *time.Time `json:"run_at,omitempty"`
MaxAttempts *int `json:"max_attempts,omitempty"`
TimeoutSeconds *int `json:"timeout_seconds,omitempty"`
// IdempotencyKey makes submission safe to repeat. Empty = generated for you (and reused across
// this call's retries). Supply your own to make *separate* calls idempotent too.
IdempotencyKey string `json:"-"`
// TraceParent is an optional W3C traceparent header to join an existing trace.
TraceParent string `json:"-"`
}
EnqueueRequest describes a job to submit.
type Job ¶
type Job struct {
ID string `json:"id"`
Status string `json:"status"`
TaskType string `json:"task_type"`
Queue string `json:"queue"`
Result json.RawMessage `json:"result"`
AttemptsStarted int `json:"attempts_started"`
MaxAttempts int `json:"max_attempts"`
LastErrorCode *string `json:"last_error_code"`
LastErrorMsg *string `json:"last_error_message"`
TraceID string `json:"trace_id"`
CreatedAt time.Time `json:"created_at"`
// IdempotentReplay is true when the server recognised the idempotency key and returned the
// original job instead of creating a new one.
IdempotentReplay bool `json:"-"`
}
Job is the server's view of a job.
type Option ¶
type Option func(*Client)
Option customises a Client.
func WithBackoff ¶
func WithHTTPClient ¶
func WithMaxRetries ¶
type WaitOptions ¶
WaitOptions controls Wait.
Source Files