follower

package
v0.1.0-alpha.4 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: MIT Imports: 20 Imported by: 0

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
	// Value is the value the watch delivered for Revision; nil for a delete or purge marker. It is
	// valid only for the duration of Deliver: a plug-in that keeps it copies it. A plug-in that
	// re-reads current truth at apply time does not apply Value (ADR-108 D4); one that applies it
	// ignores a delivery at or below the revision it last applied for the key, since the watch's
	// order across keys is not promised and the follower only declares a revision out of order.
	Value []byte
}

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

func Open(ctx context.Context, cfg Config) (*Follower, error)

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

func (f *Follower) Complete(key string, revision uint64)

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

func (f *Follower) Indexed() uint64

Indexed returns the watermark's floor: every delivered revision at or below it is complete.

func (*Follower) QueryReady

func (f *Follower) QueryReady(ctx context.Context) error

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

func (f *Follower) Run(ctx context.Context) error

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.

func (*Follower) Stuck

func (f *Follower) Stuck() []string

Stuck returns the states that hold now, each a short sentence: a latched reset, the plug-in's unresolved failures (Config.Failed's count, then each reason with its count in name order when it reports reasons), and a lost feed. It is empty when none holds.

Jump to

Keyboard shortcuts

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