api

package
v0.9.0 Latest Latest
Warning

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

Go to latest
Published: Apr 8, 2026 License: MIT Imports: 14 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) Deregister added in v0.2.3

func (c *Client) Deregister(ctx context.Context) error

Deregister deletes this agent from the NerdBackup API.

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) GetPendingBackups added in v0.2.5

func (c *Client) GetPendingBackups(ctx context.Context) ([]PendingBackup, error)

GetPendingBackups fetches any backup triggers queued from the dashboard.

func (*Client) GetPendingFileDumps added in v0.3.0

func (c *Client) GetPendingFileDumps(ctx context.Context) ([]PendingFileDump, error)

GetPendingFileDumps fetches any file download requests from the dashboard.

func (*Client) GetPendingRestores added in v0.2.4

func (c *Client) GetPendingRestores(ctx context.Context) ([]PendingRestore, error)

GetPendingRestores fetches any restore requests queued from the dashboard.

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.

func (*Client) UploadFileDump added in v0.3.0

func (c *Client) UploadFileDump(ctx context.Context, requestID string, data []byte, fileName string) error

UploadFileDump uploads a dumped file back to the server (base64 encoded).

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"`
	DashboardJobID   string                   `json:"dashboard_job_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"`
	Files            []map[string]interface{} `json:"files,omitempty"`
	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 PendingBackup added in v0.2.5

type PendingBackup struct {
	JobID     string `json:"jobId"`
	RepoID    string `json:"repoId"`
	CreatedAt string `json:"createdAt"`
}

Pending backup trigger from dashboard

type PendingFileDump added in v0.3.0

type PendingFileDump struct {
	RequestID  string `json:"requestId"`
	SnapshotID string `json:"snapshotId"`
	FilePath   string `json:"filePath"`
	CreatedAt  string `json:"createdAt"`
}

Pending file dump request from dashboard (single file download)

type PendingRestore added in v0.2.4

type PendingRestore struct {
	JobID        string   `json:"jobId"`
	SnapshotID   string   `json:"snapshotId"`
	TargetPath   string   `json:"targetPath"`
	IncludePaths []string `json:"includePaths"`
	ExcludePaths []string `json:"excludePaths"`
	CreatedAt    string   `json:"createdAt"`
}

Pending restore request from dashboard

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