filesync

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MPL-2.0 Imports: 29 Imported by: 0

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

View Source
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
)
View Source
const ConfigName = "hikyo-file-sync.yaml"

ConfigName is the conventional file name; the CLI requires --config anyway.

Variables

View Source
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

func GenerationStamp(keys *crypto.LocalKeys, target string, policy Policy, files []Rendered) string

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).

func OnTmpfs

func OnTmpfs(dir string) (bool, error)

OnTmpfs reports whether dir is on tmpfs; off Linux it cannot tell and returns ErrUnsupported.

func RenderAll

func RenderAll(cfg *Config, rows []Row) ([]Rendered, []Refusal)

RenderAll renders every configured file from one delivery. It either returns every file or refusals naming each unrepresentable key; it never returns a partial set.

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

func ParseConfig(data []byte) (*Config, error)

ParseConfig strictly parses and validates a hikyo-file-sync.yaml document.

func (*Config) FileMode

func (c *Config) FileMode() uint32

FileMode is the effective file mode.

func (*Config) KeyNames

func (c *Config) KeyNames() []string

KeyNames is the sorted, deduplicated union of every file's keys.

func (*Config) PollInterval

func (c *Config) PollInterval() time.Duration

PollInterval and PollTimeout are the effective poll bounds.

func (*Config) PollTimeout

func (c *Config) PollTimeout() time.Duration

func (*Config) SnapshotMaxAge

func (c *Config) SnapshotMaxAge() time.Duration

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) Dir

func (d *Destination) Dir() string

Dir is the destination path.

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

func (d *Destination) Publish(ctx context.Context, plan Plan, probe Probe) (Result, error)

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 Format

type Format string

Format is one supported rendering.

const (
	FormatDotenv Format = "dotenv"
	FormatJSON   Format = "json"
	FormatYAML   Format = "yaml"
	FormatRaw    Format = "raw"
)

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 Plan

type Plan struct {
	Target string
	Stamp  string
	Files  []Rendered
	Policy Policy
}

Plan is one publication.

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

func ResolvePolicy(cfg *Config) (Policy, error)

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

type Probe interface {
	BeforeWrite(name string) error
	BeforeCommit() error
	AfterCommit() error
}

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

type Refusal struct {
	File   string
	Key    string
	Reason string
}

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.

func Render

func Render(format Format, keys []string, values map[string]string) ([]byte, []Refusal)

Render encodes one file. keys fixes the dotenv line order; json and yaml sort by key. Every refusal is returned (File left empty for the caller).

func (Refusal) String

func (r Refusal) String() string

type Rendered

type Rendered struct {
	Name    string
	Content []byte
}

Rendered is one file's final bytes.

type Result

type Result struct {
	Changed    bool
	Generation string
	Stamp      string
	Pruned     []string
	Retained   []string
}

Result reports what one publication did.

type Row

type Row struct {
	KeyID          string
	Name           string
	Classification string
	Value          *string
}

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.

type State

type State struct {
	Target     string
	Generation string
	Stamp      string
	Files      []string
}

State is the published state read back from the directory.

Jump to

Keyboard shortcuts

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