Documentation
¶
Overview ¶
Package file implements file deploy and status operations using NATS Object Store for content and KV for state tracking.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildStateKey ¶
BuildStateKey returns the KV key for a file's deploy state. Format: <hostname>.<sha256-of-path>.
Types ¶
type DeployRequest ¶
type DeployRequest struct {
// ObjectName is the name of the object in the NATS object store.
ObjectName string `json:"object_name"`
// Path is the destination path on the target filesystem.
Path string `json:"path"`
// Mode is the file permission mode (e.g., "0644").
Mode string `json:"mode,omitempty"`
// Owner is the file owner user.
Owner string `json:"owner,omitempty"`
// Group is the file owner group.
Group string `json:"group,omitempty"`
// ContentType specifies whether the content is "raw" or "template".
ContentType string `json:"content_type"`
// Vars contains template variables when ContentType is "template".
Vars map[string]any `json:"vars,omitempty"`
// Metadata contains provider-specific key-value pairs stored alongside
// the file state. Meta providers use this to persist domain-specific
// fields (e.g., cron schedule, systemd unit type).
Metadata map[string]string `json:"metadata,omitempty"`
}
DeployRequest contains parameters for deploying a file to disk.
type DeployResult ¶
type DeployResult struct {
// Changed indicates whether the file was written (false if SHA matched).
Changed bool `json:"changed"`
// SHA256 is the SHA-256 hash of the deployed file content.
SHA256 string `json:"sha256"`
// Path is the destination path where the file was deployed.
Path string `json:"path"`
}
DeployResult contains the result of a file deploy operation.
type Deployer ¶
type Deployer interface {
// Deploy writes file content from the object store to the target
// path with SHA tracking and idempotency.
Deploy(
ctx context.Context,
req DeployRequest,
) (*DeployResult, error)
// Undeploy removes a deployed file from disk. The object store
// entry and file-state KV record are preserved.
Undeploy(
ctx context.Context,
req UndeployRequest,
) (*UndeployResult, error)
}
Deployer is the narrow interface for providers that deploy files to well-known paths. Meta providers (cron, systemd, sysctl) depend on this instead of the full Provider interface.
type Provider ¶
type Provider interface {
// Deploy writes file content to the target path with the specified
// permissions. Returns whether the file was changed and its SHA-256.
Deploy(
ctx context.Context,
req DeployRequest,
) (*DeployResult, error)
// Undeploy removes a deployed file from disk. The object store
// entry and file-state KV record are preserved.
Undeploy(
ctx context.Context,
req UndeployRequest,
) (*UndeployResult, error)
// Status checks the current state of a deployed file against its
// expected SHA-256 from the file-state KV.
Status(
ctx context.Context,
req StatusRequest,
) (*StatusResult, error)
}
Provider defines the interface for file operations.
type Service ¶
type Service struct {
provider.FactsAware
// contains filtered or unexported fields
}
Service implements the Provider interface for file deploy and status operations using NATS Object Store for content and KV for state tracking.
func New ¶
func New( logger *slog.Logger, fs avfs.VFS, objStore jetstream.ObjectStore, stateKV jetstream.KeyValue, hostname string, ) *Service
New creates a new Service with the given dependencies. Facts are not available at construction time; call SetFactsFunc after the agent is initialized to wire template rendering to live facts.
func (*Service) Deploy ¶
func (p *Service) Deploy( ctx context.Context, req DeployRequest, ) (*DeployResult, error)
Deploy writes file content to the target path with the specified permissions. It uses SHA-256 checksums for idempotency: if the content hasn't changed since the last deploy, the file is not rewritten and changed is false.
func (*Service) Status ¶
func (p *Service) Status( ctx context.Context, req StatusRequest, ) (*StatusResult, error)
Status checks the current state of a deployed file against its expected SHA-256 from the file-state KV. Returns "in-sync" if the file matches, "drifted" if it differs, or "missing" if the file or state entry is absent.
func (*Service) Undeploy ¶
func (p *Service) Undeploy( ctx context.Context, req UndeployRequest, ) (*UndeployResult, error)
Undeploy removes a deployed file from disk. The object store entry is preserved. The file-state KV is updated to record the undeploy timestamp.
type StatusRequest ¶
type StatusRequest struct {
// Path is the filesystem path to check.
Path string `json:"path"`
}
StatusRequest contains parameters for checking file status.
type StatusResult ¶
type StatusResult struct {
// Path is the filesystem path that was checked.
Path string `json:"path"`
// Status indicates the file state: "in-sync", "drifted", or "missing".
Status string `json:"status"`
// SHA256 is the current SHA-256 hash of the file on disk, if present.
SHA256 string `json:"sha256,omitempty"`
// Changed indicates whether system state was modified.
Changed bool `json:"changed"`
}
StatusResult contains the result of a file status check.
type TemplateContext ¶
type TemplateContext struct {
// Facts contains agent facts (architecture, kernel, etc.).
Facts map[string]any
// Vars contains user-supplied template variables.
Vars map[string]any
// Hostname is the agent's hostname.
Hostname string
}
TemplateContext is the data available to Go templates during rendering.
type UndeployRequest ¶
type UndeployRequest struct {
// Path is the filesystem path to undeploy.
Path string `json:"path"`
}
UndeployRequest contains parameters for removing a deployed file from disk.
type UndeployResult ¶
type UndeployResult struct {
// Changed indicates whether the file was removed.
Changed bool `json:"changed"`
// Path is the filesystem path that was undeployed.
Path string `json:"path"`
}
UndeployResult contains the result of a file undeploy operation.
Source Files
Directories