notifications

package
v0.3.0-beta.23 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 7, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
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")
)

Functions

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 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.

func (CursorKey) Normalize

func (k CursorKey) Normalize() (CursorKey, error)

Normalize preserves and validates cursor identity.

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.

const (
	// ScopeKindGlobal identifies a daemon-wide cursor with no workspace binding.
	ScopeKindGlobal ScopeKind = "global"
	// ScopeKindWorkspace identifies a cursor owned by one workspace.
	ScopeKindWorkspace ScopeKind = "workspace"
)

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.

func (ScopeRef) Normalize

func (s ScopeRef) Normalize() ScopeRef

Normalize preserves the exact scope components supplied by the caller.

Scope values take part in durable cursor identity, so normalizing whitespace or case here could merge two independently owned cursors. Validate instead accepts only the two canonical scope kinds.

func (ScopeRef) Validate

func (s ScopeRef) Validate() error

Validate reports whether a scope has one unambiguous ownership binding.

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) Advance

func (s *Service) Advance(ctx context.Context, update AdvanceCursor) (Cursor, error)

Advance records a monotonic confirmed delivery position.

func (*Service) Get

func (s *Service) Get(ctx context.Context, key CursorKey) (Cursor, error)

Get returns one durable cursor.

func (*Service) List

func (s *Service) List(ctx context.Context, query CursorQuery) ([]Cursor, error)

List returns durable cursors matching the query.

func (*Service) RecordError

func (s *Service) RecordError(ctx context.Context, report CursorError) (Cursor, error)

RecordError stores a diagnostic without moving the confirmed delivery sequence.

func (*Service) Reset

func (s *Service) Reset(ctx context.Context, reset ResetCursor) (Cursor, error)

Reset repairs one cursor after an explicit recovery decision.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL