Documentation
¶
Overview ¶
Package timer is the durable record of one-shot reminders an agent schedules for itself. The server claims the timers whose deadline has passed and delivers each note back into the owning session's loop as a system notice; the rows live in the project database, so a reminder scheduled before a restart still fires after it.
Index ¶
- Constants
- Variables
- type Store
- func (s *Store) Cancel(ctx context.Context, sessionID, id string) (Timer, error)
- func (s *Store) ClaimDue(ctx context.Context) ([]Timer, error)
- func (s *Store) Create(ctx context.Context, sessionID, note string, fireAt time.Time) (Timer, error)
- func (s *Store) List(ctx context.Context, sessionID string) ([]Timer, error)
- func (s *Store) MarkDelivered(ctx context.Context, ids []string) error
- func (s *Store) Prune(ctx context.Context, olderThan time.Time) (int64, error)
- func (s *Store) Undelivered(ctx context.Context, sessionID string) ([]Timer, error)
- type Timer
Constants ¶
const ( StatusPending = "pending" StatusDue = "due" StatusDelivered = "delivered" StatusCancelled = "cancelled" )
Timer states. pending is waiting for its fire_at; due has been claimed by a claim scan and is waiting to be delivered into its session; delivered has reached the session; cancelled was withdrawn before it fired. delivered and cancelled are terminal.
Variables ¶
var ErrNotFound = errors.New("timer not found")
ErrNotFound reports that a timer is not there to act on: absent, owned by another session, or already terminal.
Functions ¶
This section is empty.
Types ¶
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is the project database's set of agent timers. The schema is created by migration 068, which runs when the project database opens.
func (*Store) Cancel ¶
Cancel withdraws one of the session's own timers. Only a pending or due timer can be cancelled: an absent id, another session's id, or an already delivered or cancelled one all come back as ErrNotFound, and a cancelled timer is returned.
func (*Store) ClaimDue ¶
ClaimDue moves every pending timer whose deadline has passed to due and returns exactly the rows it moved. The condition lives in the UPDATE, not a read-then-write above it, and RETURNING is part of the same statement: a second claimant's scan touches only rows still pending, so two claimants — two servers or a retry after a crash — can never both return one timer and fire its note twice. Rows already marked due stay out of the claim, so an unreported delivery is handed over by Undelivered instead.
func (*Store) Create ¶
func (s *Store) Create(ctx context.Context, sessionID, note string, fireAt time.Time) (Timer, error)
Create schedules note for delivery into sessionID's loop at fireAt.
func (*Store) List ¶
List returns the session's timers that are still live to fire or to be delivered — pending and due — in fire_at order. Terminal ones are history.
func (*Store) MarkDelivered ¶
MarkDelivered records that these claimed timers reached their sessions. A delivered timer is terminal and never reclaimed. An empty list is a no-op.
func (*Store) Prune ¶
Prune deletes the terminal timers — delivered and cancelled — whose updated_at predates olderThan, and returns how many rows went. Pending and due rows are never touched: a due row is still owed to its session (the next turn's catch-up delivers it), so a reminder the agent asked for is never silenced by housekeeping, even when its session can never run again.
func (*Store) Undelivered ¶
Undelivered returns the session's claimed-but-not-yet-delivered timers: a delivery the server saw through the claim but crashed before reporting is still owed to its session after the restart.
Source Files