api

package
v0.1.2 Latest Latest
Warning

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

Go to latest
Published: Apr 6, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ClearPendingReports

func ClearPendingReports()

ClearPendingReports removes the pending reports file.

func SavePendingReport

func SavePendingReport(report JobReportRequest)

SavePendingReport persists a failed job report for later retry.

Types

type ApiResponse

type ApiResponse[T any] struct {
	Data T    `json:"data"`
	Meta Meta `json:"meta"`
}

ApiResponse is the standard NerdBackup API envelope.

type Client

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

func NewClient

func NewClient(baseURL, agentID, agentToken string) *Client

func (*Client) FlushPendingReports

func (c *Client) FlushPendingReports(ctx context.Context)

FlushPendingReports retries any saved pending reports.

func (*Client) GetLatestVersion

func (c *Client) GetLatestVersion(ctx context.Context) (*VersionInfo, error)

GetLatestVersion checks for agent updates.

func (*Client) GetRepos

func (c *Client) GetRepos(ctx context.Context) ([]RepoConfig, bool, error)

GetRepos fetches repo configs with ETag support. Returns (repos, changed, error). If changed=false, repos is nil (304).

func (*Client) PostDockerVolumes

func (c *Client) PostDockerVolumes(ctx context.Context, data interface{}) error

PostDockerVolumes uploads discovered Docker volumes to the API.

func (*Client) ReportJob

func (c *Client) ReportJob(ctx context.Context, req JobReportRequest) error

ReportJob reports a completed/failed job. Retries 5x, then saves to pending.

func (*Client) ReportProgress

func (c *Client) ReportProgress(ctx context.Context, progress ProgressReport)

ReportProgress sends real-time backup progress. Best-effort, 1 retry.

func (*Client) SendHeartbeat

func (c *Client) SendHeartbeat(ctx context.Context, req HeartbeatRequest) (*HeartbeatResponse, error)

SendHeartbeat sends a heartbeat. Returns config_changed flag.

func (*Client) ShipLogs

func (c *Client) ShipLogs(ctx context.Context, lines []string) error

ShipLogs sends a batch of log lines.

type HeartbeatRequest

type HeartbeatRequest struct {
	AgentVersion  string `json:"agent_version"`
	ResticVersion string `json:"restic_version"`
	Platform      string `json:"platform"`
	Arch          string `json:"arch"`
	Hostname      string `json:"hostname"`
	UptimeSeconds int64  `json:"uptime_seconds"`
	LastBackupAt  string `json:"last_backup_at,omitempty"`
	DiskFreeBytes int64  `json:"disk_free_bytes"`
	CPUCount      int    `json:"cpu_count"`
	MemTotalBytes int64  `json:"memory_total_bytes"`
}

Heartbeat

type HeartbeatResponse

type HeartbeatResponse struct {
	ConfigChanged bool   `json:"config_changed"`
	ConfigHash    string `json:"config_hash"`
}

type JobReportRequest

type JobReportRequest struct {
	RepoID           string    `json:"repo_id"`
	PolicyID         string    `json:"policy_id,omitempty"`
	Operation        string    `json:"operation"`
	Status           string    `json:"status"`
	StartedAt        time.Time `json:"started_at"`
	CompletedAt      time.Time `json:"completed_at"`
	ResticSnapshotID string    `json:"restic_snapshot_id,omitempty"`
	Stats            JobStats  `json:"stats"`
	ErrorMessage     string    `json:"error_message,omitempty"`
}

Job report

func LoadPendingReports

func LoadPendingReports() []JobReportRequest

LoadPendingReports reads all pending reports from disk.

type JobStats

type JobStats struct {
	FilesNew            int   `json:"files_new"`
	FilesChanged        int   `json:"files_changed"`
	FilesUnmodified     int   `json:"files_unmodified"`
	DirsNew             int   `json:"dirs_new"`
	DataAddedBytes      int64 `json:"data_added_bytes"`
	TotalFilesProcessed int   `json:"total_files_processed"`
	TotalBytesProcessed int64 `json:"total_bytes_processed"`
	TotalDurationSec    int   `json:"total_duration_seconds"`
}

