Documentation
¶
Index ¶
- Variables
- type ChangeKind
- type PrepareInput
- type PreparedSnapshot
- type SeedStamp
- type ServerChange
- type ServerGen
- type Service
- func (s *Service) AddPrePublishObserver(observe func(*config.Config))
- func (s *Service) Close()
- func (s *Service) Current() *Snapshot
- func (s *Service) Prepare(in PrepareInput) (*PreparedSnapshot, error)
- func (s *Service) Publish(p *PreparedSnapshot) (*Snapshot, error)
- func (s *Service) SaveToFile() error
- func (s *Service) SeedVersion(v int64)
- func (s *Service) Subscribe(ctx context.Context) <-chan Update
- func (s *Service) Unsubscribe(ch <-chan Update)
- func (s *Service) Update(newConfig *config.Config, updateType UpdateType, source string) error
- func (s *Service) UpdateIfCurrent(expected, newConfig *config.Config, updateType UpdateType, source string) (bool, error)
- func (s *Service) UpdatePath(newPath string)
- func (s *Service) Version() int64
- type Snapshot
- type Update
- type UpdateType
Constants ¶
This section is empty.
Variables ¶
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
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 ¶
NewService creates a new configuration service with the given initial config.
func (*Service) AddPrePublishObserver ¶ added in v0.68.0
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 ¶
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 ¶
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
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 ¶
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 ¶
Unsubscribe removes a subscriber channel and closes it.
func (*Service) Update ¶
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 ¶
UpdatePath updates the configuration file path.
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) 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 ¶
ServerCount returns the number of servers in this snapshot.
func (*Snapshot) ServerGeneration ¶ added in v0.71.0
ServerGeneration returns the committed generation of one server.
func (*Snapshot) ServerNames ¶
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 )