api

package
v0.9.1 Latest Latest
Warning

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

 Go to latest Published: Sep 10, 2026 License: AGPL-3.0 Imports: 20 Imported by: 0

Documentation

Index

Constants

View Source 
const BackupTicketHeader = "X-Fallbck-Backup-Ticket"

BackupTicketHeader carries the backup ticket on agent HTTP requests

Variables

This section is empty.

Functions

This section is empty.

Types

type CreateAPIKeyRequest 

type CreateAPIKeyRequest struct {
	Name      string     `json:"name"`
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
}

CreateAPIKeyRequest creates an admin API key for fallbck-ctl / automation

type CreateAPIKeyResponse 

type CreateAPIKeyResponse struct {
	ID        uuid.UUID  `json:"id"`
	Name      string     `json:"name"`
	RawKey    string     `json:"raw_key"`
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
}

CreateAPIKeyResponse returns the raw key exactly once

type CreateTargetRequest added in v0.6.0 

type CreateTargetRequest struct {
	Name        string `json:"name"`
	TargetType  string `json:"target_type"`
	Endpoint    string `json:"endpoint"`
	Datastore   string `json:"datastore"`
	Namespace   string `json:"namespace"`
	AuthToken   string `json:"auth_token"`
	Fingerprint string `json:"fingerprint"`
	TLSVerify   bool   `json:"tls_verify"`
	PxarFormat  string `json:"pxar_format"`
}

CreateTargetRequest registers a backup target. AuthToken is the PBS API token ("user@realm!tokenid=secret" or with the PBSAPIToken= prefix); it is stored and used only server-side.

type CreateTokenRequest 

type CreateTokenRequest struct {
	Name      string    `json:"name"`
	MaxUses   int       `json:"max_uses"` // 0 for unlimited, default 1
	ExpiresAt time.Time `json:"expires_at"`
}

CreateTokenRequest is used by the admin UI/CLI to create an agent enrollment token

type CreateTokenResponse 

type CreateTokenResponse struct {
	ID        uuid.UUID `json:"id"`
	Name      string    `json:"name"`
	RawToken  string    `json:"raw_token"`
	ExpiresAt time.Time `json:"expires_at"`
	MaxUses   int       `json:"max_uses"`
}

CreateTokenResponse returns the raw one-time enrollment token to the admin

type DBCredentials added in v0.6.0 

type DBCredentials struct {
	Password string `json:"password"`
}

DBCredentials hands an agent the server-stored database password for a run

type EnrollRequest 

type EnrollRequest struct {
	Token     string `json:"token"`
	Hostname  string `json:"hostname"`
	OS        string `json:"os"`
	Arch      string `json:"arch"`
	Version   string `json:"version"`
	IPAddress string `json:"ip_address,omitempty"`
	// AgentType is "filesystem" (default) or "database"
	AgentType string `json:"agent_type,omitempty"`
}

EnrollRequest is sent by an agent to enroll with the central server

type EnrollResponse 

type EnrollResponse struct {
	AgentID        uuid.UUID `json:"agent_id"`
	TaskQueue      string    `json:"task_queue"`
	Namespace      string    `json:"namespace"`
	AuthToken      string    `json:"auth_token"`
	TokenExpiresAt time.Time `json:"token_expires_at"`
	ServerURL      string    `json:"server_url"`
	// ServerCAPEM optionally carries a private CA bundle the agent must trust for ServerURL
	ServerCAPEM string `json:"server_ca_pem,omitempty"`
	ProxyURL    string `json:"proxy_url"`
}

EnrollResponse contains the credentials and configuration needed for the agent to start. Everything the agent talks to (HTTP API, PBS proxy, Temporal gRPC) lives behind ServerURL.

type HeartbeatRequest 

type HeartbeatRequest struct {
	AgentID uuid.UUID `json:"agent_id"`
	Status  string    `json:"status"`
	Version string    `json:"version"`
}

HeartbeatRequest is sent by an agent periodically

type HeartbeatResponse added in v0.6.2 

type HeartbeatResponse struct {
	Status string `json:"status"`
	// DebugLogging tells the agent to raise its log level to debug (web UI toggle)
	DebugLogging bool `json:"debug_logging"`
}

