configsvc

package
v0.73.0-rc.1 Latest Latest
Warning

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

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

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrConcurrentPublish = errors.New("configsvc: concurrent publish")

ErrConcurrentPublish reports that a prepared snapshot was published after another publication moved the version it was prepared against. Under the runtime's commit lock this is an invariant violation.

Functions

This section is empty.

Types

type ChangeKind added in v0.71.0

type ChangeKind int

ChangeKind classifies one server's change in a commit.

const (
	// ChangeCreated: the name is absent from the base snapshot.
	ChangeCreated ChangeKind = iota + 1
	// ChangeUpdated: the entry exists in both and is not ServerEntryEqual.
	ChangeUpdated
	// ChangeRemoved: the name is absent from the new config.
	ChangeRemoved
	// ChangeReplaced: removed and re-created in one commit (review R8.2). Every
	// consumer treats it as Removed(Old) followed by Created(New).
	ChangeReplaced
)

func (ChangeKind) String added in v0.71.0

func (k ChangeKind) String() string

type PrepareInput added in v0.71.0

type PrepareInput struct {
	Config   *config.Config
	Source   string
	Type     UpdateType
	Replaced map[string]bool
	// Seed carries stored stamps for servers whose base snapshot has no
	// generation, so generations survive a restart (data-model §2, D13).
	Seed map[string]SeedStamp
	// OAuthCleared names the servers whose cached OAuth state this commit
	// clears because their OAuth configuration changed (Spec 116 PR2b,
	// data-model §2): their OAuthEpoch moves to G, so an instance built for
	// the previous OAuth configuration holds a stale credential binding and
	// none of its OAuth writes can land after the clear.
	OAuthCleared map[string]bool
	// Path, when non-empty, is the config file path the snapshot publishes
	// with. It moves only when Publish succeeds (Spec 116 PR1 review round 3:
	// a failed commit must not leave a new path published).
	Path string
}

PrepareInput is everything Prepare needs. Replaced names a server the commit removed and re-created (review R8.2): the final config alone cannot tell that from an unchanged or updated entry. Every replaced name must be present in both the base and the new config.

type PreparedSnapshot added in v0.71.0

type PreparedSnapshot struct {
	Changes map[string]ServerChange
	// contains filtered or unexported fields
}

PreparedSnapshot is a snapshot computed against a base version and not yet visible. Changes describes the commit from the same inputs, so the snapshot, the commit result and the stored rows cannot disagree.

func (*PreparedSnapshot) ChangedNames added in v0.71.0

func (p *PreparedSnapshot) ChangedNames() []string

ChangedNames returns the names in Changes, sorted.

func (*PreparedSnapshot) Generation added in v0.71.0

func (p *PreparedSnapshot) Generation() int64

Generation is the commit generation G this snapshot will publish as.

func (*PreparedSnapshot) Snapshot added in v0.71.0

func (p *PreparedSnapshot) Snapshot() *Snapshot

Snapshot is the snapshot that Publish will make current. Callers must treat it as read-only.

type SeedStamp added in v0.71.0

type SeedStamp struct {
	Stamp   ServerGen
	Matches bool
}

SeedStamp is the stored stamp of a server whose base snapshot carries no generation (the snapshot NewService was built with). Matches reports whether the stored row describes the same configuration as the new entry.

type ServerChange added in v0.71.0

type ServerChange struct {
	Kind ChangeKind
	Old  ServerGen // zero when Created
	New  ServerGen // zero when Removed
	// Reconnect is true when the connection settings, Enabled or Quarantined
	// changed (config.ConnectionEquivalent is false); always true for
	// Created, Removed and Replaced.
	Reconnect bool
	// QuarantineRaised is true when the server is quarantined in the new
	// config and was not in the base (or did not exist).
	QuarantineRaised bool
}

ServerChange is one server's change in a commit (Spec 116 data-model §1).

type ServerGen added in v0.71.0

type ServerGen = commitview.ServerGen

ServerGen is the committed {generation, incarnation} of one server. It lives in the leaf package commitview so configsvc and storage never import each other (Spec 116 review R7.2).

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service manages configuration state with lock-free reads and atomic updates.

Key design principles: 1. Reads are lock-free via atomic.Value (no mutex contention) 2. Updates are serialized through a single mutex 3. Subscribers receive updates via buffered channels 4. File I/O is decoupled from snapshot reads

func NewService

func NewService(initialConfig *config.Config, configPath string, logger *zap.Logger) *Service

NewService creates a new configuration service with the given initial config.

func (*Service) AddPrePublishObserver added in v0.68.0

func (s *Service) AddPrePublishObserver(observe func(*config.Config))

AddPrePublishObserver registers a read-only observer of every configuration on its way into the snapshot. Observers run inside the update, after the pre-publish hook has produced the final config and before the snapshot is stored or any subscriber is notified — so they see the exact *Config that will be published, at a moment nothing else can. They must not mutate it, and because they run under the update mutex they must be cheap (an index build of one insertion per entry, not I/O).

