Documentation
¶
Overview ¶
Package persistence owns BlockQueue's durable SQL state and backend dialect differences. The public blockqueue package remains the runtime/API facade; database drivers are supplied through the public store package.
Index ¶
- Constants
- Variables
- func Migrate(ctx context.Context, driver store.Driver) error
- type BatchAckItem
- type BatchNackItem
- type CancellationRow
- type CheckpointMode
- type CheckpointResult
- type DeliveryError
- type DeliveryRow
- type MessageDeliveryStatus
- type MessageStatus
- type PersistWriteResult
- type RetryPolicy
- type Schedule
- type ScheduleRun
- type Store
- func (store *Store) AckDelivery(ctx context.Context, subscriberID uuid.UUID, messageID, receipt string) error
- func (store *Store) AckDeliveryWithTx(ctx context.Context, tx *sql.Tx, subscriberID uuid.UUID, ...) error
- func (store *Store) BatchAckDeliveries(ctx context.Context, subscriberID uuid.UUID, requests []BatchAckItem) ([]error, error)
- func (store *Store) BatchNackDeliveries(ctx context.Context, subscriberID uuid.UUID, requests []BatchNackItem) ([]bool, []error, error)
- func (store *Store) BatchReplayDeadLetters(ctx context.Context, subscriberID uuid.UUID, messageIDs []string) ([]bool, error)
- func (store *Store) CancelClaimedDeliveryWithTx(ctx context.Context, tx *sql.Tx, subscriberID uuid.UUID, ...) error
- func (store *Store) CancelDeliveryWithTx(ctx context.Context, tx *sql.Tx, subscriberID uuid.UUID, ...) (string, error)
- func (store *Store) CancelMessageWithTx(ctx context.Context, tx *sql.Tx, topicID uuid.UUID, messageID, reason string) ([]CancellationRow, error)
- func (store *Store) CheckpointSQLite(ctx context.Context, mode CheckpointMode) (CheckpointResult, error)
- func (store *Store) ClaimDeliveries(ctx context.Context, subscriberID uuid.UUID, limit int, lease time.Duration) ([]DeliveryRow, error)
- func (store *Store) ClaimDueSchedule(ctx context.Context, owner string, now time.Time, lease time.Duration) (Schedule, bool, error)
- func (store *Store) Close() error
- func (store *Store) Conn() *sqlx.DB
- func (store *Store) CreateSchedule(ctx context.Context, schedule Schedule) error
- func (store *Store) CreateSubscribers(ctx context.Context, subscribers Subscribers) error
- func (store *Store) CreateTopic(ctx context.Context, topic Topic, subscribers Subscribers) error
- func (store *Store) DatabaseNow(ctx context.Context) (time.Time, error)
- func (store *Store) DeleteSchedule(ctx context.Context, topicID uuid.UUID, scheduleID string) error
- func (store *Store) DeleteSubscriber(ctx context.Context, topicID, subscriberID uuid.UUID, name string) error
- func (store *Store) DeleteTopic(ctx context.Context, topicID uuid.UUID) error
- func (store *Store) DialectError() error
- func (store *Store) ExtendDeliveryLease(ctx context.Context, subscriberID uuid.UUID, messageID, receipt string, ...) (time.Time, error)
- func (store *Store) FailScheduleOccurrence(ctx context.Context, claimed Schedule, scheduledFor, nextRunAt time.Time, ...) (ScheduleRun, error)
- func (store *Store) GetMessageStatus(ctx context.Context, topicID uuid.UUID, messageID string) (MessageStatus, error)
- func (store *Store) GetSchedule(ctx context.Context, topicID uuid.UUID, scheduleID string) (Schedule, error)
- func (store *Store) GetSubscribers(ctx context.Context, filter SubscriberFilter) (Subscribers, error)
- func (store *Store) GetTopics(ctx context.Context, filter TopicFilter) (Topics, error)
- func (store *Store) HasDeletedTopology(ctx context.Context) (bool, error)
- func (store *Store) IncrementalVacuum(ctx context.Context) error
- func (store *Store) ListDeliveries(ctx context.Context, subscriberID uuid.UUID, deadLetter bool, limit int, ...) ([]DeliveryRow, error)
- func (store *Store) ListDeliveryErrors(ctx context.Context, subscriberID uuid.UUID, messageID string, limit int, ...) ([]DeliveryError, error)
- func (store *Store) ListScheduleRuns(ctx context.Context, scheduleID string, limit int, before time.Time, ...) ([]ScheduleRun, error)
- func (store *Store) ListSchedules(ctx context.Context, topicID uuid.UUID) ([]Schedule, error)
- func (store *Store) ListSchedulesPage(ctx context.Context, topicID uuid.UUID, limit int, afterName, afterID string) ([]Schedule, error)
- func (store *Store) ListSubscriberStatuses(ctx context.Context, topicID uuid.UUID, limit int, afterName, afterID string) ([]SubscriberStatusRow, error)
- func (store *Store) ListTopics(ctx context.Context, limit int, afterName, afterID string) (Topics, error)
- func (store *Store) NackDelivery(ctx context.Context, subscriberID uuid.UUID, messageID, receipt string, ...) (bool, error)
- func (store *Store) NackDeliveryWithTx(ctx context.Context, tx *sql.Tx, subscriberID uuid.UUID, ...) (bool, error)
- func (store *Store) NextDeliveryWake(ctx context.Context, subscriberID uuid.UUID) (time.Time, time.Time, bool, error)
- func (store *Store) NextLeaseExpiry(ctx context.Context) (time.Time, time.Time, bool, error)
- func (store *Store) NextScheduleDue(ctx context.Context, now time.Time) (time.Time, time.Time, bool, error)
- func (store *Store) PersistScheduleOccurrence(ctx context.Context, claimed Schedule, scheduledFor, nextRunAt time.Time, ...) (ScheduleRun, error)
- func (store *Store) PersistWriteRequests(ctx context.Context, requests []WriteRequest) (PersistWriteResult, error)
- func (store *Store) PersistWriteRequestsWithTx(ctx context.Context, tx *sql.Tx, requests []WriteRequest) (PersistWriteResult, error)
- func (store *Store) PruneDeadLetters(ctx context.Context, retention time.Duration) error
- func (store *Store) PruneDeletedTopology(ctx context.Context, budget time.Duration) (int64, bool, bool, error)
- func (store *Store) PruneProcessedMessages(ctx context.Context, retention time.Duration) error
- func (store *Store) PruneScheduleRuns(ctx context.Context, retention time.Duration) error
- func (store *Store) ReapExpiredDeliveries(ctx context.Context, limit int) (int64, error)
- func (store *Store) ReplayDeadLetter(ctx context.Context, subscriberID uuid.UUID, messageID string) (bool, error)
- func (store *Store) ScheduleNameExists(ctx context.Context, topicID uuid.UUID, name string) (bool, error)
- func (store *Store) SetSchedulePaused(ctx context.Context, topicID uuid.UUID, scheduleID string, paused bool) error
- func (store *Store) SetSubscriberPaused(ctx context.Context, subscriberID uuid.UUID, paused bool) error
- func (store *Store) SetTopicPaused(ctx context.Context, topicID uuid.UUID, paused bool) error
- func (store *Store) SnoozeDeliveryWithTx(ctx context.Context, tx *sql.Tx, subscriberID uuid.UUID, ...) (time.Time, error)
- func (store *Store) StatementCacheLen() int
- func (store *Store) SupportsSQLiteMaintenance() bool
- func (store *Store) TopicSubscriberQueueStats(ctx context.Context, topicID uuid.UUID) (map[uuid.UUID]SubscriberQueueStats, error)
- func (store *Store) TryMaintenanceLeadership(ctx context.Context) (bool, func() error, error)
- func (store *Store) UpdateSchedule(ctx context.Context, topicID uuid.UUID, scheduleID string, expectedVersion int, ...) error
- type Subscriber
- type SubscriberFilter
- type SubscriberOptions
- type SubscriberQueueStats
- type SubscriberStatusRow
- type Subscribers
- type Topic
- type TopicFilter
- type Topics
- type WriteRequest
Constants ¶
const ( MaximumDeliveryLease = subscriberconfig.MaximumDeliveryLease MaxDeliveryTextBytes = 16 << 10 )
const ( DeliveryStatusPending = "pending" DeliveryStatusDelivered = "delivered" DeliveryStatusProcessed = "processed" DeliveryStatusDeadLetter = "dead_letter" DeliveryStatusCancelled = "cancelled" )
Delivery states are persisted values protected by schema constraints. Keep them centralized for Go-side comparisons and assignments. SQL predicates intentionally retain literals so both backends can match partial indexes.
const ( ScheduleRunStatusRunning = "running" ScheduleRunStatusCompleted = "completed" ScheduleRunStatusSkipped = "skipped" ScheduleRunStatusFailed = "failed" )
const ( ScheduleMisfirePolicyFireOnce = "fire_once" ScheduleOverlapPolicySkip = "skip" )
const ( EventChannel = "blockqueue_events" EventTopology = "topology" EventScheduler = "scheduler" EventDeliveryPrefix = "delivery:" )
PostgreSQL notifications are wake-up hints. These values form the internal event protocol shared by persistence and the queue listener.
Variables ¶
var ( ErrTopicNotFound = errors.New("topic not found") ErrNoActiveSubscriber = errors.New("topic has no active subscriber") ErrInvalidPublish = errors.New("invalid publish request") ErrInvalidCursor = errors.New("invalid pagination cursor") ErrResourceConflict = errors.New("resource already exists") ErrSubscriberNotFound = errors.New("subscriber not found") ErrLeaseLost = errors.New("delivery lease lost") ErrDeliveryNotFound = errors.New("delivery not found") ErrInvalidReceipt = errors.New("receipt_token is required") ErrDeliveryTerminal = errors.New("delivery is already terminal") ErrIdempotencyConflict = errors.New("idempotency key conflicts with a different message") ErrWriterClosed = errors.New("writer closed") ErrScheduleNotFound = errors.New("schedule not found") ErrScheduleVersion = errors.New("stale schedule version") ErrScheduleOverlap = errors.New("previous schedule run is still active") ErrScheduleLeaseLost = errors.New("schedule lease lost") ErrUnsupportedDialect = errors.New("unsupported database dialect") ErrMigrationChecksum = errors.New("migration checksum mismatch") )
Functions ¶
Types ¶
type BatchAckItem ¶
type BatchNackItem ¶
type CancellationRow ¶
type CancellationRow = cancellationRow
type CheckpointMode ¶
type CheckpointMode = sqliteCheckpointMode
const ( CheckpointPassive CheckpointMode = sqliteCheckpointPassive CheckpointTruncate CheckpointMode = sqliteCheckpointTruncate )
type CheckpointResult ¶
type CheckpointResult = sqliteCheckpointResult
type DeliveryError ¶
type DeliveryRow ¶
type DeliveryRow = deliveryRow
type MessageDeliveryStatus ¶
type MessageDeliveryStatus struct {
SubscriberID string `db:"subscriber_id"`
Subscriber string `db:"subscriber"`
Status string `db:"status"`
DeliveryCount int `db:"delivery_count"`
FailureCount int `db:"failure_count"`
VisibleAt time.Time `db:"visible_at"`
ProcessedAt *time.Time `db:"processed_at"`
CancelledAt *time.Time `db:"cancelled_at"`
CancelReason string `db:"cancel_reason"`
}
type MessageStatus ¶
type PersistWriteResult ¶
PersistWriteResult describes the storage-resolved identity of each request in input order. ScheduledAt is calculated from the database clock for immediate and relative-delay publishes, and is authoritative even when the caller owns the surrounding transaction and has not committed it yet.
type RetryPolicy ¶
type Schedule ¶
type Schedule struct {
ID string `db:"id"`
TopicID string `db:"topic_id"`
Name string `db:"name"`
CronExpression string `db:"cron_expression"`
Timezone string `db:"timezone"`
Message string `db:"message"`
Headers string `db:"headers"`
CorrelationID sql.NullString `db:"correlation_id"`
Priority int `db:"priority"`
MisfirePolicy string `db:"misfire_policy"`
OverlapPolicy string `db:"overlap_policy"`
Paused bool `db:"paused"`
Version int `db:"version"`
NextRunAt time.Time `db:"next_run_at"`
OwnerID sql.NullString `db:"owner_id"`
LeaseExpiresAt sql.NullTime `db:"lease_expires_at"`
FencingToken int64 `db:"fencing_token"`
CreatedAt time.Time `db:"created_at"`
UpdatedAt time.Time `db:"updated_at"`
ClaimedAt time.Time `db:"-"`
}
type ScheduleRun ¶
type ScheduleRun struct {
ID string `db:"id"`
ScheduleID string `db:"schedule_id"`
MessageID sql.NullString `db:"message_id"`
ScheduledFor time.Time `db:"scheduled_for"`
StartedAt time.Time `db:"started_at"`
FinishedAt sql.NullTime `db:"finished_at"`
Status string `db:"status"`
Error sql.NullString `db:"error"`
CreatedAt time.Time `db:"created_at"`
}
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is the queue engine's concrete persistence boundary. It deliberately avoids a broad repository interface: SQLite and PostgreSQL share the same transactional implementation, with only genuine SQL differences delegated to the internal dialect strategy.
func (*Store) AckDelivery ¶
func (*Store) AckDeliveryWithTx ¶
func (*Store) BatchAckDeliveries ¶
func (*Store) BatchNackDeliveries ¶
func (*Store) BatchReplayDeadLetters ¶
func (*Store) CancelClaimedDeliveryWithTx ¶
func (*Store) CancelDeliveryWithTx ¶
func (*Store) CancelMessageWithTx ¶
func (*Store) CheckpointSQLite ¶
func (store *Store) CheckpointSQLite(ctx context.Context, mode CheckpointMode) (CheckpointResult, error)
func (*Store) ClaimDeliveries ¶
func (*Store) ClaimDueSchedule ¶
func (*Store) CreateSchedule ¶
func (*Store) CreateSubscribers ¶
func (store *Store) CreateSubscribers(ctx context.Context, subscribers Subscribers) error
func (*Store) CreateTopic ¶
func (*Store) DeleteSchedule ¶
func (*Store) DeleteSubscriber ¶
func (*Store) DeleteTopic ¶
func (*Store) DialectError ¶
func (*Store) ExtendDeliveryLease ¶
func (*Store) FailScheduleOccurrence ¶
func (*Store) GetMessageStatus ¶
func (*Store) GetSchedule ¶
func (*Store) GetSubscribers ¶
func (store *Store) GetSubscribers(ctx context.Context, filter SubscriberFilter) (Subscribers, error)
func (*Store) HasDeletedTopology ¶
func (*Store) ListDeliveries ¶
func (*Store) ListDeliveryErrors ¶
func (*Store) ListScheduleRuns ¶
func (*Store) ListSchedules ¶
func (*Store) ListSchedulesPage ¶
func (*Store) ListSubscriberStatuses ¶
func (*Store) ListTopics ¶
func (*Store) NackDelivery ¶
func (*Store) NackDeliveryWithTx ¶
func (*Store) NextDeliveryWake ¶
func (*Store) NextLeaseExpiry ¶
func (*Store) NextScheduleDue ¶
func (*Store) PersistScheduleOccurrence ¶
func (*Store) PersistWriteRequests ¶
func (store *Store) PersistWriteRequests(ctx context.Context, requests []WriteRequest) (PersistWriteResult, error)
func (*Store) PersistWriteRequestsWithTx ¶
func (store *Store) PersistWriteRequestsWithTx(ctx context.Context, tx *sql.Tx, requests []WriteRequest) (PersistWriteResult, error)
func (*Store) PruneDeadLetters ¶
func (*Store) PruneDeletedTopology ¶
func (*Store) PruneProcessedMessages ¶
func (*Store) PruneScheduleRuns ¶
func (*Store) ReapExpiredDeliveries ¶
func (*Store) ReplayDeadLetter ¶
func (*Store) ScheduleNameExists ¶
func (*Store) SetSchedulePaused ¶
func (*Store) SetSubscriberPaused ¶
func (*Store) SetTopicPaused ¶
func (*Store) SnoozeDeliveryWithTx ¶
func (*Store) StatementCacheLen ¶
func (*Store) SupportsSQLiteMaintenance ¶
func (*Store) TopicSubscriberQueueStats ¶
func (*Store) TryMaintenanceLeadership ¶
type Subscriber ¶
type SubscriberFilter ¶
type SubscriberOptions ¶
type SubscriberOptions struct {
MaxAttempts int `json:"max_attempts"`
VisibilityDuration string `json:"visibility_duration"`
DequeueBatchSize int `json:"dequeue_batch_size,omitempty"`
RetryPolicy RetryPolicy `json:"retry_policy,omitempty"`
}
func (*SubscriberOptions) Scan ¶
func (options *SubscriberOptions) Scan(source any) error
type SubscriberQueueStats ¶
type SubscriberStatusRow ¶
type Subscribers ¶
type Subscribers []Subscriber