HeartbeatResponse acknowledges a heartbeat and carries server-side agent settings

type JobScheduler added in v0.6.2 

type JobScheduler interface {
	Sync(ctx context.Context, job *db.BackupJob) error
	Remove(ctx context.Context, jobID uuid.UUID) error
}

JobScheduler mirrors scheduler.Scheduler (interface here to keep tests light)

type MeResponse 

type MeResponse struct {
	Kind    string `json:"kind"`
	Subject string `json:"subject"`
	Email   string `json:"email,omitempty"`
	Name    string `json:"name,omitempty"`
}

MeResponse describes the authenticated admin principal

type Middleware 

type Middleware = func(http.Handler) http.Handler

Middleware is a chi-compatible middleware

type PBSCredentials added in v0.6.0 

type PBSCredentials struct {
	Endpoint    string `json:"endpoint"`
	Datastore   string `json:"datastore"`
	Namespace   string `json:"namespace"`
	Fingerprint string `json:"fingerprint"`
	TLSVerify   bool   `json:"tls_verify"`
	// APIToken is the canonical user@realm!tokenid:secret
	APIToken string `json:"api_token"`
}

PBSCredentials are handed to an agent for a job configured with direct_pbs

type RotateTokenResponse 

type RotateTokenResponse struct {
	AuthToken      string    `json:"auth_token"`
	TokenExpiresAt time.Time `json:"token_expires_at"`
}

RotateTokenResponse carries a freshly issued agent token

type RunProgressRequest added in v0.9.0 

type RunProgressRequest struct {
	RunID uuid.UUID `json:"run_id"`
	// Phase is the current human-readable step (optional)
	Phase string `json:"phase,omitempty"`
	// Items are per-unit statuses keyed by a stable id (PVC group, database) (optional)
	Items map[string]rundetail.ProgressItem `json:"items,omitempty"`
}

RunProgressRequest is posted by an agent during a run to update its live progress

type ServerAPI 

type ServerAPI struct {
	DB           *db.DB
	Temporal     client.Client
	Config       *config.ServerConfig
	TokenManager *auth.TokenManager
	// Verifier is used to invalidate cached agent state on revocation (may be nil)
	Verifier *auth.AgentVerifier
	// Scheduler keeps Temporal Schedules aligned with jobs (may be nil)
	Scheduler JobScheduler
}

ServerAPI holds database, Temporal client, config and token services for HTTP requests

func NewServerAPI 

func NewServerAPI(database *db.DB, temporalClient client.Client, cfg *config.ServerConfig, tm *auth.TokenManager, verifier *auth.AgentVerifier) *ServerAPI

NewServerAPI initializes the API service

func (*ServerAPI) HandleAgentEnroll 

func (s *ServerAPI) HandleAgentEnroll(w http.ResponseWriter, r *http.Request)

HandleAgentEnroll processes an agent enrollment request with a one-time token and issues the agent its bearer token.

func (*ServerAPI) HandleAgentHeartbeat 

func (s *ServerAPI) HandleAgentHeartbeat(w http.ResponseWriter, r *http.Request)

HandleAgentHeartbeat updates agent last_seen_at and status

func (*ServerAPI) HandleCancelRun added in v0.3.1 

func (s *ServerAPI) HandleCancelRun(w http.ResponseWriter, r *http.Request)

HandleCancelRun cancels an in-flight backup run. The Temporal workflow is cancelled, which tells the agent activity to stop; the workflow then finalises the run as "cancelled". Until that happens the run shows as "cancelling". A run that never started (still pending, or no workflow) is marked cancelled immediately.

func (*ServerAPI) HandleCreateAPIKey 

func (s *ServerAPI) HandleCreateAPIKey(w http.ResponseWriter, r *http.Request)

HandleCreateAPIKey mints an admin API key

func (*ServerAPI) HandleCreateJob 

func (s *ServerAPI) HandleCreateJob(w http.ResponseWriter, r *http.Request)

HandleCreateJob creates a backup job

func (*ServerAPI) HandleCreateTarget 

func (s *ServerAPI) HandleCreateTarget(w http.ResponseWriter, r *http.Request)

