configsource

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package configsource provides the bounded fixed-path configuration source for runtime reload (versioned-runtime-reloadable-proxy-configuration).

FixedSource resolves an absolute startup path and implements ReadStable with handle re-stat, path revalidation, and atomic-replacement enforcement. This package must not grow a file watcher, mtime poller, or automatic reload loop.

Index

Constants

View Source 
const (
	CategoryOK                = config.CategoryOK
	CategoryMissing           = config.CategoryMissing
	CategoryEmpty             = config.CategoryEmpty
	CategoryWhitespace        = config.CategoryWhitespace
	CategoryOversize          = config.CategoryOversize
	CategoryUnstable          = config.CategoryUnstable
	CategoryNonAtomicUpdate   = config.CategoryNonAtomicUpdate
	CategoryUnsupportedType   = config.CategoryUnsupportedType
	CategoryMalformedYAML     = config.CategoryMalformedYAML
	CategoryMultipleDocuments = config.CategoryMultipleDocuments
	CategoryTrailingContent   = config.CategoryTrailingContent
	CategoryUnknownCoreField  = config.CategoryUnknownCoreField
	CategoryPartialUnreadable = config.CategoryPartialUnreadable
)
View Source 
const DefaultMaxBytes int64 = config.DefaultConfigMaxBytes

DefaultMaxBytes is the startup-fixed upper bound for one accepted source snapshot.

Variables

This section is empty.

Functions

func ClassifyAtomicReplacement 

func ClassifyAtomicReplacement(active ActiveSourceVersion, candidate SourceSnapshot) (AtomicResult, Category, error)

func IsSourceCleanupError 

func IsSourceCleanupError(err error) bool

IsSourceCleanupError reports whether err contains a source close failure.

func MarkSourceCleanupFailure 

func MarkSourceCleanupFailure(err error) error

MarkSourceCleanupFailure wraps a cleanup cause with the bounded private marker consumed by runtime cleanup telemetry and keeps the cause available through errors.Is/errors.As. Its string form never includes the cause.

func SafeReasonOf 

func SafeReasonOf(err error) string

SafeReasonOf returns only the bounded private reason attached to source lease integrity failures. It never returns operating-system error text.

Types

type ActiveSourceVersion 

type ActiveSourceVersion struct {
	HandleIdentity FileIdentity
	PrivateDigest  [32]byte
	// contains filtered or unexported fields
}

ActiveSourceVersion is the last accepted source identity used for no-op / non-atomic comparisons (published generation or effective no-op baseline).

func (*ActiveSourceVersion) Borrow 

func (v *ActiveSourceVersion) Borrow() (*SourceBorrow, error)

Borrow acquires a non-owning validated lease borrow. Native non-Linux identity schemes do not require a retained source descriptor.

func (*ActiveSourceVersion) RequiresLease 

func (v *ActiveSourceVersion) RequiresLease() bool

RequiresLease reports whether this version depends on Linux's retained descriptor identity scheme.

type AtomicResult 

type AtomicResult string

ClassifyAtomicReplacement enforces requirement 2.9: changed content with the same handle identity is a non-atomic in-place update; identical digest may no-op; a new identity is eligible for reload. 

const (
	AtomicEligible AtomicResult = "eligible"
	AtomicNoop     AtomicResult = "noop"
	AtomicReject   AtomicResult = "reject_non_atomic"
)

func LoadEffectiveFromPath 

func LoadEffectiveFromPath(ctx context.Context, path string, active *ActiveSourceVersion, opts config.LoadEffectiveOptions) (*config.EffectiveConfig, AtomicResult, error)

LoadEffectiveFromPath resolves one fixed source and delegates to LoadEffective.

type Category 

type Category = config.LoadCategory

Category aliases the core secret-safe load category so driving adapters and typed decoding report one stable vocabulary without reversing dependencies.

func CategoryOf 

func CategoryOf(err error) (Category, bool)

CategoryOf returns the integrity/decode category when err wraps or is an IntegrityError or a config.LoadError from the shared effective-load pipeline.

func ClassifyBytes 

func ClassifyBytes(raw []byte, maxBytes int64) (Category, error)