Observers run with the update mutex held and MUST NOT publish: a call to Update, UpdateIfCurrent or Publish from inside an observer is a re-entrant publish and deadlocks by design. Registering a further observer from inside one is allowed — the list is not locked while observers run — and that observer first runs on the next publication.

Nil observers and a nil service are ignored. Safe to call at any time, including from an observer.

func (*Service) Close

func (s *Service) Close()

Close cleans up the service and closes all subscriber channels.

func (*Service) Current

func (s *Service) Current() *Snapshot

Current returns the current configuration snapshot. This is a lock-free operation that returns an immutable snapshot.

func (*Service) Prepare added in v0.71.0

func (s *Service) Prepare(in PrepareInput) (*PreparedSnapshot, error)

Prepare computes the next snapshot for in.Config against the current one without making it visible (Spec 116 two-phase publish). It assigns the commit generation G = version+1, the per-server generations and the change set. Publish makes it current. The runtime's commit lock serializes Prepare/Publish pairs; Publish refuses a snapshot whose base version moved.

func (*Service) Publish added in v0.71.0

func (s *Service) Publish(p *PreparedSnapshot) (*Snapshot, error)

Publish makes a prepared snapshot current: it runs the pre-publish observers, stores the snapshot and notifies subscribers.

func (*Service) SaveToFile

func (s *Service) SaveToFile() error

SaveToFile persists the current configuration to disk. This operation blocks on file I/O but doesn't hold any locks.

func (*Service) SeedVersion added in v0.71.0

func (s *Service) SeedVersion(v int64)

SeedVersion raises the version counter to v so the next commit generation is greater than every generation persisted by an earlier process (Spec 116 D6). It never lowers the counter.

func (*Service) Subscribe

func (s *Service) Subscribe(ctx context.Context) <-chan Update

Subscribe returns a channel that receives configuration updates. The channel has a buffer size of 10 to prevent blocking publishers. The caller should stop reading from the channel and call Unsubscribe when done.

func (*Service) Unsubscribe

func (s *Service) Unsubscribe(ch <-chan Update)

Unsubscribe removes a subscriber channel and closes it.

func (*Service) Update

func (s *Service) Update(newConfig *config.Config, updateType UpdateType, source string) error

Update atomically updates the configuration and notifies all subscribers. It is Prepare+Publish without replacement metadata; after Spec 116 only the runtime's commit (and tests) call it.

func (*Service) UpdateIfCurrent added in v0.66.1

func (s *Service) UpdateIfCurrent(expected, newConfig *config.Config, updateType UpdateType, source string) (bool, error)

UpdateIfCurrent atomically publishes newConfig only when expected is still the active configuration pointer. It closes the check-then-update race for derived snapshots: a newer config must never be overwritten by a stale copy prepared before it was committed.

func (*Service) UpdatePath

func (s *Service) UpdatePath(newPath string)

UpdatePath updates the configuration file path.

func (*Service) Version

func (s *Service) Version() int64

Version returns the current configuration version number.

type Snapshot

type Snapshot struct {
	Config *config.Config
	Path   string
	// Version is monotonically increasing. Since Spec 116 it is the commit
	// generation G of the commit that published this snapshot, and it is
	// seeded from storage at startup, so it also increases across restarts.
	Version   int64
	Timestamp time.Time
	// ServerGenerations holds each configured server's committed generation
	// (Spec 116 data-model §2). Immutable once published. Nil on the snapshot
	// NewService was constructed with, which predates any commit.
	ServerGenerations map[string]ServerGen
}

Snapshot is an immutable point-in-time view of the configuration. It allows lock-free reads without blocking on disk I/O or mutations.

func (*Snapshot) Clone

func (s *Snapshot) Clone() *config.Config

Clone creates a deep copy of the configuration to ensure immutability.

func (*Snapshot) GetServer

func (s *Snapshot) GetServer(name string) *config.ServerConfig

GetServer returns a copy of the server configuration by name, or nil if not found.

func (*Snapshot) ServerCount

func (s *Snapshot) ServerCount() int

ServerCount returns the number of servers in this snapshot.

func (*Snapshot) ServerGeneration added in v0.71.0

func (s *Snapshot) ServerGeneration(name string) (ServerGen, bool)

ServerGeneration returns the committed generation of one server.

func (*Snapshot) ServerNames

func (s *Snapshot) ServerNames() []string

ServerNames returns a list of all server names in this snapshot.

type Update

type Update struct {
	Snapshot  *Snapshot
	Type      UpdateType
	ChangedAt time.Time
	Source    string // e.g., "file_watcher", "api_request", "initial_load"
}

Update represents a configuration change notification.

type UpdateType

type UpdateType string

UpdateType describes the nature of a configuration update.

const (
	UpdateTypeReload UpdateType = "reload" // Config reloaded from disk
	UpdateTypeModify UpdateType = "modify" // In-memory modification
	UpdateTypeInit   UpdateType = "init"   // Initial configuration load
)

Jump to

Keyboard shortcuts

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