HandleCreateTarget registers a new backup target

func (*ServerAPI) HandleCreateToken 

func (s *ServerAPI) HandleCreateToken(w http.ResponseWriter, r *http.Request)

HandleCreateToken creates a new one-time enrollment token

func (*ServerAPI) HandleDBCredentials added in v0.6.0 

func (s *ServerAPI) HandleDBCredentials(w http.ResponseWriter, r *http.Request)

HandleDBCredentials hands a database agent the password stored on a database job for the run identified by its backup ticket. Like HandlePBSCredentials, the ticket must have been issued to the calling agent.

func (*ServerAPI) HandleDeleteAgent 

func (s *ServerAPI) HandleDeleteAgent(w http.ResponseWriter, r *http.Request)

HandleDeleteAgent removes an agent

func (*ServerAPI) HandleDeleteJob 

func (s *ServerAPI) HandleDeleteJob(w http.ResponseWriter, r *http.Request)

HandleDeleteJob deletes a job

func (*ServerAPI) HandleDeleteTarget 

func (s *ServerAPI) HandleDeleteTarget(w http.ResponseWriter, r *http.Request)

HandleDeleteTarget deletes a target

func (*ServerAPI) HandleDeleteToken added in v0.6.0 

func (s *ServerAPI) HandleDeleteToken(w http.ResponseWriter, r *http.Request)

HandleDeleteToken invalidates an enrollment token immediately

func (*ServerAPI) HandleGetAgent 

func (s *ServerAPI) HandleGetAgent(w http.ResponseWriter, r *http.Request)

HandleGetAgent returns a single agent by ID

func (*ServerAPI) HandleGetJob 

func (s *ServerAPI) HandleGetJob(w http.ResponseWriter, r *http.Request)

HandleGetJob returns job by ID

func (*ServerAPI) HandleGetRun added in v0.3.1 

func (s *ServerAPI) HandleGetRun(w http.ResponseWriter, r *http.Request)

HandleGetRun returns a single backup run

func (*ServerAPI) HandleGetTarget 

func (s *ServerAPI) HandleGetTarget(w http.ResponseWriter, r *http.Request)

HandleGetTarget gets target by ID

func (*ServerAPI) HandleHealth 

func (s *ServerAPI) HandleHealth(w http.ResponseWriter, r *http.Request)

HandleHealth returns the system health status

func (*ServerAPI) HandleListAPIKeys 

func (s *ServerAPI) HandleListAPIKeys(w http.ResponseWriter, r *http.Request)

HandleListAPIKeys lists API keys (hashes are never returned)

func (*ServerAPI) HandleListAgents 

func (s *ServerAPI) HandleListAgents(w http.ResponseWriter, r *http.Request)

HandleListAgents returns all registered agents

func (*ServerAPI) HandleListJobs 

func (s *ServerAPI) HandleListJobs(w http.ResponseWriter, r *http.Request)

HandleListJobs returns all jobs

func (*ServerAPI) HandleListRuns 

func (s *ServerAPI) HandleListRuns(w http.ResponseWriter, r *http.Request)

HandleListRuns returns recent backup runs

func (*ServerAPI) HandleListTargets 

func (s *ServerAPI) HandleListTargets(w http.ResponseWriter, r *http.Request)

HandleListTargets returns all backup targets

func (*ServerAPI) HandleListTokens 

func (s *ServerAPI) HandleListTokens(w http.ResponseWriter, r *http.Request)

HandleListTokens lists all enrollment tokens

func (*ServerAPI) HandleMe 

func (s *ServerAPI) HandleMe(w http.ResponseWriter, r *http.Request)

HandleMe returns the authenticated admin principal

func (*ServerAPI) HandlePBSCredentials added in v0.6.0 

func (s *ServerAPI) HandlePBSCredentials(w http.ResponseWriter, r *http.Request)

HandlePBSCredentials hands an agent the PBS connection details for a run whose job is configured with direct_pbs. The agent authenticates with its bearer token and presents the run's backup ticket; the ticket must belong to the agent and the job must be in direct mode. Jobs using the server tunnel never expose the token.

