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 HandlerConfig struct {
	Limiter limiter.ConcurrencyConfig
}

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 InMemoryQueueConfig struct {
	LeaseManager LeaseManager
}

type Lease interface {
	// TaskID returns the task identifier associated with the lease.
	// Implementations may return a TaskID different from the one in the [Payload] to
	// support idempotency (e.g. dedup by message ID and map to an existing TaskID).
	TaskID() a2a.TaskID
	// Release releases the lease.
	Release(context.Context)
}

type LeaseManager interface {
	// Acquire attempts to acquire a lease for the given payload.
	Acquire(context.Context, *Payload) (Lease, 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
	// CancelRequest defines the cancelation parameters. It is only set for [PayloadTypeCancel].
	CancelRequest *a2a.CancelTaskRequest
	// ExecuteRequest defines the execution parameters. It is only set for [PayloadTypeExecute].
	ExecuteRequest *a2a.SendMessageRequest
	// CallContext carries serializable call context data (user identity, service params, tenant)
	// for cross-process propagation in distributed mode.
	CallContext map[string]any
}

type PayloadType string

type PullQueueConfig struct {
	// ReadRetry configures the behavior of polling loop in case of workqueue Read errors.
	ReadRetry ReadRetryPolicy
	// BeforeExecutionCallback is called before execution is started. It can be used to modify the context or the message.
	// If an error is returned, execution will not be started and neither Complete nor Return will be called for the Message.
	BeforeExecutionCallback func(context.Context, Message) (context.Context, error)
	// AfterExecutionCallback is called after execution finishes. It can be used to decide how the message should be handled.
	// If an error is returned, neither Complete nor Return will be called for the Message.
	AfterExecutionCallback func(context.Context, Message, a2a.SendMessageResult, error) error
}

type Queue interface {
	Writer

	// RegisterHandler registers an executor. This method is called by the SDK.
	RegisterHandler(HandlerConfig, 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)
}

type WriterFunc func(context.Context, *Payload) (a2a.TaskID, error)