ClassifyBytes classifies a raw snapshot against the bounded source contract before typed YAML decode. It does not decode YAML; empty/whitespace/oversize are rejected here so decode never sees them.

maxBytes <= 0 selects DefaultMaxBytes. Classification is secret-safe: errors never include the raw payload.

func ClassifyPathPresence 

func ClassifyPathPresence(exists, isRegular bool) (Category, error)

ClassifyPathPresence maps filesystem presence to a source category without reading contents. Used by table fixtures and the future ReadStable path.

func ClassifyStability 

func ClassifyStability(beforeSize, afterSize int64, beforeID, afterID FileIdentity) (Category, error)

ClassifyStability rejects torn/partial reads where handle metadata changed across the bounded read window (requirement 2.1–2.2).

type FileIdentity 

type FileIdentity struct {
	Platform string
	Scheme   string
	Opaque   [32]byte
}

FileIdentity is a platform-stable handle identity used to prove atomic replacement. Scheme records the provenance of Opaque so identities derived from different metadata can never be mistaken for the same physical file.

type FixedSource 

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

FixedSource is the startup-fixed absolute configuration path used by every reload. It does not watch the filesystem; callers must invoke ReadStable explicitly after an operator trigger.

func NewFixedSource 

func NewFixedSource(path string, maxBytes int64) (*FixedSource, error)

NewFixedSource resolves path to an absolute location and stores the startup-fixed size limit. maxBytes <= 0 selects DefaultMaxBytes.

func (*FixedSource) AbsolutePath 

func (s *FixedSource) AbsolutePath() string

AbsolutePath returns the startup-resolved absolute source path.

func (*FixedSource) LoadEffective 

func (s *FixedSource) LoadEffective(ctx context.Context, active *ActiveSourceVersion, opts config.LoadEffectiveOptions) (effective *config.EffectiveConfig, result AtomicResult, err error)

LoadEffective reads one stable snapshot from s and runs the shared pure effective-configuration pipeline. Filesystem ownership remains in this driving adapter; core/config only sees bounded bytes and explicit options.

func (*FixedSource) MaxBytes 

func (s *FixedSource) MaxBytes() int64

MaxBytes returns the startup-fixed read limit.

func (*FixedSource) ReadStable 

func (s *FixedSource) ReadStable(ctx context.Context, active *ActiveSourceVersion) (snap SourceSnapshot, result AtomicResult, err error)

ReadStable opens the fixed path, captures handle identity, reads one bounded snapshot, revalidates the same candidate handle and a second path handle, classifies the bytes, and enforces atomic-replacement rules against active when non-nil. On supported Linux ext4, the accepted descriptor is retained as the source lease until its owner is closed.

type IntegrityError 

type IntegrityError struct {
	Category Category
	Limit    int64 // set for oversize; otherwise 0
	// contains filtered or unexported fields
}

IntegrityError is a secret-safe source-integrity or pre-decode failure. Error strings carry only the category (and bounded limits), never raw bytes.

func (*IntegrityError) Error 

func (e *IntegrityError) Error() string

type SourceBorrow 

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

SourceBorrow keeps a validated source core open until Release. It exposes no descriptor and carries no close authority. Copies share one release token.

func (*SourceBorrow) Release 

func (b *SourceBorrow) Release()

func (*SourceBorrow) ValidateBaseline 

func (b *SourceBorrow) ValidateBaseline(version *ActiveSourceVersion) error

ValidateBaseline confirms that this borrow matches the supplied source baseline and that its pinned handle has not changed stable metadata.

func (*SourceBorrow) ValidateProvenance 

func (b *SourceBorrow) ValidateProvenance(version *ActiveSourceVersion) error

ValidateProvenance confirms that the borrow belongs to the live pinned owner for version. It intentionally does not compare current content times: a rejected in-place edit may later be repaired by an atomic replacement.

type SourceLeaseOwner 

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

SourceLeaseOwner is the sole close-capable token for an accepted source handle. Copies of this pointer share one synchronized close authority.

func (*SourceLeaseOwner) Close 

func (o *SourceLeaseOwner) Close(ctx context.Context) error