func (*ServerAPI) HandleRevokeAPIKey 

func (s *ServerAPI) HandleRevokeAPIKey(w http.ResponseWriter, r *http.Request)

HandleRevokeAPIKey revokes an API key

func (*ServerAPI) HandleRotateAgentToken 

func (s *ServerAPI) HandleRotateAgentToken(w http.ResponseWriter, r *http.Request)

HandleRotateAgentToken issues a fresh bearer token to an authenticated agent (same token version, so the old token stays valid until it expires or the agent is revoked).

func (*ServerAPI) HandleRunProgress added in v0.9.0 

func (s *ServerAPI) HandleRunProgress(w http.ResponseWriter, r *http.Request)

HandleRunProgress records live progress for a run. The caller presents its agent bearer token and the run's backup ticket; the run must belong to the ticket's job and agent and still be active. Progress is best-effort — failures never fail a run.

func (*ServerAPI) HandleSetAgentDebug added in v0.6.2 

func (s *ServerAPI) HandleSetAgentDebug(w http.ResponseWriter, r *http.Request)

HandleSetAgentDebug toggles remote debug logging for an agent; the agent applies it on its next heartbeat (within ~30s), no restart needed

func (*ServerAPI) HandleTriggerJob 

func (s *ServerAPI) HandleTriggerJob(w http.ResponseWriter, r *http.Request)

HandleTriggerJob starts an on-demand backup execution for a job

func (*ServerAPI) HandleUpdateJob added in v0.6.0 

func (s *ServerAPI) HandleUpdateJob(w http.ResponseWriter, r *http.Request)

HandleUpdateJob replaces a job's configuration (name, agent, target, paths, schedule, retention, enabled, direct_pbs). The job ID in the path wins over any in the body.

func (*ServerAPI) HandleUpdateTarget added in v0.9.0 

func (s *ServerAPI) HandleUpdateTarget(w http.ResponseWriter, r *http.Request)

HandleUpdateTarget replaces a target's configuration. The API token is optional on update: leave auth_token blank to keep the stored token, or supply a new one to replace it. The path ID wins over any ID in the body.

func (*ServerAPI) HandleVolumeTicket added in v0.7.2 

func (s *ServerAPI) HandleVolumeTicket(w http.ResponseWriter, r *http.Request)

HandleVolumeTicket mints a per-volume backup ticket for a kubernetes run: identical claims to the session ticket, with the backup group swapped to the volume's group (which must extend the session group with "-pvc-"). Fetched just-in-time per volume so retried volumes always hold a fresh ticket.

func (*ServerAPI) HandleWorkerToken added in v0.7.2 

func (s *ServerAPI) HandleWorkerToken(w http.ResponseWriter, r *http.Request)

HandleWorkerToken mints a short-lived secondary agent bearer for a run's worker pods (same agent identity, 6h TTL); requires the run's session ticket.

func (*ServerAPI) RegisterRoutes 

func (s *ServerAPI) RegisterRoutes(r chi.Router, admin, agent Middleware)

RegisterRoutes registers all API routes onto the Chi router. admin protects the administrative API, agent protects agent-authenticated endpoints.

type SetAgentDebugRequest added in v0.6.2 

type SetAgentDebugRequest struct {
	Enabled bool `json:"enabled"`
}

SetAgentDebugRequest toggles an agent's remote debug logging

type VolumeTicketRequest added in v0.7.2 

type VolumeTicketRequest struct {
	// VolumeBackupID must extend the run's group: <cluster group>-pvc-<ns>-<name>
	VolumeBackupID string `json:"volume_backup_id"`
}

VolumeTicketRequest asks for a per-volume backup ticket during a kubernetes run

type VolumeTicketResponse added in v0.7.2 

type VolumeTicketResponse struct {
	Ticket string `json:"ticket"`
}

VolumeTicketResponse carries the freshly minted ticket

type WorkerTokenResponse added in v0.7.2 

type WorkerTokenResponse struct {
	AuthToken      string    `json:"auth_token"`
	TokenExpiresAt time.Time `json:"token_expires_at"`
}

WorkerTokenResponse carries a short-lived agent bearer for worker pods

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.