streamqueue

type AckRequest struct {
	// Stream is the logical stream key.
	Stream string
	// Group is consumer-group identity.
	Group string
	// ID is backend entry identity, not application identity.
	ID string
}

type AddRequest struct {
	// Stream is the logical stream key.
	Stream string
	// MaxLength is positive append capacity/count policy interpreted by the transport.
	MaxLength int64
	// Body contains mutable payload bytes without copying the backing array.
	Body []byte
}

type ClaimRequest struct {
	// Stream is the logical stream key.
	Stream string
	// Group is consumer-group identity.
	Group string
	// Consumer is read/reclaim owner identity.
	Consumer string
	// MinIdle is positive idle eligibility, not exclusive handler execution fencing.
	MinIdle time.Duration
	// Start is the opaque server reclaim scan cursor.
	Start string
	// Count bounds returned entries, not all server scan work.
	Count int64
}

type ClaimResult struct {
	// Next is the next server scan cursor, not a snapshot identity.
	Next string
	// Deliveries contains mutable recovered entries with transport-defined byte ownership.
	Deliveries []Delivery
}

type DeadLetterRequest struct {
	// Source is the source stream to settle after destination append.
	Source string
	// Destination must identify a distinct terminal stream.
	Destination string
	// Group is consumer-group identity.
	Group string
	// Delivery holds pending source identity, body and replay lineage.
	Delivery Delivery
	// Failure holds bounded disposition without content redaction.
	Failure FailureMetadata
}

type Delivery struct {
	// ID is backend entry identity, not application identity.
	ID string
	// Body contains mutable payload bytes without copying the backing array.
	Body []byte
	// Attempts counts backend deliveries, separately from local handler retries.
	Attempts int64
	// Reclaimed marks a stale pending entry recovered by this transport.
	Reclaimed bool
	// OriginalDeadLetterID identifies the first terminal record in replay lineage.
	OriginalDeadLetterID string
	// PriorDeadLetterID identifies the immediately preceding terminal record.
	PriorDeadLetterID string
	// ReplayGeneration is positive only with complete lineage; zero means no replay metadata.
	ReplayGeneration uint32
}

type FailureMetadata struct {
	// Classification selects backend-neutral disposition.
	Classification management.Classification
	// Code is a bounded caller-controlled failure label; keep its content non-sensitive.
	Code string
}

type GroupState struct {
	// Pending counts delivered group entries not acknowledged.
	Pending int64
	// Lag counts undelivered group entries; negative means unknown.
	Lag int64
	// OldestPendingID is the server identity used to derive pending age.
	OldestPendingID string
}

type ReadRequest struct {
	// Stream is the logical stream key.
	Stream string
	// Group is consumer-group identity.
	Group string
	// Consumer is read/reclaim owner identity.
	Consumer string
	// Count is the positive batch ceiling, at most MaxBatchSize.
	Count int64
	// Block is positive blocking duration; millisecond command encoding truncates fractions.
	Block time.Duration
}

type RequestError struct {
	// Command identifies the rejected operation without its input values.
	Command string
	// Field identifies the rejected field; caller construction controls label disclosure.
	Field string
	// Cause retains the validation cause for programmatic inspection.
	Cause error
}

type Stats struct {
	// Depth combines pending and lag only when lag is known.
	Depth int64
	// Pending counts delivered group entries not acknowledged.
	Pending int64
	// Lag counts undelivered group entries; negative means unknown.
	Lag int64
	// LagKnown distinguishes determinate depth/lag from unsupported measurements.
	LagKnown bool
}

type Transport interface {
	// EnsureGroup creates or verifies a consumer group; existing group ownership is transport-defined.
	EnsureGroup(context.Context, string, string) error
	// Add appends one entry subject to native admission policy.
	Add(context.Context, AddRequest) (string, error)
	// Read returns new group entries with transport-defined byte ownership.
	Read(context.Context, ReadRequest) ([]Delivery, error)
	// Claim recovers stale pending entries; idle time is not exclusive execution fencing.
	Claim(context.Context, ClaimRequest) (ClaimResult, error)
	// Ack settles one pending entry; a lost response may leave an ambiguous outcome.
	Ack(context.Context, AckRequest) error
	// DeadLetter appends terminal metadata before acknowledging source; failures can duplicate records.
	DeadLetter(context.Context, DeadLetterRequest) error
	// GroupState returns measured group counters without inventing unsupported lag.
	GroupState(context.Context, string, string) (GroupState, error)
	// Close releases owned transport resources; this signature has no caller context.
	Close() error
}