Documentation
¶
Overview ¶
Package follower follows ENTITY_STATES for a projection owner: it waits for the bucket, holds the one watch on it, replays the stored entities and then the live writes in delivery order, and keeps the owner's readiness: the watermark of applied revisions, the bootstrap latch, the reset latch, the lost-feed state, and the envelope it publishes to GRAPH_STATUS on every heartbeat (ADR-108 D4). The owner, a plug-in, takes each entry through Config.Deliver and reports each outcome back: Complete when a revision is applied, Config.Failed for its unresolved writes, Reset when its state can no longer be trusted. graph-index is the first owner.
Limits, declared rather than promised:
- A lost feed is never repaired. When the watch cannot start, closes, delivers a revision out of order, or reads a stream other than the one Open bound, the follower says so (Stuck, a degraded envelope, QueryReady refusing) until the process restarts; nothing rebinds the watch.
- A restored stream can go unnoticed. The third trigger compares the backing stream's creation time with the one Open read; a stream deleted and restored with that creation time inside one stall of the watch reads as the same stream, and the revisions it skipped are not declared.
- How long a watch stalls after a reconnect, and when a deleted bucket closes it, is nats.go's timing (about 20 s at nats.go v1.54.0, PR #414 comments 6425769680 and 6426443564), not promised here.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
Client *natsclient.Client
// Key is the producer's GRAPH_STATUS key (readiness.KeyGraphIndex). The gauges' Prometheus
// subsystem is derived from it ("graph-index" becomes "graph_index"), so the name is spelled once.
Key string
// MetricsRegistry takes the readiness gauges. Nil registers nothing.
MetricsRegistry *metric.MetricsRegistry
// Logger defaults to slog.Default().
Logger *slog.Logger
// StartupAttempts and StartupInterval bound Open's wait for ENTITY_STATES; zero takes
// internal/resource's defaults.
StartupAttempts int
StartupInterval time.Duration
// Deliver takes one entry, in delivery order, on Run's goroutine. It is called after the
// revision is in the watermark; the plug-in calls Complete once it is applied.
Deliver func(ctx context.Context, e Entry)
// Failed returns the plug-in's count of unresolved required writes and, when it tracks them,
// the count per bounded reason; nil reasons when it does not. The follower calls it once per
// envelope, so count and reasons come from one moment, and owns the map it returns: the
// plug-in returns a fresh one and keeps no reference to it.
Failed func() (count int64, reasons map[string]uint64)
// Withhold, when set, returns the count of the plug-in's failures that withhold queries; nil
// means Failed's count. After the first build QueryReady refuses on failures only while it
// returns above 0. Before the first build the gate reads the envelope, and the envelope and
// Stuck always read Failed, so a failure Withhold leaves out still reads degraded.
Withhold func() int64
}
Config is what Open needs. Client, Key, Deliver and Failed are required.
type Entry ¶
type Entry struct {
Key string
Revision uint64
Deleted bool // a delete or purge marker
Bytes int // the delivered value's length; 0 for a delete or purge marker
}
Entry is one delivered ENTITY_STATES write.
type Follower ¶
type Follower struct {
// contains filtered or unexported fields
}
Follower follows ENTITY_STATES for one plug-in. Build it with Open and run it with Run.
func Open ¶
Open waits for ENTITY_STATES up to Config.StartupAttempts times Config.StartupInterval, opens its readers, ensures GRAPH_STATUS and registers the readiness gauges. It does its work under ctx and starts nothing: the watch begins in Run. An absent bucket after the wait is a transient error naming it.
func (*Follower) Complete ¶
Complete records that revision of key is applied, with every earlier revision of it. Each call counts as progress for the stuck detector, whether or not it raises the floor.
func (*Follower) Indexed ¶
Indexed returns the watermark's floor: every delivered revision at or below it is complete.
func (*Follower) QueryReady ¶
QueryReady says whether a query may be answered now (ADR-109 D1): nil, or a classified refusal. A latched reset is fatal graph_state_reset_required; a lost feed, unresolved writes that withhold queries (Config.Withhold) and an incomplete initial build are transient index_not_ready. Before the initial build is complete the gate reads the envelope, which counts every unresolved write (Config.Failed); once it is complete it answers nil at once.
func (*Follower) Reset ¶
func (f *Follower) Reset(reason graph.StateResetReason)
Reset latches reason for the life of the process. The first reason holds; later calls change nothing (ADR-074, ADR-084 D4).
func (*Follower) Run ¶
Run follows ENTITY_STATES on the caller's goroutine until ctx ends, then returns with the watch stopped, its delivery closed and its heartbeat goroutine joined. It returns nil, or the watch's Stop error when that error says more than that the watch was already gone. It waits for the delivery to close for at most watchDrainBudget (see stopWatch) and then returns errWatchDeliveryOpen. It publishes the envelope once at once and then every readiness.DefaultHeartbeat, on a goroutine of its own, so a Deliver that blocks does not delay a heartbeat. A nil context is refused.