Documentation
¶
Overview ¶
Package filesync is the client-side library for Hikyo's generic file destination (#164): an authenticated client on the destination host pulls one revision of a server-side file target and atomically renders it to a locally configured directory. The server never learns the path; nothing in this package talks to the network. The CLI verbs (`hikyo file-sync render|doctor`) are thin wiring over it, the same split internal/compose keeps for the Compose path.
hikyo-file-sync.yaml, the client-local binding ¶
A NON-SECRET file the operator keeps on the destination host and passes with --config. It binds one server file target to one local directory:
version: 1
instance: https://hikyo.example.internal
org: org_...
project: prj_...
environment: env_...
target: ftg_... # the server file target
refresh:
mode: oneshot # or poll: fetch until current, then exit
interval: 30s # poll only
timeout: 10m # poll only
snapshot:
offline_serve: false
max_age: 168h # downward-only override of 7 d
destination:
directory: /run/app/secrets # absolute, must exist, never created
mode: "0600" # file mode; group read is the widest allowed
owner: "" # uid or user name; refused if chown fails
group: "" # gid or group name
require_tmpfs: false # refuse unless the directory is tmpfs (Linux)
on_removed: refuse # refuse | retain | prune a dropped file
files:
- name: app.env
format: dotenv # dotenv | json | yaml | raw
keys: [DATABASE_URL, API_TOKEN]
acknowledge_loader_control: []
Parsing is STRICT (unknown fields are errors) and a credential key anywhere is refused: the token reaches the CLI through --token-file or HIKYO_TOKEN only, exactly as for hikyo-compose.yaml.
Index ¶
- Constants
- Variables
- func GenerationStamp(keys *crypto.LocalKeys, target string, policy Policy, files []Rendered) string
- func OnTmpfs(dir string) (bool, error)
- func RenderAll(cfg *Config, rows []Row) ([]Rendered, []Refusal)
- type Config
- type Destination
- func (d *Destination) Close() error
- func (d *Destination) Current() (State, error)
- func (d *Destination) Dir() string
- func (d *Destination) Intact(keys *crypto.LocalKeys, target string, policy Policy, names []string) (State, bool, error)
- func (d *Destination) Publish(ctx context.Context, plan Plan, probe Probe) (Result, error)
- func (d *Destination) Verify(plan Plan) (bool, error)
- type DestinationSettings
- type File
- type Format
- type OnRemoved
- type Plan
- type Policy
- type Probe
- type RefreshMode
- type RefreshSettings
- type Refusal
- type Rendered
- type Result
- type Row
- type SnapshotSettings
- type State
Constants ¶
const ( // DefaultSnapshotMaxAge is the ops-spec hard maximum a config may only // lower (the Compose path's value). DefaultSnapshotMaxAge = 7 * 24 * time.Hour // DefaultPollInterval and DefaultPollTimeout bound the poll mode. DefaultPollInterval = 30 * time.Second DefaultPollTimeout = 10 * time.Minute // MinPollInterval keeps a poll loop from becoming a fetch storm; the // per-principal fetch rate would refuse it anyway. MinPollInterval = 5 * time.Second // MaxFiles bounds one binding. MaxFiles = 64 // DefaultMode is the file mode when the config names none. DefaultMode = 0o600 )
const ConfigName = "hikyo-file-sync.yaml"
ConfigName is the conventional file name; the CLI requires --config anyway.
Variables ¶
var ( // ErrForeign refuses to replace something the client did not create. ErrForeign = errors.New("filesync: destination holds a file this client did not publish") // ErrRemoved refuses a publication that drops a previously published file // while on_removed is refuse. ErrRemoved = errors.New("filesync: a previously published file is no longer configured") // ErrBinding refuses a directory that belongs to a different file target. ErrBinding = errors.New("filesync: destination directory belongs to a different file target") // ErrBusy refuses a second concurrent client on the same directory. ErrBusy = errors.New("filesync: another hikyo file-sync process holds this destination") // ErrNotTmpfs refuses a require_tmpfs destination that is not in memory. ErrNotTmpfs = errors.New("filesync: destination directory is not on tmpfs") // ErrUnsupported is a platform that cannot honour the requested policy. ErrUnsupported = errors.New("filesync: not supported on this platform") )
Functions ¶
func GenerationStamp ¶
GenerationStamp is the keyed stamp over one complete publication: the target, the policy and every (name, content) pair. Keyed, never a bare digest, because it is a function of secret plaintext (compose ADR).
Types ¶
type Config ¶
type Config struct {
Version int `yaml:"version"`
Instance string `yaml:"instance"`
Org string `yaml:"org"`
Project string `yaml:"project"`
Environment string `yaml:"environment"`
Target string `yaml:"target"`
Refresh RefreshSettings `yaml:"refresh"`
Snapshot SnapshotSettings `yaml:"snapshot"`
Destination DestinationSettings `yaml:"destination"`
Files []File `yaml:"files"`
// contains filtered or unexported fields
}
Config is a parsed, validated hikyo-file-sync.yaml.
func ParseConfig ¶
ParseConfig strictly parses and validates a hikyo-file-sync.yaml document.
func (*Config) PollInterval ¶
PollInterval and PollTimeout are the effective poll bounds.
func (*Config) PollTimeout ¶
func (*Config) SnapshotMaxAge ¶
SnapshotMaxAge is the effective offline snapshot max age.
type Destination ¶
type Destination struct {
// contains filtered or unexported fields
}
Destination is an opened, locked destination directory.
func OpenDestination ¶
func OpenDestination(dir string, requireTmpfs bool) (*Destination, error)
OpenDestination opens dir root-bound and takes the non-blocking directory lock. dir must be an existing directory and not itself a symlink; it is never created, so a typo cannot materialize plaintext somewhere new.
func (*Destination) Close ¶
func (d *Destination) Close() error
Close releases the lock and the root.
func (*Destination) Current ¶
func (d *Destination) Current() (State, error)
Current reads the committed state. A directory never published to returns a zero State and no error.
func (*Destination) Intact ¶
func (d *Destination) Intact(keys *crypto.LocalKeys, target string, policy Policy, names []string) (State, bool, error)
Intact re-derives the current generation's keyed stamp from the bytes on disk and the policy, and reports whether it equals the stamp the generation was committed under, the generation holds exactly names, every name links to it, and every file carries the policy's mode and ownership. A wiped tmpfs, a hand-edited file or a changed policy all read as not intact, which is what stops a stored cursor from claiming "current" over them.
func (*Destination) Publish ¶
Publish commits plan as one generation. On any error before the commit the previously current generation is untouched; after the commit the new one is current even if link creation, pruning or collection then fails.
func (*Destination) Verify ¶
func (d *Destination) Verify(plan Plan) (bool, error)
Verify reports whether every configured name resolves, through this client's own link, to the current generation's file with the given content, mode and ownership. It is the "destination intact" test that decides whether a stored cursor may be presented.
type DestinationSettings ¶
type DestinationSettings struct {
Directory string `yaml:"directory"`
Mode string `yaml:"mode"`
Owner string `yaml:"owner"`
Group string `yaml:"group"`
RequireTmpfs bool `yaml:"require_tmpfs"`
OnRemoved OnRemoved `yaml:"on_removed"`
}
DestinationSettings is the one local directory every file of the binding lands in.
type File ¶
type File struct {
Name string `yaml:"name"`
Format Format `yaml:"format"`
Keys []string `yaml:"keys"`
AcknowledgeLoaderControl []string `yaml:"acknowledge_loader_control"`
}
File is one rendered file.
type OnRemoved ¶
type OnRemoved string
OnRemoved is the explicit decision for a file a previous generation published that the configuration no longer names.
const ( // RemovedRefuse fails the render, naming the file, until the operator // decides. It is the default because both other answers are irreversible // in their own way. RemovedRefuse OnRemoved = "refuse" // RemovedRetain leaves the last content in place as an unmanaged regular // file and forgets it. RemovedRetain OnRemoved = "retain" // RemovedPrune deletes the file, and only a file this client published. RemovedPrune OnRemoved = "prune" )
type Policy ¶
type Policy struct {
Mode os.FileMode
UID, GID int // -1 leaves the process's own
OnRemoved OnRemoved
}
Policy is the ownership, mode and removal policy applied to one publication.
func ResolvePolicy ¶
ResolvePolicy turns the destination settings into a publication policy, resolving owner and group names to ids. An unknown name is refused: a policy that cannot be applied exactly is never approximated.
type Probe ¶
Probe is the fault seam. Production passes nil; tests inject errors at each durability boundary (a write that fails like a full disk, a crash before or after the commit) and assert the reader-visible invariant.
type RefreshMode ¶
type RefreshMode string
RefreshMode is how one invocation converges. There is deliberately no resident watch mode (mvp-boundary: "Local agent daemon / resident watcher: Out"): continuous refresh is a systemd timer, cron or CronJob running the one-shot or poll mode.
const ( RefreshOneshot RefreshMode = "oneshot" RefreshPoll RefreshMode = "poll" )
type RefreshSettings ¶
type RefreshSettings struct {
Mode RefreshMode `yaml:"mode"`
Interval string `yaml:"interval"`
Timeout string `yaml:"timeout"`
}
RefreshSettings selects the convergence mode.
type Refusal ¶
Refusal names one key a file cannot represent and why. A non-empty refusal list means nothing is written: refusals are reported before any temporary file exists.
type Result ¶
type Result struct {
Changed bool
Generation string
Stamp string
Pruned []string
Retained []string
}
Result reports what one publication did.
type Row ¶
Row is one delivered key as the renderer sees it. Value is nil when no plaintext crossed: a secret delivered presence-only, or a key the snapshot does not set.
type SnapshotSettings ¶
type SnapshotSettings struct {
OfflineServe bool `yaml:"offline_serve"`
MaxAge string `yaml:"max_age"`
}
SnapshotSettings is the offline snapshot policy.