Documentation
¶
Index ¶
- Variables
- func AttentionIdentity(parts ...string) string
- func AttentionSnapshotIdentity(scope AttentionScope, occurrences []string) (string, []string)
- func EncodeDeliveryID(identity DeliveryIdentity) (string, error)
- type AdvanceCursor
- type AttentionScope
- type AttentionStore
- type Cursor
- type CursorError
- type CursorKey
- type CursorQuery
- type CursorStore
- type DeliveryIdentity
- type DeliveryKind
- type DeliveryPermit
- type DeliveryPermitReader
- type DeliveryPermitStore
- type ResetCursor
- type ScopeKind
- type ScopeRef
- type Service
- func (s *Service) AcquireDeliveryPermit(ctx context.Context, permit DeliveryPermit) error
- func (s *Service) Advance(ctx context.Context, update AdvanceCursor) (Cursor, error)
- func (s *Service) Get(ctx context.Context, key CursorKey) (Cursor, error)
- func (s *Service) List(ctx context.Context, query CursorQuery) ([]Cursor, error)
- func (s *Service) RecordError(ctx context.Context, report CursorError) (Cursor, error)
- func (s *Service) Reset(ctx context.Context, reset ResetCursor) (Cursor, error)
Constants ¶
This section is empty.
Variables ¶
var ( // ErrCursorNotFound reports that no durable notification cursor matched the key. ErrCursorNotFound = errors.New("notifications: cursor not found") // ErrInvalidCursor reports invalid cursor identity or cursor payload. ErrInvalidCursor = errors.New("notifications: invalid cursor") // ErrNonMonotonicCursor reports a cursor advance that would move backward or fork delivery metadata. ErrNonMonotonicCursor = errors.New("notifications: non-monotonic cursor advance") // ErrResetReasonRequired reports a reset request without an explicit recovery reason. ErrResetReasonRequired = errors.New("notifications: reset reason required") )
"notifications: snapshot expired or unavailable; refresh notifications",
)
ErrAttentionSnapshotUnavailable requires a fresh notification read before retrying.
Functions ¶
func AttentionIdentity ¶
AttentionIdentity preserves source boundaries even when identifiers contain separators.
func AttentionSnapshotIdentity ¶
func AttentionSnapshotIdentity(scope AttentionScope, occurrences []string) (string, []string)
AttentionSnapshotIdentity deduplicates unchanged snapshots across polling clients.
func EncodeDeliveryID ¶
func EncodeDeliveryID(identity DeliveryIdentity) (string, error)
EncodeDeliveryID returns an opaque, versioned, deterministic delivery identity.
Types ¶
type AdvanceCursor ¶
type AdvanceCursor struct {
Key CursorKey `json:"key"`
LastSequence int64 `json:"last_sequence"`
LastDeliveredAt time.Time `json:"last_delivered_at"`
DeliveryID string `json:"delivery_id,omitempty"`
Now time.Time `json:"now"`
}
AdvanceCursor records a confirmed delivery position.
func (AdvanceCursor) Normalize ¶
func (a AdvanceCursor) Normalize(fallbackNow time.Time) (AdvanceCursor, error)
Normalize validates an advance request and fills missing timestamps.
type AttentionScope ¶
AttentionScope binds receipts to the operator and snapshots to their selected population.
func (AttentionScope) Validate ¶
func (s AttentionScope) Validate() error
type AttentionStore ¶
type AttentionStore interface {
CaptureAttentionSnapshot(context.Context, AttentionScope, []string) (string, []string, error)
AcknowledgeAttentionSnapshot(context.Context, AttentionScope, string, string) error
}
AttentionStore persists exact occurrence receipts without changing source state.
type Cursor ¶
type Cursor struct {
Key CursorKey `json:"key"`
LastSequence int64 `json:"last_sequence"`
LastDeliveryID string `json:"last_delivery_id,omitempty"`
LastDeliveredAt time.Time `json:"last_delivered_at"`
LastError string `json:"last_error,omitempty"`
UpdatedAt time.Time `json:"updated_at"`
}
Cursor stores the latest confirmed delivery position for one consumer.
type CursorError ¶
type CursorError struct {
Key CursorKey `json:"key"`
LastError string `json:"last_error"`
Now time.Time `json:"now"`
}
CursorError records a bounded diagnostic without advancing delivery progress.
func (CursorError) Normalize ¶
func (e CursorError) Normalize(fallbackNow time.Time) (CursorError, error)
Normalize validates an error report and fills missing timestamps.
type CursorKey ¶
type CursorKey struct {
ProfileID string `json:"profile_id"`
Scope ScopeRef `json:"scope"`
ConsumerID string `json:"consumer_id"`
StreamName string `json:"stream_name"`
SubjectID string `json:"subject_id"`
}
CursorKey identifies one durable delivery cursor.
type CursorQuery ¶
type CursorQuery struct {
ProfileID string `json:"profile_id,omitempty"`
Scope ScopeRef `json:"scope"`
ConsumerID string `json:"consumer_id,omitempty"`
StreamName string `json:"stream_name,omitempty"`
SubjectID string `json:"subject_id,omitempty"`
Limit int `json:"limit,omitempty"`
}
CursorQuery filters cursor diagnostics. An omitted scope is valid only for an administrative aggregate list; scoped reads must carry a complete ScopeRef.
func (CursorQuery) Normalize ¶
func (q CursorQuery) Normalize() (CursorQuery, error)
Normalize validates query filters without changing opaque identity values.
type CursorStore ¶
type CursorStore interface {
GetCursor(ctx context.Context, key CursorKey) (Cursor, error)
ListCursors(ctx context.Context, query CursorQuery) ([]Cursor, error)
AdvanceCursor(ctx context.Context, update AdvanceCursor) (Cursor, error)
ResetCursor(ctx context.Context, reset ResetCursor) (Cursor, error)
RecordCursorError(ctx context.Context, report CursorError) (Cursor, error)
}
CursorStore persists confirmed notification delivery progress.
type DeliveryIdentity ¶
type DeliveryIdentity struct {
Cursor CursorKey `json:"cursor"`
TargetIdentity string `json:"target_identity"`
TargetIndex int `json:"target_index"`
Sequence int64 `json:"sequence"`
Kind DeliveryKind `json:"kind"`
Reason string `json:"reason,omitempty"`
}
DeliveryIdentity is the complete deterministic identity of one notification outcome.
func DecodeDeliveryID ¶
func DecodeDeliveryID(value string) (DeliveryIdentity, error)
DecodeDeliveryID validates and returns an opaque delivery identity.
type DeliveryKind ¶
type DeliveryKind string
DeliveryKind classifies whether a cursor advanced after an outbound send or a skip.
const ( // DeliveryKindDeliver identifies an outbound delivery attempt acknowledged by the bridge. DeliveryKindDeliver DeliveryKind = "deliver" // DeliveryKindSkipped identifies a deliberate cursor advance without an outbound delivery. DeliveryKindSkipped DeliveryKind = "skipped" )
type DeliveryPermit ¶
type DeliveryPermit struct {
Key CursorKey `json:"key"`
DeliveryID string `json:"delivery_id"`
AcquiredAt time.Time `json:"acquired_at"`
}
DeliveryPermit is the owner-active fence held from immediately before an external send through acknowledgement and cursor advancement.
func (DeliveryPermit) Normalize ¶
func (p DeliveryPermit) Normalize(fallbackNow time.Time) (DeliveryPermit, error)
Normalize validates the permit identity and fills an absent acquisition time.
type DeliveryPermitReader ¶
type DeliveryPermitReader interface {
ListDeliveryPermits(context.Context) ([]DeliveryPermit, error)
}
DeliveryPermitReader enumerates durable sends that still require acknowledgement and cursor advancement. Callers must replay them with the same delivery ID.
type DeliveryPermitStore ¶
type DeliveryPermitStore interface {
// AcquireDeliveryPermit records an owner-active fence before an external send.
AcquireDeliveryPermit(context.Context, DeliveryPermit) error
}
DeliveryPermitStore records the owner-active fence required before an external send.
type ResetCursor ¶
type ResetCursor struct {
Key CursorKey `json:"key"`
LastSequence int64 `json:"last_sequence"`
LastDeliveryID string `json:"last_delivery_id,omitempty"`
LastDeliveredAt time.Time `json:"last_delivered_at"`
Reason string `json:"reason"`
Now time.Time `json:"now"`
}
ResetCursor rewinds or repairs one cursor after an explicit recovery decision.
func (ResetCursor) Normalize ¶
func (r ResetCursor) Normalize(fallbackNow time.Time) (ResetCursor, error)
Normalize validates a reset request and fills missing timestamps.
type ScopeKind ¶
type ScopeKind string
ScopeKind identifies the durable ownership scope of a notification cursor.
type ScopeRef ¶
type ScopeRef struct {
Kind ScopeKind `json:"kind"`
WorkspaceID string `json:"workspace_id,omitempty"`
}
ScopeRef keeps a cursor's scope separate from every opaque identity component.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service validates cursor requests before delegating persistence to the store.
func NewService ¶
func NewService(store CursorStore) *Service
NewService creates a notification cursor service.
func (*Service) AcquireDeliveryPermit ¶
func (s *Service) AcquireDeliveryPermit(ctx context.Context, permit DeliveryPermit) error
AcquireDeliveryPermit fences profile archival before an external send.
func (*Service) RecordError ¶
RecordError stores a diagnostic without moving the confirmed delivery sequence.