workqueue

type ExponentialReadBackoff struct {
	// BaseDelay is used for calculating retry interval as base * 2 ^ attempt.
	BaseDelay time.Duration
	// MaxDelay sets a cap for the value returned from NextDelay.
	MaxDelay time.Duration
}

type HandlerFn func(context.Context, *Payload) (a2a.SendMessageResult, error)

type Heartbeater interface {
	// HeartbeatInterval returns the interval between heartbeats.
	HeartbeatInterval() time.Duration
	// Heartbeat is called at heartbeat interval to mark the message as still being handled.
	Heartbeat(ctx context.Context) error
}

type Message interface {
	// Payload returns the payload of the message which becomes the execution or cancelation input.
	Payload() *Payload
	// Complete marks the message as completed after it was handled by a worker.
	Complete(ctx context.Context) error
	// Return returns the message to the queue after worker failed to handle it.
	Return(ctx context.Context, cause error) error
}

type Payload struct {
	// Type defines the type of payload.
	Type PayloadType
	// TaskID is an ID of the task to execute or cancel.
	TaskID a2a.TaskID
	// CancelParams defines the cancelation parameters. It is only set for [PayloadTypeCancel].
	CancelParams *a2a.TaskIDParams
	// ExecuteParams defines the execution parameters. It is only set for [PayloadTypeExecute].
	ExecuteParams *a2a.MessageSendParams
}

type PayloadType string

type PullQueueConfig struct {
	// ReadRetry configures the behavior of polling loop in case of workqueue Read errors.
	ReadRetry ReadRetryPolicy
}

type Queue interface {
	Writer

	// RegisterHandler registers an executor. This method is called by the SDK.
	RegisterHandler(limiter.ConcurrencyConfig, HandlerFn)
}

type ReadRetryPolicy interface {
	// NextDelay returns the sleep duration for a failed Read attempt.
	NextDelay(attempt int) time.Duration
}

type ReadWriter interface {
	Writer
	// Read dequeues a new message from the queue.
	Read(context.Context) (Message, error)
}

type Writer interface {
	// Write puts a new payload into the queue. Paylod will contain a TaskID but a different value can be returned to handle idempotency.
	Write(context.Context, *Payload) (a2a.TaskID, error)
}