Close requests closure and waits for completion only until ctx expires. The underlying Close call is synchronous and is never retried.

func (*SourceLeaseOwner) RequestClose 

func (o *SourceLeaseOwner) RequestClose() error

RequestClose prevents future borrows and closes the file immediately when no borrow is active. If a borrow remains, its final Release performs close.

func (*SourceLeaseOwner) WaitClosed 

func (o *SourceLeaseOwner) WaitClosed(ctx context.Context) error

WaitClosed waits for the owner close requested by RequestClose. It does not initiate close itself, which lets shutdown remain nonblocking while readers still hold borrows.

type SourceOwnerSlot 

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

SourceOwnerSlot is a destructive handoff slot. Take atomically clears the slot, so copied metadata or outcome records cannot close a moved owner.

func NewSourceOwnerSlot 

func NewSourceOwnerSlot(owner *SourceLeaseOwner) *SourceOwnerSlot

NewSourceOwnerSlot creates a takeable slot for owner handoff between the configsource, runtimehost, and runtimebundle packages.

func (*SourceOwnerSlot) Close 

func (s *SourceOwnerSlot) Close(ctx context.Context) error

Close takes and closes the owner remaining in the slot. A caller that already moved the owner gets a harmless nil result.

func (*SourceOwnerSlot) IsEmpty 

func (s *SourceOwnerSlot) IsEmpty() bool

IsEmpty reports whether the slot currently contains no close authority.

func (*SourceOwnerSlot) Matches 

func (s *SourceOwnerSlot) Matches(version *ActiveSourceVersion) bool

Matches reports whether this slot contains the owner whose private core backs version. It does not transfer close authority.

func (*SourceOwnerSlot) MoveMatchingTo 

func (s *SourceOwnerSlot) MoveMatchingTo(destination *SourceOwnerSlot, version *ActiveSourceVersion) (*SourceLeaseOwner, bool)

MoveMatchingTo atomically consumes this slot only if it still contains the lease paired with version. An ownerless native version is valid and clears the destination owner so metadata and close authority stay aligned.

func (*SourceOwnerSlot) MoveTo 

func (s *SourceOwnerSlot) MoveTo(destination *SourceOwnerSlot) *SourceLeaseOwner

MoveTo atomically transfers this slot's owner into an already allocated destination slot and returns the destination's displaced owner.

func (*SourceOwnerSlot) SetCleanupObserver 

func (s *SourceOwnerSlot) SetCleanupObserver(fn func(error))

SetCleanupObserver installs the bounded runtime cleanup sink on the owner still held in this slot. It does not move or otherwise expose the owner.

func (*SourceOwnerSlot) Take 

func (s *SourceOwnerSlot) Take() *SourceLeaseOwner

Take moves the slot's owner to the caller and leaves the slot empty.

func (*SourceOwnerSlot) ValidFor 

func (s *SourceOwnerSlot) ValidFor(version *ActiveSourceVersion) bool

ValidFor reports whether the slot and version describe one valid lease pair. Native and unsupported-Linux versions have no lease owner; supported Linux versions must retain the exact core recorded in the version.

type SourceSnapshot 

type SourceSnapshot struct {
	SourceID       string
	HandleIdentity FileIdentity
	Size           int64
	ModTime        time.Time
	PrivateDigest  [32]byte
	Bytes          []byte
	ReadAt         time.Time
	// contains filtered or unexported fields
}

SourceSnapshot is one accepted bounded read of the fixed startup path.

func (*SourceSnapshot) Close 

func (s *SourceSnapshot) Close(ctx context.Context) error

Close releases an owner still held by this snapshot, if one was not moved with TakeBaseline.

func (*SourceSnapshot) SetCleanupObserver 

func (s *SourceSnapshot) SetCleanupObserver(fn func(error))

SetCleanupObserver attaches the bounded runtime cleanup observer to the snapshot's owner, if a supported-platform lease exists.

func (*SourceSnapshot) TakeBaseline 

func (s *SourceSnapshot) TakeBaseline() (*ActiveSourceVersion, *SourceOwnerSlot)

TakeBaseline creates comparison metadata and moves any accepted owner into a fresh destructive slot. The metadata itself has no close authority.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.