Documentation
¶
Overview ¶
Package queue provides message queue abstractions for job orchestration. Supports SQS (EC2 mode) and Valkey Streams (K8s mode).
Index ¶
- func ExtractTraceContext(msg Message) (traceID, spanID, parentID string)
- type JobMessage
- type Message
- type Queue
- type SQSAPI
- type SQSClient
- type ValkeyClient
- func (c *ValkeyClient) Close() error
- func (c *ValkeyClient) DeleteMessage(ctx context.Context, handle string) error
- func (c *ValkeyClient) Ping(ctx context.Context) error
- func (c *ValkeyClient) ReceiveMessages(ctx context.Context, maxMessages int32, waitTimeSeconds int32) ([]Message, error)
- func (c *ValkeyClient) SendMessage(ctx context.Context, job *JobMessage) error
- type ValkeyConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractTraceContext ¶
ExtractTraceContext extracts OpenTelemetry trace context from message attributes.
Types ¶
type JobMessage ¶
type JobMessage struct {
JobID string `json:"job_id,omitempty"`
RunID string `json:"run_id"`
Repo string `json:"repo,omitempty"`
InstanceType string `json:"instance_type"`
Pool string `json:"pool,omitempty"`
Private bool `json:"private"`
Spot bool `json:"spot"`
RunnerSpec string `json:"runner_spec"`
OriginalLabel string `json:"original_label,omitempty"`
RetryCount int `json:"retry_count,omitempty"`
ForceOnDemand bool `json:"force_on_demand,omitempty"`
Region string `json:"region,omitempty"`
Environment string `json:"environment,omitempty"`
OS string `json:"os,omitempty"` // linux, windows
Arch string `json:"arch,omitempty"` // amd64, arm64
InstanceTypes []string `json:"instance_types,omitempty"`
StorageGiB int `json:"storage_gib,omitempty"` // Disk storage in GiB
TraceID string `json:"trace_id,omitempty"`
SpanID string `json:"span_id,omitempty"`
ParentID string `json:"parent_id,omitempty"`
}
JobMessage represents workflow job configuration for queue transport.
type Message ¶ added in v1.1.0
type Message struct {
// ID is the unique message identifier.
ID string
// Body contains the JSON-encoded JobMessage.
Body string
// Handle is used to delete/acknowledge the message.
// For SQS: ReceiptHandle
// For Valkey: stream message ID
Handle string
// Attributes contains message metadata (trace context, etc).
Attributes map[string]string
}
Message represents a queue message in a provider-agnostic format.
type Queue ¶ added in v1.1.0
type Queue interface {
// SendMessage publishes a job message to the queue.
// Returns error if the message cannot be sent.
SendMessage(ctx context.Context, job *JobMessage) error
// ReceiveMessages retrieves up to maxMessages with long polling.
// waitTimeSeconds controls how long to wait for messages (0 = no wait).
// Returns empty slice if no messages available.
ReceiveMessages(ctx context.Context, maxMessages int32, waitTimeSeconds int32) ([]Message, error)
// DeleteMessage acknowledges successful message processing.
// handle is the receipt handle (SQS) or message ID (Valkey).
DeleteMessage(ctx context.Context, handle string) error
}
Queue defines the interface for message queue operations. Implementations must provide FIFO semantics per message group.
type SQSAPI ¶
type SQSAPI interface {
SendMessage(ctx context.Context, params *sqs.SendMessageInput, optFns ...func(*sqs.Options)) (*sqs.SendMessageOutput, error)
ReceiveMessage(ctx context.Context, params *sqs.ReceiveMessageInput, optFns ...func(*sqs.Options)) (*sqs.ReceiveMessageOutput, error)
DeleteMessage(ctx context.Context, params *sqs.DeleteMessageInput, optFns ...func(*sqs.Options)) (*sqs.DeleteMessageOutput, error)
}
SQSAPI defines SQS operations for queue message handling.
type SQSClient ¶ added in v1.1.0
type SQSClient struct {
// contains filtered or unexported fields
}
SQSClient implements Queue interface using AWS SQS.
func NewSQSClient ¶ added in v1.1.0
NewSQSClient creates an SQS-backed queue client.
func NewSQSClientWithAPI ¶ added in v1.1.0
NewSQSClientWithAPI creates an SQS client with a custom API implementation (for testing).
func (*SQSClient) DeleteMessage ¶ added in v1.1.0
DeleteMessage removes processed message from queue.
func (*SQSClient) ReceiveMessages ¶ added in v1.1.0
func (c *SQSClient) ReceiveMessages(ctx context.Context, maxMessages int32, waitTimeSeconds int32) ([]Message, error)
ReceiveMessages retrieves messages from queue with long polling. VisibilityTimeout set to 120s to exceed MessageProcessTimeout (90s).
func (*SQSClient) SendMessage ¶ added in v1.1.0
func (c *SQSClient) SendMessage(ctx context.Context, job *JobMessage) error
SendMessage sends job message to SQS FIFO queue with deduplication.
type ValkeyClient ¶ added in v1.1.0
type ValkeyClient struct {
// contains filtered or unexported fields
}
ValkeyClient implements Queue interface using Valkey/Redis Streams.
func NewValkeyClient ¶ added in v1.1.0
func NewValkeyClient(cfg ValkeyConfig) (*ValkeyClient, error)
NewValkeyClient creates a Valkey-backed queue client.
func NewValkeyClientWithRedis ¶ added in v1.1.0
func NewValkeyClientWithRedis(client *redis.Client, stream, group, consumerID string) *ValkeyClient
NewValkeyClientWithRedis creates a Valkey client with an existing redis.Client (for testing).
func (*ValkeyClient) Close ¶ added in v1.1.0
func (c *ValkeyClient) Close() error
Close closes the Valkey client connection.
func (*ValkeyClient) DeleteMessage ¶ added in v1.1.0
func (c *ValkeyClient) DeleteMessage(ctx context.Context, handle string) error
DeleteMessage acknowledges message processing via XACK.
func (*ValkeyClient) Ping ¶ added in v1.1.0
func (c *ValkeyClient) Ping(ctx context.Context) error
Ping checks connectivity to Valkey.
func (*ValkeyClient) ReceiveMessages ¶ added in v1.1.0
func (c *ValkeyClient) ReceiveMessages(ctx context.Context, maxMessages int32, waitTimeSeconds int32) ([]Message, error)
ReceiveMessages retrieves messages from Valkey stream using consumer group.
func (*ValkeyClient) SendMessage ¶ added in v1.1.0
func (c *ValkeyClient) SendMessage(ctx context.Context, job *JobMessage) error
SendMessage publishes job message to Valkey stream.