Documentation
¶
Overview ¶
Package config owns the configuration the node's owner edits: node settings, the access policy, presets, adapter instances with their endpoint settings, the stable endpoint identifiers, the revocation records the node keeps, and the installed adapter packages. See README.md for the rules and docs/references/configuration for the reasons.
Index ¶
- Constants
- Variables
- func AdapterCurrentPath(id string) string
- func AdapterDir(id string) string
- func AdapterManifestPath(id, version string) string
- func AdapterRevisionDir(id, version string, revision uint32) string
- func AdapterStageDir(id, suffix string) string
- func AdapterVersionDir(id, version string) string
- func AdapterVersionsDir(id string) string
- func BackupWrite() txn.Write
- func DecodeRevocation(name string, data []byte) (revocation.Revocation, record.Record, error)
- func DefaultListen(port int) ([]string, error)
- func EncodeAdapterCurrent(c AdapterCurrent) ([]byte, error)
- func EndpointIDsPath(instance string) string
- func EndpointIDsWrite() txn.Write
- func InitWrites() []txn.Write
- func InstallOldWrite() txn.Write
- func InstallWrites() []txn.Write
- func LayoutDirs() []string
- func RevocationPath(d record.Digest) string
- func RevocationWrite() txn.Write
- func Transactions() []*txn.Decl
- func ValidateListen(addr string) error
- func ValidatePeerAddress(addr string) error
- func ValidatePort(port int) error
- type Adapter
- type AdapterCurrent
- type AfterCommit
- type Backup
- type ChangeError
- type ChangeReason
- type Config
- func (c *Config) Adapters() []Adapter
- func (c *Config) AddPreset(req Request, name string, preset []byte, result ResultFunc[Presets]) (Presets, error)
- func (c *Config) Backup() (Backup, bool)
- func (c *Config) DirectID(instance, key string, rnd io.Reader) (IDChange, error)
- func (c *Config) DisableAdapter(req Request, instance string, open OpenEndpoints, result ResultFunc[Instances]) (Instances, error)
- func (c *Config) DropTrash(t Trash) error
- func (c *Config) EnableAdapter(req Request, instance, adapter string, instanceConfig []byte, ...) (Instances, error)
- func (c *Config) EndpointIDs(instance string) EndpointIDs
- func (c *Config) EndpointSettings(instance string, id ident.EndpointID) EndpointSettings
- func (c *Config) Instances() Instances
- func (c *Config) LastOperations() []Operation
- func (c *Config) Network() Network
- func (c *Config) Node() Node
- func (c *Config) PlanInstall(s Staged, ending StillEnding) (Install, error)
- func (c *Config) Policy() PolicyFile
- func (c *Config) Presets() Presets
- func (c *Config) PutBackup(tx *txn.Tx, p PreparedBackup) (AfterCommit, error)
- func (c *Config) PutEndpointIDs(tx *txn.Tx, ch IDChange) (AfterCommit, error)
- func (c *Config) PutRevocation(tx *txn.Tx, p PreparedRevocation) (AfterCommit, error)
- func (c *Config) RemoveInstance(req Request, instance, stateDir string, sessions OpenSessions, ...) (Instances, Trash, error)
- func (c *Config) RemovePeer(req Request, node ident.NodeID, result ResultFunc[Network]) (Network, error)
- func (c *Config) RemovePreset(req Request, name string, result ResultFunc[Presets]) (Presets, error)
- func (c *Config) RevocationSet() *revocation.Set
- func (c *Config) Revocations() []revocation.Revocation
- func (c *Config) RuntimeID(instance string, rnd io.Reader) (IDChange, error)
- func (c *Config) SetEndpointSettings(req Request, instance string, endpoint ident.EndpointID, patch []byte, ...) (Instances, error)
- func (c *Config) SetInstanceConfig(req Request, instance string, instanceConfig []byte, open OpenEndpoints, ...) (Instances, error)
- func (c *Config) SetListen(req Request, listen []string, result ResultFunc[Network]) (Network, error)
- func (c *Config) SetNodeSettings(req Request, patch []byte, result ResultFunc[Node]) (Node, error)
- func (c *Config) SetPeerAddresses(req Request, node ident.NodeID, addrs []string, result ResultFunc[Network]) (Network, error)
- func (c *Config) StageAdapter(src fsx.Reader, rnd io.Reader) (Staged, error)
- func (c *Config) Unstage(s Staged) error
- type EndpointIDs
- type EndpointOverride
- type EndpointPatch
- type EndpointSettings
- type FieldError
- type FileError
- type FileKind
- type FileReason
- type GCItem
- type GCReason
- type IDChange
- type InitOptions
- type InitPlan
- type Install
- type Instance
- type Instances
- type Network
- type Node
- type NodePatch
- type NodeSettings
- type OpenEndpoints
- type OpenSessions
- type Operation
- type PolicyFile
- type PreparedBackup
- type PreparedRevocation
- type Preset
- type Presets
- type Request
- type ResultFunc
- type SourceError
- type Staged
- type StillEnding
- type Trash
Constants ¶
const ( // RoleDir creates the directories of config/ (init). RoleDir = "dir" // RoleNode, RolePolicy, RolePresets and RoleInstances replace the file of // that name; RoleNetworkConfig replaces network.json (the role "network" is // the network key of keys, in the same transaction). RoleNode = "node" RolePolicy = "policy" RolePresets = "presets" RoleInstances = "instances" RoleNetworkConfig = "network-config" // RoleEndpointIDs replaces the endpoint-id file of one instance. RoleEndpointIDs = "ids" // RoleBackup replaces revocation-backup.json. RoleBackup = "backup" // RoleRevocation writes one revocation record. RoleRevocation = "revocation" // RoleVersion, RoleCurrent and RoleOld are the writes of an adapter // installation: rename the staging directory to the version, replace the // current pointer, discard the previous version. RoleVersion = "version" RoleCurrent = "current" RoleOld = "old" )
The roles of the writes this package offers to transactions of other packages. A transaction that spans owners is declared by the package that composes it, with these names, and every write function below writes only under the role it is documented with.
const ( // DefaultListenPort is the port `init` makes the node listen on unless the // owner names another. DefaultListenPort = 7744 // MaxAddressesPerNode is the most addresses one list holds: the listen // list, and the list of one peer. It is the limit of an address list in a // pairing record, so an address the book holds can be offered in one. MaxAddressesPerNode = pairing.MaxAddresses // MaxAddressLen is the longest address, in bytes, by the same reasoning. MaxAddressLen = pairing.MaxAddressLen )
const ( // DefaultNodeQueueLimit is how many unfinished deliveries the node holds. DefaultNodeQueueLimit = 10000 // DefaultDiskReserveBytes is the free space below which new work is refused. DefaultDiskReserveBytes = 256 << 20 // DefaultLogTotalBytes is the space all logs together may take. DefaultLogTotalBytes = 150 << 20 // DefaultArchiveRetentionDays is how long the archive keeps its summaries. DefaultArchiveRetentionDays = 30 // OpenDeliveryDiskGrowth is what an unfinished delivery adds to the disk // before it is finished and archived: its summary and the // feedback it may give rise to. The disk reserve must cover this for as many // deliveries as the queue holds, plus the logs. OpenDeliveryDiskGrowth = 4 << 10 // MaxArchiveRetentionDays is the most days of retention a time.Duration can // hold. A larger number would wrap around to a negative or short retention // in ArchiveRetention, and the archive would then discard its summaries at // once. The limit is almost three centuries, which no owner needs. MaxArchiveRetentionDays = math.MaxInt64 / int64(24*time.Hour) )
The settings that no other package decides. Each has its reason in the README: the numbers that another package owns are read from it, not repeated.
const ( Dir = "config" NodePath = Dir + "/node.json" PolicyPath = Dir + "/policy.json" PresetsPath = Dir + "/presets.json" InstancesPath = Dir + "/instances.json" NetworkPath = Dir + "/network.json" EndpointIDsDir = Dir + "/endpoint-ids" BackupPath = Dir + "/revocation-backup.json" RevocationsDir = Dir + "/revocations" AdaptersDir = Dir + "/adapters" )
The files of config/, relative to the data directory root.
const (
DefaultPresetName = "default"
)
DefaultPresetName is the one preset `init` writes, and the description it carries.
const FormatVersion = 1
FormatVersion is the format of every file of config/. It is not the version a management request names: it is what a future change of the format reads to know what it migrates.
const MaxPackageBytes = 256 << 20
MaxPackageBytes is the most a package may hold in all, the sizes of its files added up. The whole package is read through a file system the owner points at, one file at a time into memory, so a package without a limit could take the node down by being large; no adapter is anywhere near it, so the limit is a refusal of a mistake (the wrong directory) and never of a package.
const MaxPresets = 20
MaxPresets is the most presets a node has. Every preset is told to a requester in the node's answer to endpoint.status, the answer is one signed record, and a record is read only up to record.DefaultMaxInput (64 KiB) bytes, so the presets together must fit in it whatever they say. The largest a preset can be in the answer, from the bounds of the adapter protocol (adapterproto.MaxPresetNameLen, MaxModelNameLen, MaxAllowedModels and the five efforts of the scale):
name 64 + default model 128 + default effort 6 ("medium")
+ 16 allowed models x (128 + the five efforts, 26)
+ the framing of the encoding = about 2.8 KB
so 23 presets nearly fill the record (64 KiB). Twenty makes the largest reply about 55 KB and leaves about 9.5 KB: room for the rest of the reply (the id of the signal, the conditions, the envelope of the record) and for a bound of the adapter protocol raised a little. TestTheLargestStatusReplyTheLimitOnPresetsAllowsFitsInOneSignedRecord builds that largest reply and fails when a raise of any of the bounds, or of this number, makes it too large to read. AddPreset refuses the preset that would be over the limit; the presets already stored are not checked again, so a node that holds more keeps working, and its status reply is refused when it cannot be read (see the control reply in the engine).
const StageSuffixBytes = 8
StageSuffixBytes is how much randomness StageAdapter reads from its reader to name a staging directory. A caller that may not let the staging read its own source of randomness (the engine draws only in its loop, and staging runs outside it) draws this many bytes first and hands them over.
Variables ¶
var ErrDiskReserveTooLow = errors.New("disk reserve below what the node queue and the logs can fill")
ErrDiskReserveTooLow is wrapped by the error of a disk reserve that the unfinished deliveries and the logs could fill: new work would be refused only after the disk was already full.
var ErrOutOfRange = errors.New("value out of range")
ErrOutOfRange is wrapped by the error of a setting whose own rule is violated: the settings whose limits another package owns return that package's error instead.
Functions ¶
func AdapterCurrentPath ¶
AdapterCurrentPath is the pointer file that names the installed version.
func AdapterDir ¶
AdapterDir is the directory of an adapter: its versions and its pointer.
func AdapterManifestPath ¶
AdapterManifestPath is the manifest of the first package of one version.
func AdapterRevisionDir ¶
AdapterRevisionDir is the immutable package directory of one version at one revision. Revision 0 is the directory of the version itself; a package that is installed when that name is taken (the same version again with other contents, or a version that was replaced earlier and may still be run from) needs a directory of another name, so that the pointer's replacement is what switches packages and no directory is ever replaced in place. The "~" cannot be part of a version.
func AdapterStageDir ¶
AdapterStageDir is the staging directory of an installation, next to the versions so that it can be renamed into one.
func AdapterVersionDir ¶
AdapterVersionDir is the immutable package directory of one version.
func AdapterVersionsDir ¶
AdapterVersionsDir holds the version directories and the staging directories.
func BackupWrite ¶
BackupWrite is the write of PutBackup, in backup-confirm.
func DecodeRevocation ¶
func DecodeRevocation(name string, data []byte) (revocation.Revocation, record.Record, error)
DecodeRevocation decodes the file of a revocation record, verifies it with the rules of the revocation package, and checks that the file is named after the record's digest. name is the name of the file in config/revocations. The error is a *FileError that names the file.
func DefaultListen ¶
DefaultListen is the listen list `init` writes for a port: TCP and QUIC on every IPv4 interface.
func EncodeAdapterCurrent ¶
func EncodeAdapterCurrent(c AdapterCurrent) ([]byte, error)
EncodeAdapterCurrent returns the bytes of a current pointer.
func EndpointIDsPath ¶
EndpointIDsPath is the file of the stable endpoint ids of an instance.
func EndpointIDsWrite ¶
EndpointIDsWrite is the write of PutEndpointIDs, in direct-register and runtime-admit. It is optional: an id that already exists is not written.
func InitWrites ¶
InitWrites are the writes of init that belong to this package, in the order they are made: the directories, then the files that are not already valid. The writes of the other owners and the marker come after.
func InstallOldWrite ¶
InstallOldWrite is the write of Install.DiscardOld, the last of adapter-install. It is optional: a first installation has no previous version.
func InstallWrites ¶
InstallWrites are the writes of adapter-install up to and including the current pointer, in the order of Install's methods: Promote is preparation (a crash before the pointer changes leaves a directory adapter-gc discards), and Point is the commit point. The composer's own write follows, then InstallOldWrite.
func LayoutDirs ¶
func LayoutDirs() []string
LayoutDirs is the directories config/ consists of, each after its parent. `init` creates them and loading refuses a tree that lacks one.
func RevocationPath ¶
RevocationPath is the file of a revocation record.
func RevocationWrite ¶
RevocationWrite is the write of PutRevocation, in identity-retire.
func Transactions ¶
Transactions lists the transactions this package runs itself. The composition root puts them in the table of the program.
func ValidateListen ¶
ValidateListen checks an address the node listens on: /<host>/tcp/<port> or /<host>/udp/<port>/quic-v1, with an ip4, ip6, dns, dns4 or dns6 host. It is the one definition of what a listen address may be.
func ValidatePeerAddress ¶
ValidatePeerAddress checks an address entered for another node: the shapes of ValidateListen, and after them an optional /p2p/<peer id> that must be a libp2p peer identifier. A relay circuit is refused: relaying is not a way the owner can state, and a circuit address would name a third node.
func ValidatePort ¶
ValidatePort checks a port the node is told to listen on: a fixed one, so 0, which would ask the system for any, is refused.
Types ¶
type Adapter ¶
type Adapter struct {
ID string
// Version is the version the current pointer names; empty when the pointer
// could not be read.
Version string
// Digest and Revision are those of the current pointer.
Digest string
Revision uint32
// Manifest is the manifest of the package; the zero value when Fault is set.
Manifest manifest.Manifest
// Fault says why the package on the disk could not be loaded: the pointer or the
// manifest it names is missing, unreadable or invalid, or is of another adapter
// or version. The adapter is still installed, so that an installation replaces
// it, but nothing of it can run. A fault is the package's, never the node's: the
// node loads and the other adapters run.
Fault *FileError
}
Adapter is an installed adapter package.
type AdapterCurrent ¶
type AdapterCurrent struct {
Version string
// Digest is the digest of the contents of the installed package in lower case
// hex; empty for a package installed before the contents were told apart,
// whose contents are then unknown.
Digest string
// Revision numbers the directories of one version: 0 is the directory named by
// the version itself, and an installation takes the first revision whose
// directory does not exist (see AdapterRevisionDir).
Revision uint32
}
AdapterCurrent is what the current pointer of an adapter says: the installed version, the digest of the package's contents and the revision of the version whose directory holds it.
func DecodeAdapterCurrent ¶
func DecodeAdapterCurrent(id string, data []byte) (AdapterCurrent, error)
DecodeAdapterCurrent decodes the current pointer of an adapter. The error is a *FileError that names the file.
type AfterCommit ¶
type AfterCommit func()
AfterCommit is returned by a write function that runs inside a transaction of another package. The caller calls it after Commit returned nil, and not otherwise: only then does the in-memory configuration take the change over.
type Backup ¶
type Backup struct {
ConfirmedAt time.Time
// Digest is the digest of the self-revocation that was confirmed.
Digest record.Digest
}
Backup is the owner's confirmation that the self-revocation was kept offline.
func DecodeBackup ¶
DecodeBackup decodes revocation-backup.json. The error is a *FileError that names the file.
type ChangeError ¶
type ChangeError struct {
Reason ChangeReason
// Field names what the refusal is about. For ChangeInvalid it is the JSON
// path of the offending value, or for a package being installed the path of
// the offending file in it. For the reasons about a name it is that name: the
// preset (ChangePresetExists, ChangePresetUnknown), the instance
// (ChangeInstanceUnknown, ChangeInstanceExists, ChangeInstanceAdapterMismatch,
// ChangeInstanceEnabled, ChangeInstanceInUse, ChangeInstanceStateBusy),
// the adapter (ChangeAdapterNotInstalled), "instances.<name>" for
// ChangeAdapterInUse and the endpoint id for ChangeEndpointUnknown and the node id for
// ChangePeerUnknown. It is
// empty for ChangeVersionConflict and ChangeNothingToChange.
Field string
// Current is the current version of the collection, for
// ChangeVersionConflict.
Current admin.Version
Err error
}
ChangeError is a refused change.
func (*ChangeError) Error ¶
func (e *ChangeError) Error() string
func (*ChangeError) Unwrap ¶
func (e *ChangeError) Unwrap() error
type ChangeReason ¶
type ChangeReason uint8
ChangeReason says why a change of the configuration was refused.
const ( // ChangeInvalid: a value is malformed or breaks a rule; Field names it. ChangeInvalid ChangeReason = iota + 1 // ChangeVersionConflict: the version the request was based on is not the // current one; Current has the current one. ChangeVersionConflict // ChangePresetExists: a preset of this name exists. ChangePresetExists // ChangePresetUnknown: no preset of this name. ChangePresetUnknown // ChangeInstanceUnknown: no adapter instance of this name. ChangeInstanceUnknown // ChangeInstanceExists: enabling an existing instance with a configuration // would silently replace or ignore it. ChangeInstanceExists // ChangeInstanceAdapterMismatch: the existing instance belongs to another // adapter. ChangeInstanceAdapterMismatch // ChangeEndpointUnknown: the endpoint is neither a stable endpoint of the // instance nor open, so a setting for it could not be kept. ChangeEndpointUnknown // ChangeAdapterNotInstalled: the adapter has no installed package. ChangeAdapterNotInstalled // ChangeAdapterInUse: an adapter that an instance is using. No change returns // it now (a package is installed over an adapter whatever its instances do); // the reason stays because its wire code is part of the stable vocabulary. ChangeAdapterInUse // ChangeNothingToChange: a patch that names no setting. ChangeNothingToChange // ChangePeerUnknown: removing a node that has no address in the book. ChangePeerUnknown // ChangeInstanceEnabled: removing an instance that is still enabled. ChangeInstanceEnabled // ChangeInstanceInUse: removing an instance that session endpoints made through // it are still open on. ChangeInstanceInUse // ChangeInstanceStateBusy: removing an instance whose state directory could not // be moved aside, because something still holds a file in it (on Windows a // process that was not ended); Field names the instance and Err the path. ChangeInstanceStateBusy )
The reasons a change is refused. Nothing is written for any of them.
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config is the configuration of the node as loaded, and the one writer of config/. Its values are read through the methods, which return copies; its writes go through the transactions of this package, and the in-memory configuration takes a change over only after the transaction that wrote it has committed.
func Load ¶
Load reads and checks all of config/ and then repairs the adapter directory.
A file that is missing where it must exist, cannot be read, is not a valid document of its kind or breaks a rule makes Load return a *FileError that names it, and nothing is written. The files are read in a fixed order, so with several wrong ones the owner is shown the first: the directories, then node.json, policy.json, presets.json, instances.json, network.json, the endpoint-id files by name, revocation-backup.json, the revocation records by name, and the adapters by id. Only when everything is valid does the repair run, which removes what an interrupted installation left among the adapters.
func (*Config) Adapters ¶
Adapters returns the installed adapters, in the order of their ids. The manifests are copies: changing one changes nothing a later call returns.
func (*Config) AddPreset ¶
func (c *Config) AddPreset(req Request, name string, preset []byte, result ResultFunc[Presets]) (Presets, error)
AddPreset adds a preset named name from its document. The document must make the statement about local sources; a name that is taken is refused. Each adapter's section is checked against the manifest of that adapter, which must be installed (see checkPresetConfig).
func (*Config) Backup ¶
Backup returns the owner's confirmation of the offline backup, if there is one. Whether it holds for the node's current self-revocation is Backup.Confirms.
func (*Config) DirectID ¶
DirectID returns the id of the direct endpoint an adapter registers under key. A key that is new gets an id minted from rnd. The same key always gives the same id, which is the promise the adapter protocol makes.
func (*Config) DisableAdapter ¶
func (c *Config) DisableAdapter(req Request, instance string, open OpenEndpoints, result ResultFunc[Instances]) (Instances, error)
DisableAdapter disables the instance named instance. The instance stays, with its settings and its stable endpoint ids, so that enabling it again finds the same endpoints.
func (*Config) DropTrash ¶ added in v0.13.0
DropTrash deletes what a removal moved aside, and syncs the directory it was in. It is meant to run outside the loop that made the removal, after the removal has been answered, because the directory can be large. A failure is the caller's to log: the directory has a garbage name, and the next start removes it. The zero Trash is nothing to delete.
func (*Config) EnableAdapter ¶
func (c *Config) EnableAdapter(req Request, instance, adapter string, instanceConfig []byte, open OpenEndpoints, result ResultFunc[Instances]) (Instances, error)
EnableAdapter enables the instance named instance of an installed adapter. A new instance is created, with instanceConfig as its configuration when that is given (a JSON object); an existing one is turned on, and keeps what the owner set. An existing instance of another adapter, and an existing instance together with a configuration, which would be silently ignored or replace the owner's, are refused. The configuration of a new instance is checked against the manifest of the adapter, so a new instance without one is refused when the adapter has a required field.
func (*Config) EndpointIDs ¶
func (c *Config) EndpointIDs(instance string) EndpointIDs
EndpointIDs returns the stable endpoint ids of an instance: none for an instance that has none.
func (*Config) EndpointSettings ¶
func (c *Config) EndpointSettings(instance string, id ident.EndpointID) EndpointSettings
EndpointSettings returns the settings that apply to an endpoint of an instance: what the owner gave it, and for what they did not, the node default.
func (*Config) LastOperations ¶
LastOperations returns the operation recorded in each versioned file that has one: the results the management layer can still answer a repeated request from.
func (*Config) PlanInstall ¶
func (c *Config) PlanInstall(s Staged, ending StillEnding) (Install, error)
PlanInstall plans the installation of a staged package.
The same version with the same contents (the digest the staging computed) is already installed and writes nothing. Any other package of the adapter, another version or the same version with other contents, replaces the installed one under a directory of its own, one that does not exist yet, the pointer's replacement being what switches to it; the processes of the adapter keep running the files they were started from, so no instance is refused, and the caller restarts the enabled ones. The directory they run from is not discarded while one may still hold it (an enabled instance, or a disabled one whose process is still ending; ending says so, and nil says none is): a running executable does not allow that on every platform, and the repair of the adapter directory removes it at the next start. No other directory of the adapter is discarded either, for the same reason.
func (*Config) PutBackup ¶
func (c *Config) PutBackup(tx *txn.Tx, p PreparedBackup) (AfterCommit, error)
PutBackup writes a prepared confirmation under RoleBackup, in a transaction of the composing package. The returned function is called after the transaction committed. It panics for a PreparedBackup that PrepareBackup did not return.
func (*Config) PutEndpointIDs ¶
PutEndpointIDs writes the ids of an instance with the id of ch in them, under RoleEndpointIDs, in a transaction of the composing package. The ids were encoded when RuntimeID or DirectID minted the id, before the transaction, so the write can only fail the way a write of the transaction does. For an id that already existed it writes nothing. The returned function makes the configuration in memory take the ids over; it is called after the transaction committed.
func (*Config) PutRevocation ¶
func (c *Config) PutRevocation(tx *txn.Tx, p PreparedRevocation) (AfterCommit, error)
PutRevocation writes a prepared revocation under the name its digest gives, under RoleRevocation, in a transaction of the composing package. The returned function is called after the transaction committed. It panics for a PreparedRevocation that PrepareRevocation did not return.
func (*Config) RemoveInstance ¶
func (c *Config) RemoveInstance(req Request, instance, stateDir string, sessions OpenSessions, open OpenEndpoints, result ResultFunc[Instances]) (Instances, Trash, error)
RemoveInstance removes the instance named instance from the configuration, with the settings it holds for endpoints. The instance has to be disabled, so that no process of it is meant to run, and no session endpoint made through it may be open: both are the owner's to undo first, and the refusal of the second says how many there are. The stable endpoint ids of the instance stay in endpoint-ids/, as they do when it is disabled: an instance later made under the same name finds the same endpoints. sessions may be nil, which says there are none.
stateDir, a path in the data directory, is the state directory of the instance: the adapter's own files, which belong to the instance and go with it. It is moved aside, to a garbage name in its own directory, in the transaction that removes the instance and before the file is replaced, which is O(1) whatever it holds, and the Trash returned names it for DropTrash to delete once the removal has been answered. A directory that is not there is nothing to move. When it cannot be moved (on Windows a file in it is still open) nothing is removed and the refusal is ChangeInstanceStateBusy, naming the path. An empty stateDir moves nothing.
func (*Config) RemovePeer ¶
func (c *Config) RemovePeer(req Request, node ident.NodeID, result ResultFunc[Network]) (Network, error)
RemovePeer removes a node and its addresses from the book. A node that is not listed is refused with ChangePeerUnknown.
func (*Config) RemovePreset ¶
func (c *Config) RemovePreset(req Request, name string, result ResultFunc[Presets]) (Presets, error)
RemovePreset removes the preset named name.
func (*Config) RevocationSet ¶
func (c *Config) RevocationSet() *revocation.Set
RevocationSet returns the revocations as the set that the packages which judge read. The set is new on each call.
func (*Config) Revocations ¶
func (c *Config) Revocations() []revocation.Revocation
Revocations returns the verified revocations the node keeps, in the order of their file names.
func (*Config) RuntimeID ¶
RuntimeID returns the runtime endpoint id of an instance. An instance that has none gets one minted from rnd; the id is then written by PutEndpointIDs in the transaction that registers the endpoint.
func (*Config) SetEndpointSettings ¶
func (c *Config) SetEndpointSettings(req Request, instance string, endpoint ident.EndpointID, patch []byte, open OpenEndpoints, result ResultFunc[Instances]) (Instances, error)
SetEndpointSettings changes the settings of one endpoint of an instance: the settings the patch names change and the others stay. The endpoint is a stable endpoint of the instance or one that is open now; a setting for any other would be dropped with the next write, so it is refused. Without knowledge of the open endpoints that is not judged.
func (*Config) SetInstanceConfig ¶
func (c *Config) SetInstanceConfig(req Request, instance string, instanceConfig []byte, open OpenEndpoints, result ResultFunc[Instances]) (Instances, error)
SetInstanceConfig replaces the configuration of the instance named instance with instanceConfig, a JSON object read as `enable` reads one, so an empty object clears it. The instance stays as it is otherwise, enabled or not, with its endpoint settings and its stable endpoint ids. The values are checked against the manifest of the instance's adapter, whose package must load. The adapter reads the values when it starts, so a running instance takes them only when the caller restarts it.
func (*Config) SetListen ¶
func (c *Config) SetListen(req Request, listen []string, result ResultFunc[Network]) (Network, error)
SetListen replaces the listen list. An empty list is valid: the node then does not listen.
func (*Config) SetNodeSettings ¶
SetNodeSettings changes the settings of the node named by patch, a JSON object of settings, atomically: with one value refused nothing changes. The patch is merged into the current settings and the result is validated whole, so a setting is judged against the others it depends on. The change is recorded in node.json with the operation and the result, in the same replacement.
func (*Config) SetPeerAddresses ¶
func (c *Config) SetPeerAddresses(req Request, node ident.NodeID, addrs []string, result ResultFunc[Network]) (Network, error)
SetPeerAddresses replaces the addresses of a node, adding the node when it is not listed. At least one address is given: removing a node is RemovePeer.
func (*Config) StageAdapter ¶
StageAdapter copies the package that src is rooted at into a staging directory next to the versions of its adapter, and checks that the manifest of the copy is, byte for byte, the one that was read and judged first. Nothing is installed: everything it writes is preparation that the repair of the adapter directory removes after a crash, and that Unstage removes when the installation is refused. A package that changes between the check and the copy is refused, so what the install runs is what was checked.
After preflight, the package is copied one entry at a time. Link targets are judged during the copy, and a failed copy cleans up what was written to the staging directory. A package over MaxPackageBytes is refused. rnd names the staging directory. The platform the manifest lists is the caller's to check on Staged.Manifest.
func (*Config) Unstage ¶
Unstage drops the staging directory of an installation that did not complete, and, when the adapter was never installed and nothing else is staged beside it, the directory of the adapter that the staging made. It touches nothing else: a version directory that was renamed in and did not become current, like one a crash left, is the repair's, because Unstage runs outside the writer loop and cannot tell such a directory from one that an installation committed meanwhile. What is not there is not an error, and with nothing to drop it writes nothing.
type EndpointIDs ¶
type EndpointIDs struct {
Runtime ident.EndpointID
Direct map[string]ident.EndpointID
}
EndpointIDs are the endpoint ids of one instance that must outlive the run-time state: the runtime endpoint and the direct endpoints by key.
func DecodeEndpointIDs ¶
func DecodeEndpointIDs(instance string, data []byte) (EndpointIDs, error)
DecodeEndpointIDs decodes the endpoint-id file of an instance. The error is a *FileError that names the file.
func (EndpointIDs) Encode ¶
func (e EndpointIDs) Encode() ([]byte, error)
Encode returns the bytes of an endpoint-id file.
type EndpointOverride ¶
EndpointOverride is the settings an owner gave one endpoint. A zero field is not set: the node default applies.
func (EndpointOverride) Validate ¶
func (o EndpointOverride) Validate() error
Validate checks the settings an owner gave one endpoint. A field that is not set is not checked: the node default applies.
func (EndpointOverride) WireJSON ¶
func (o EndpointOverride) WireJSON() ([]byte, error)
WireJSON is what the owner gave one endpoint, as the owner's commands show it: the compact JSON object that names only the settings that are set, as `endpoint set` takes them, so that a setting left to the node default is not shown as if the owner had chosen its value.
type EndpointPatch ¶
EndpointPatch names the endpoint settings a request changes; a nil field is not named.
func DecodeEndpointPatch ¶
func DecodeEndpointPatch(data []byte) (EndpointPatch, error)
DecodeEndpointPatch decodes the settings object of an endpoints.set request.
type EndpointSettings ¶
type EndpointSettings struct {
// MaxQueue is the longest the endpoint keeps a message queued.
MaxQueue time.Duration
// BacklogLimit is how many messages the endpoint holds queued.
BacklogLimit int
}
EndpointSettings are the settings of one endpoint that an owner can change.
func (EndpointSettings) Validate ¶
func (s EndpointSettings) Validate() error
Validate checks the settings of an endpoint with the rules of the package that owns them: delivery decides what a queue time and a backlog limit may be.
type FieldError ¶
type FieldError struct {
// Field is the JSON path of the value.
Field string
// Malformed is true when the input is not a document of the expected shape
// (see FileMalformed); false when a well formed value breaks a rule.
Malformed bool
Err error
}
FieldError is a value of a document, or a setting, that is refused.
func (*FieldError) Error ¶
func (e *FieldError) Error() string
func (*FieldError) Unwrap ¶
func (e *FieldError) Unwrap() error
type FileError ¶
type FileError struct {
// Path is relative to the data directory root.
Path string
Kind FileKind
Reason FileReason
// Field is the JSON path of the offending value inside the file; empty when
// the file as a whole is meant.
Field string
Err error
}
FileError is what a refused file gives: the node does not start, and the message names the file, so the owner knows what to fix.
type FileKind ¶
type FileKind uint8
FileKind says which kind of file or directory of config/ an error is about.
type FileReason ¶
type FileReason uint8
FileReason says why a file was refused.
const ( // FileMissing: a file or directory that must exist does not. FileMissing FileReason = iota + 1 // FileUnreadable: the file exists and could not be read. FileUnreadable // FileMalformed: the content is not a document of the file's shape: not // JSON, an unknown, repeated, missing or null field, or a value of the // wrong type. FileMalformed // FileInvalid: the document is well formed and a value breaks a rule. FileInvalid // FileMisnamed: the name of the file does not match what it holds. FileMisnamed )
The ways loading a file fails.
type GCItem ¶
GCItem is one directory adapter-gc removes.
func AdapterGCWork ¶
AdapterGCWork lists what the repair of the adapter directory removes: an adapter directory without a current pointer, and in an installed adapter a staging directory or a version directory the pointer does not name. It only reads, and it is the one definition of that garbage: the repair removes exactly this list (an adapter whose pointer cannot be read is left alone, for what to keep is not known), and a test evaluates it on a copy of the disk, where a run without a crash must leave it empty at every quiet point. The order is by adapter id and, within an adapter, by name.
type GCReason ¶
type GCReason uint8
GCReason says why an adapter directory entry is garbage.
const ( // GCNotInstalled: an adapter directory without a current pointer: an // installation that did not finish. GCNotInstalled GCReason = iota + 1 // GCStaging: a staging directory. GCStaging // GCSuperseded: a version directory that the current pointer does not name. GCSuperseded )
What adapter-gc removes.
type IDChange ¶
type IDChange struct {
Instance string
ID ident.EndpointID
// New is true when the id was minted and has to be written.
New bool
// contains filtered or unexported fields
}
IDChange is an endpoint id that was looked up or minted for an instance, and the whole set of ids that holds it.
type InitOptions ¶
type InitOptions struct {
// Port is the port network.json makes the node listen on; zero is
// DefaultListenPort.
Port int
}
InitOptions are the choices of the owner that `init` writes into the files it makes.
type InitPlan ¶
type InitPlan struct {
// contains filtered or unexported fields
}
InitPlan is what `init` has to do on the side of config/. `init` never overwrites: for each of the five files it writes, a file that is missing is written with the defaults, one that exists and is valid stays as the owner left it, and one that exists and is not valid makes the plan fail, naming the file, so that the owner decides what becomes of it.
func PlanInit ¶
func PlanInit(r fsx.Reader, opts InitOptions) (*InitPlan, error)
PlanInit checks what is on disk and decides what is missing. It only reads, so when it fails nothing has been written. A port that cannot be listened on is refused even when network.json exists and will be kept: the owner asked for something that cannot be done.
type Install ¶
type Install struct {
// AlreadyCurrent is true when the staged package is the one that is current,
// the same version with the same contents: there is nothing to write, and the
// installation is already done.
AlreadyCurrent bool
// Replaced is true when the package replaces one that was installed: another
// version, or the same version with other contents. A running process of the
// adapter runs the package that was replaced until it is started again.
Replaced bool
// contains filtered or unexported fields
}
Install is the plan of the writes that make a staged package the current version of its adapter. The composing package runs them in its own transaction, in this order, with its own write between Point and DiscardOld: Promote, Point, DiscardOld. The commit point is the replacement of the current pointer. PlanInstall, before the transaction begins, does every check and encoding the writes need, so none of them can fail for a reason of its own.
func (Install) DiscardOld ¶
DiscardOld discards the package that was replaced, under RoleOld. It writes nothing for a first installation, and nothing when a process may still hold the package's files (see PlanInstall), which the repair removes at the next start.
func (Install) Point ¶
func (i Install) Point(tx *txn.Tx) (AfterCommit, error)
Point replaces the current pointer, under RoleCurrent. This is the commit point of the installation. The returned function makes the configuration in memory take the version over; it is called after the transaction committed.
type Instance ¶
type Instance struct {
Adapter string
Enabled bool
// Config holds the values of the manifest's instance fields.
Config map[string]json.RawMessage
// Endpoints are the settings owners gave single endpoints.
Endpoints map[ident.EndpointID]EndpointOverride
}
Instance is one adapter instance.
type Instances ¶
Instances is the content of instances.json.
func DecodeInstances ¶
DecodeInstances decodes instances.json. The error is a *FileError that names the file.
type Network ¶
type Network struct {
Version admin.Version
// Listen holds multiaddrs without a peer identifier. An empty list means the
// node does not listen: it can still dial.
Listen []string
// Peers holds, per node, the multiaddrs it can be reached on, each with an
// optional trailing /p2p/<peer id>. A node with no address is not listed.
Peers map[ident.NodeID][]string
LastOperation *Operation
}
Network is the content of network.json: where the node listens, and the addresses the owner entered for other nodes. A node that is learned about later is not here: only what the owner decided is configuration.
func DecodeNetwork ¶
DecodeNetwork decodes network.json. The error is a *FileError that names the file.
type Node ¶
type Node struct {
Version admin.Version
Settings NodeSettings
LastOperation *Operation
}
Node is the content of node.json.
func DecodeNode ¶
DecodeNode decodes node.json. The error is a *FileError that names the file.
type NodePatch ¶
type NodePatch struct {
// Name is the new name; a pointer to the empty string takes the name away.
Name *string
ReplyPermission *bool
NodeQueueLimit *int
DiskReserveBytes *int64
NodePromptTurns *int
ArchiveRetentionDays *int
LogTotalBytes *int64
EndpointDefaults *EndpointPatch
}
NodePatch names the node settings a request changes; a nil field is not named.
func DecodeNodePatch ¶
DecodeNodePatch decodes the settings object of a node.set request.
type NodeSettings ¶
type NodeSettings struct {
// Name is what the owner calls the node, shown to people and agents beside
// the node's identifier; empty means the node has no name of its own and is
// called by its host name. It is a label: nothing is addressed, trusted or
// allowed by it.
Name string
// ReplyPermission is whether a reply with evidence may reach an endpoint
// that did not ask for it.
ReplyPermission bool
// NodeQueueLimit is how many unfinished deliveries the node holds.
NodeQueueLimit int
// DiskReserveBytes is the free space below which new work is refused.
DiskReserveBytes int64
// NodePromptTurns is how many turns started by prompts may run at once.
NodePromptTurns int
// ArchiveRetentionDays is how long the archive keeps what it summarises.
ArchiveRetentionDays int
// LogTotalBytes is the space all logs together may take.
LogTotalBytes int64
// EndpointDefaults apply to an endpoint without settings of its own.
EndpointDefaults EndpointSettings
}
NodeSettings are the settings of the node.
func DefaultNodeSettings ¶
func DefaultNodeSettings() NodeSettings
DefaultNodeSettings are the settings `init` writes. The limits another package decided come from that package.
func (NodeSettings) ArchiveRetention ¶
func (s NodeSettings) ArchiveRetention() time.Duration
ArchiveRetention is how long the archive keeps its summaries, the one conversion of archive_retention_days to a duration. Validate refuses a number of days that the conversion would wrap around.
func (NodeSettings) Validate ¶
func (s NodeSettings) Validate() error
Validate checks every setting: the ones that another package owns by asking it, the others by the ranges the README gives, and the disk reserve against what the queue and the logs can fill.
func (NodeSettings) WireJSON ¶
func (s NodeSettings) WireJSON() ([]byte, error)
WireJSON is the settings as the owner's commands show them: the compact JSON object that node.json holds under "settings", whose names `node set` takes patches by. It is the one place the names of the settings are written for anything but the file, so that what a command shows is what the file says.
type OpenEndpoints ¶
type OpenEndpoints func(ident.EndpointID) bool
OpenEndpoints says whether an endpoint is open now. The session endpoints that are closed are the ones whose settings a write of instances.json drops. A nil value drops nothing.
type OpenSessions ¶
OpenSessions says how many session endpoints made through the instance are still open. Config does not hold endpoints, so the caller that does tells it.
type Operation ¶
type Operation struct {
ID admin.OperationID
// Person is who sent the request; the zero value is the local owner.
Person ident.PersonID
Fingerprint admin.Fingerprint
// Result is one compact JSON object.
Result json.RawMessage
}
Operation is the management operation that produced the current version of a file, with its result. It is stored in the file it changed, in the same replacement as the change, so the effect and its result cannot be told apart by a crash. A file the owner edited by hand has none.
func (Operation) Key ¶
func (o Operation) Key() admin.RequestKey
Key is the key under which the management layer files the operation's result.
type PolicyFile ¶
PolicyFile is the content of policy.json.
func DecodePolicy ¶
func DecodePolicy(data []byte) (PolicyFile, error)
DecodePolicy decodes policy.json: the rules, each as authz reads it. The error is a *FileError that names the file.
func (PolicyFile) Encode ¶
func (p PolicyFile) Encode() ([]byte, error)
Encode returns the bytes of policy.json.
type PreparedBackup ¶
type PreparedBackup struct {
// contains filtered or unexported fields
}
PreparedBackup is the owner's confirmation of the offline backup, checked and encoded for a transaction of the composing package. PrepareBackup runs before that transaction begins, so a confirmation that cannot be written is an error that touches nothing, and PutBackup can only fail the way a write of the transaction does.
func PrepareBackup ¶
func PrepareBackup(b Backup) (PreparedBackup, error)
PrepareBackup checks and encodes a confirmation. It does no I/O.
type PreparedRevocation ¶
type PreparedRevocation struct {
// contains filtered or unexported fields
}
PreparedRevocation is a verified revocation record, with its file, for a transaction of the composing package. PrepareRevocation runs before that transaction begins, so a record that does not verify is an error that touches nothing, and PutRevocation can only fail the way a write of the transaction does.
func PrepareRevocation ¶
func PrepareRevocation(rec record.Record) (PreparedRevocation, error)
PrepareRevocation verifies a revocation record and encodes its file, the record's own wire bytes. It does no I/O.
type Preset ¶
type Preset struct {
// LocalSources is the preset's statement about local sources. It has no
// default: a preset without one is not valid.
LocalSources authz.PresetLocalAccess
Description string
// Config holds, per adapter id, the values of the manifest's preset fields.
// Only the shape is checked here; the manifest decides what is valid.
Config map[string]map[string]json.RawMessage
}
Preset is one preset: what local sources may do with it, and the values it gives the adapters.
func DecodePreset ¶
DecodePreset decodes one preset document, as presets.add carries it. The statement about local sources is required and has no default: a document without it, or with a value that is not exactly "allow" or "deny", is refused, and the result never holds the zero statement. The error is a *FieldError.
func (Preset) WireJSON ¶
WireJSON is the preset as the owner's commands show it and as presets.add takes it: the compact JSON object that presets.json holds under the preset's name. It is the one place the names of a preset's members are written for anything but the file, so that what a command shows is what the file says.
type Presets ¶
Presets is the content of presets.json.
func DecodePresets ¶
DecodePresets decodes presets.json. The error is a *FileError that names the file.
type Request ¶
type Request struct {
// Key is the key the request's results are filed under, as admin.KeyFor
// makes it from the actor and the operation id. The change records its
// person and id in last_operation, so the replay lookup finds them under the
// same key.
Key admin.RequestKey
Fingerprint admin.Fingerprint
// Expected is the version of the collection the sender last saw.
Expected admin.Version
}
Request is what a versioned change takes from the management layer: which request it is, and the version it was based on.
type ResultFunc ¶
type ResultFunc[T any] func(after T) (json.RawMessage, error)
ResultFunc builds the result that is stored with a change, from the state the change produced. The management layer owns the shape of a result; the version is known only once the change is made, so it is built here.
type SourceError ¶
SourceError is a package that cannot be read: Path is the directory or file inside the package whose reading failed, relative to the package, "." for the package itself. The package is not what it should be, and the owner who named it can fix it; that is no failure of this node's own storage.
func (*SourceError) Error ¶
func (e *SourceError) Error() string
func (*SourceError) Unwrap ¶
func (e *SourceError) Unwrap() error
type Staged ¶
type Staged struct {
ID string
Version string
// Digest is the digest of the contents of the copy in lower case hex: every
// directory and file by relative path, and every file's bytes.
Digest string
Dir string
Manifest manifest.Manifest
}
Staged is a package copied into a staging directory next to the versions, parsed there, and not installed yet.
type StillEnding ¶
StillEnding says whether a process of the instance is still being ended. Config does not run adapters, so the caller that does tells it.