type LogBatch

type LogBatch struct {
	Lines []string `json:"lines"`
}

Log batch

type Meta

type Meta struct {
	RequestID string `json:"request_id"`
	Cursor    string `json:"cursor,omitempty"`
}

type ProgressReport

type ProgressReport struct {
	RepoID         string  `json:"repo_id"`
	PercentDone    float64 `json:"percent_done"`
	BytesProcessed int64   `json:"bytes_processed"`
	FilesProcessed int     `json:"files_processed"`
	CurrentFile    string  `json:"current_file,omitempty"`
	StartedAt      string  `json:"started_at"`
}

Progress report (sent during backup)

type RegisterAgentRequest

type RegisterAgentRequest struct {
	Name     string `json:"name"`
	Platform string `json:"platform"`
	Arch     string `json:"arch"`
	Hostname string `json:"hostname"`
}

Agent registration

type RegisterAgentResponse

type RegisterAgentResponse struct {
	ID    string `json:"id"`
	Token string `json:"token"`
}

func Register

func Register(baseURL, apiKey string, req RegisterAgentRequest) (*RegisterAgentResponse, error)

Register registers a new agent. Uses API key auth (not agent token).

type RegisterWithTokenResponse added in v0.1.2

type RegisterWithTokenResponse struct {
	AgentID    string `json:"agent_id"`
	AgentToken string `json:"agent_token"`
	APIBaseURL string `json:"api_base_url"`
}

func RegisterWithToken added in v0.1.2

func RegisterWithToken(baseURL, installToken string, req RegisterAgentRequest) (*RegisterWithTokenResponse, error)

RegisterWithToken registers an agent using a pre-authenticated install token.

type RepoConfig

type RepoConfig struct {
	ID                 string               `json:"id"`
	StorageBackendID   string               `json:"storage_backend_id"`
	PolicyID           string               `json:"policy_id,omitempty"`
	ResticRepoPath     string               `json:"restic_repo_path"`
	ResticPassword     string               `json:"restic_password"`
	Paths              []string             `json:"paths"`
	ExcludePatterns    []string             `json:"exclude_patterns"`
	ExcludePresets     []string             `json:"exclude_presets"`
	Tags               []string             `json:"tags"`
	ScheduleCron       string               `json:"schedule_cron,omitempty"`
	BandwidthLimitKiB  int                  `json:"bandwidth_limit_kib,omitempty"`
	PreBackupCommand   string               `json:"pre_backup_command,omitempty"`
	PostBackupCommand  string               `json:"post_backup_command,omitempty"`
	CheckEveryNBackups int                  `json:"check_every_n_backups"`
	Preset             string               `json:"preset,omitempty"` // "full-system", "docker-stop", "docker-hot"
	StorageConfig      StorageBackendConfig `json:"storage_config"`
	ConfigHash         string               `json:"config_hash,omitempty"`
}

Repo config (returned by GET /agents/:id/repos — password decrypted server-side)

type StorageBackendConfig

type StorageBackendConfig struct {
	Provider        string `json:"provider"`
	Endpoint        string `json:"endpoint"`
	Bucket          string `json:"bucket"`
	Region          string `json:"region"`
	AccessKeyID     string `json:"access_key_id"`
	SecretAccessKey string `json:"secret_access_key"`
}

type SystemMetadata

type SystemMetadata struct {
	BootMode        string   `json:"boot_mode"` // "UEFI" or "BIOS"
	Hostname        string   `json:"hostname"`
	Kernel          string   `json:"kernel"`
	Packages        []string `json:"packages,omitempty"` // installed package names
	EnabledServices []string `json:"enabled_services,omitempty"`
	DiskUsage       string   `json:"disk_usage,omitempty"`
}

SystemMetadata is captured by the full-system preset pre-hook.

type VersionInfo

type VersionInfo struct {
	Version   string            `json:"version"`
	Platforms map[string]string `json:"platforms"`
}

Version info

Jump to

Keyboard shortcuts

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