queue

type BatchEntry struct {
	// ID is the caller's own name for this entry, which the result carries back.
	//
	// The result is not ordered, so this is the only thing that identifies an
	// entry in it. Not sent to the provider, so any string the caller can tell
	// apart will do and two entries may share one.
	ID string
	// Body is the message.
	Body []byte
	// Options configure this entry alone rather than the batch, so one batch can
	// span message groups.
	Options []SendOption
}

type BatchFailure struct {
	// ID is the name the caller gave the entry.
	ID string
	// Code is the provider's own name for the refusal.
	Code string
	// Message describes the refusal.
	Message string
	// SenderFault reports whether the entry itself was at fault rather than the
	// service, where the provider tells the two apart. A sender fault fails the
	// same way however often it is retried; a service fault may not.
	SenderFault bool
}

type BatchResult struct {
	Successful []BatchSuccess
	Failed     []BatchFailure
	Unsent     []BatchUnsent
}

type BatchSuccess struct {
	// ID is the name the caller gave the entry.
	ID string
	// MessageID is what the provider called the message it took.
	MessageID string
}

type BatchUnsent struct {
	// ID is the name the caller gave the entry.
	ID string
	// Err is what stopped the batch, and is the same failure for every unsent
	// entry.
	//
	// Whether the entry is worth sending again is Err's to say: a request that
	// timed out is, an entry the provider cannot accept is not until it is
	// changed. An entry of the request that actually failed may or may not have
	// reached the provider, which is a reason to send it again rather than a
	// reason not to: a message delivered twice is something a consumer has to
	// withstand regardless.
	Err error
}

type Client interface {
	// Send puts one message on the queue, and returns the provider's id for it.
	Send(ctx context.Context, body []byte, opts ...SendOption) (string, error)
	// SendBatch sends several messages in as few requests as the provider
	// allows. Every entry comes back in exactly one of the three lists of
	// [BatchResult], whether or not an error comes back with it.
	//
	// A batch taken in part is not an error: a provider accepts the entries it
	// will and refuses the rest, and those refusals are Failed.
	//
	// The error reports a request that did not complete. A batch over the
	// provider's own ceiling is more than one request, and it stops at the
	// first that fails: entries sent before then are in Successful, and the
	// entries of the failed request along with any the batch never reached are
	// in Unsent.
	SendBatch(ctx context.Context, entries []BatchEntry) (BatchResult, error)
}

type SendOption func(*SendOptions)

type SendOptions struct {
	Delay      time.Duration
	Attributes map[string]string
	// GroupID orders messages within a group on queues that support it.
	GroupID string
	// DeduplicationID suppresses a duplicate send within the provider's window.
	DeduplicationID string
}