Documentation
¶
Overview ¶
Package runtime is the shared daemon skeleton of the fallbck agents: configuration lookup and self-enrollment, the Temporal client and PBS tunnel connections through the server gateway, the activity worker, and the heartbeat / token-rotation loop. Agent binaries only add their activities.
Index ¶
- func ConnectionOptions(cfg *config.AgentConfig) (string, client.ConnectionOptions, error)
- func DBPasswordFetcher(cfg *config.AgentConfig, store *TokenStore) func(ctx context.Context, ticket string) (string, error)
- func DialTunnel(cfg *config.AgentConfig, store *TokenStore) (*grpc.ClientConn, error)
- func FindDefaultConfig(agentType string) string
- func IsWindowsService() bool
- func LoadConfig(a Agent, configPath string) (*config.AgentConfig, string, error)
- func PBSCredentialsFetcher(cfg *config.AgentConfig, store *TokenStore) func(ctx context.Context, ticket string) (*backup.DirectOptions, error)
- func PrintEnrolled(a Agent, cfg *config.AgentConfig)
- func ProgressReporter(cfg *config.AgentConfig, store *TokenStore) ...
- func Run(a Agent, cfg *config.AgentConfig, configPath string, ...) error
- func RunAsService(string, func(stop <-chan struct{}) error) error
- func RunUntil(a Agent, cfg *config.AgentConfig, configPath string, ...) error
- func ServerHTTPClient(cfg *config.AgentConfig) *http.Client
- func ServiceCommand(name, _, _, action, _ string) error
- func StartHeartbeat(ctx context.Context, cfg *config.AgentConfig, store *TokenStore, ...)
- func TicketGet(ctx context.Context, httpClient *http.Client, cfg *config.AgentConfig, ...) error
- func TicketPost(ctx context.Context, httpClient *http.Client, cfg *config.AgentConfig, ...) error
- func TicketRefresher(cfg *config.AgentConfig, store *TokenStore) func(ctx context.Context, ticket string) (string, int64, error)
- type Agent
- type Conns
- type DebugControl
- type LogRing
- type Logging
- type TokenStore
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ConnectionOptions ¶
func ConnectionOptions(cfg *config.AgentConfig) (string, client.ConnectionOptions, error)
ConnectionOptions derives the Temporal gRPC endpoint and TLS settings from ServerURL. The FallBCK server multiplexes gRPC and HTTP on the same port; https → TLS, http → h2c.
func DBPasswordFetcher ¶ added in v0.9.5
func DBPasswordFetcher(cfg *config.AgentConfig, store *TokenStore) func(ctx context.Context, ticket string) (string, error)
DBPasswordFetcher retrieves the server-stored password of a database job (GET /api/v1/agents/db-credentials with the run's ticket)
func DialTunnel ¶ added in v0.7.2
func DialTunnel(cfg *config.AgentConfig, store *TokenStore) (*grpc.ClientConn, error)
DialTunnel opens only the agent-authenticated gRPC connection to the gateway (PBS tunnel and other agent services); used by worker processes that need no Temporal client.
func FindDefaultConfig ¶
FindDefaultConfig returns the first existing agent.yaml among the conventional locations for the agent type: the default data dir (env / system dir as root / home), then the others.
func IsWindowsService ¶ added in v0.9.5
func IsWindowsService() bool
IsWindowsService is always false outside Windows
func LoadConfig ¶
LoadConfig loads the agent configuration (configPath or the default location) and self-enrolls when the agent has no identity but an enrollment key is configured (config file or FALLBCK_AGENT_ENROLLMENT_KEY). It returns the configuration and the path it should be persisted to.
func PBSCredentialsFetcher ¶
func PBSCredentialsFetcher(cfg *config.AgentConfig, store *TokenStore) func(ctx context.Context, ticket string) (*backup.DirectOptions, error)
PBSCredentialsFetcher retrieves PBS connection details for direct-mode jobs
func PrintEnrolled ¶
func PrintEnrolled(a Agent, cfg *config.AgentConfig)
PrintEnrolled prints the post-enrollment summary and how to start the service
func ProgressReporter ¶ added in v0.9.0
func ProgressReporter(cfg *config.AgentConfig, store *TokenStore) func(ctx context.Context, ticket string, runID uuid.UUID, phase string, items map[string]rundetail.ProgressItem) error
ProgressReporter returns a best-effort function that posts live run progress to the server (phase and/or per-item statuses), authenticated with the run's backup ticket.
func Run ¶
func Run(a Agent, cfg *config.AgentConfig, configPath string, register func(w worker.Worker, conns *Conns, store *TokenStore) error) error
Run starts the daemon: connections, an activity-only worker on the agent's task queue with the activities registered by register, and the heartbeat loop; it blocks until SIGINT/SIGTERM.
func RunAsService ¶ added in v0.9.5
RunAsService is Windows-only
func RunUntil ¶ added in v0.9.5
func RunUntil(a Agent, cfg *config.AgentConfig, configPath string, register func(w worker.Worker, conns *Conns, store *TokenStore) error, stop <-chan struct{}) error
RunUntil is Run with an explicit stop signal (the Windows service control manager closes stop on a stop request)
func ServerHTTPClient ¶
func ServerHTTPClient(cfg *config.AgentConfig) *http.Client
ServerHTTPClient builds the HTTP client for the FallBCK server (trusting a private CA and/or skipping verification if configured). A CA bundle that cannot be loaded is logged and the system roots are used instead, so the failure shows up here rather than as an opaque certificate error on the first request.
func ServiceCommand ¶ added in v0.9.5
ServiceCommand is Windows-only; Linux installs use the packaged systemd/OpenRC units
func StartHeartbeat ¶
func StartHeartbeat(ctx context.Context, cfg *config.AgentConfig, store *TokenStore, version string, logging *Logging)
StartHeartbeat reports the agent online every 30 s, applies the server's remote debug-logging toggle from the response, and rotates the token when it approaches expiry; it returns when ctx is cancelled. logging may be nil.
func TicketGet ¶
func TicketGet(ctx context.Context, httpClient *http.Client, cfg *config.AgentConfig, store *TokenStore, path, ticket string, out any) error
TicketGet performs an agent-authenticated GET carrying a backup ticket and decodes the JSON response into out.
func TicketPost ¶ added in v0.7.2
func TicketPost(ctx context.Context, httpClient *http.Client, cfg *config.AgentConfig, store *TokenStore, path, ticket string, body, out any) error
TicketPost performs an agent-authenticated POST carrying a backup ticket, a JSON body, and decodes the JSON response into out.
func TicketRefresher ¶ added in v0.9.5
func TicketRefresher(cfg *config.AgentConfig, store *TokenStore) func(ctx context.Context, ticket string) (string, int64, error)
TicketRefresher returns a function that re-issues a run's backup ticket with a fresh snapshot timestamp (POST /api/v1/agents/ticket/refresh); retried backup activities use it so PBS does not reject the retry as older than the previous attempt's snapshot.
Types ¶
type Agent ¶
type Agent struct {
// Name is the binary name (fallbck-agent, fallbck-db-agent); used for identities and messages
Name string
// Type is config.AgentTypeFilesystem or config.AgentTypeDatabase
Type string
Version string
// Logging is the process logging setup (SetupLogging); the heartbeat loop applies
// the server's per-agent debug toggle to it and failures attach its ring buffer
Logging *Logging
// PersistToken overrides where token rotations are stored (TokenStore.Persist);
// used by the kubernetes agent to write into its identity Secret
PersistToken func(cfg *config.AgentConfig) error
}
Agent identifies the binary using the runtime
type Conns ¶
type Conns struct {
HostPort string
Temporal client.Client
// Tunnel carries PBS backup sessions and other agent-authenticated gRPC services
Tunnel *grpc.ClientConn
}
Conns are the agent's connections to the server gateway
func Connect ¶
func Connect(cfg *config.AgentConfig, store *TokenStore, identity string) (*Conns, error)
Connect opens the Temporal client and the tunnel connection through the gateway, both authenticated with the agent token
type DebugControl ¶ added in v0.6.2
type DebugControl struct {
// contains filtered or unexported fields
}
DebugControl owns the agent's stdout log level: a base level from environment and config, and a runtime override the server toggles per agent via heartbeats.
func (*DebugControl) Level ¶ added in v0.6.2
func (d *DebugControl) Level() slog.Level
Level reports the current stdout log level
func (*DebugControl) SetBase ¶ added in v0.6.2
func (d *DebugControl) SetBase(level slog.Level)
SetBase installs the configured base level (unless a remote override is active)
func (*DebugControl) SetRemoteDebug ¶ added in v0.6.2
func (d *DebugControl) SetRemoteDebug(enabled bool) bool
SetRemoteDebug applies or clears the server-side debug toggle; it reports whether the state changed.
type LogRing ¶ added in v0.6.2
type LogRing struct {
// contains filtered or unexported fields
}
LogRing keeps the most recent log lines (all levels, independent of the stdout level) so a failed backup can ship them to the server.
type Logging ¶ added in v0.6.2
type Logging struct {
Control *DebugControl
Ring *LogRing
}
Logging is the agent's logging setup: the stdout logger (level adjustable at runtime) plus the ring buffer that always captures debug-level lines.
func SetupLogging ¶ added in v0.6.2
func SetupLogging() *Logging
SetupLogging installs the process-wide logger: JSON on stdout at the environment's level (adjustable later), and a text copy of every record — including debug — into the ring buffer.
func (*Logging) ApplyConfigLogLevel ¶ added in v0.6.2
func (l *Logging) ApplyConfigLogLevel(cfg *config.AgentConfig)
ApplyConfigLogLevel applies agent.yaml's log_level as the base level unless the environment already chose one (DEBUG / FALLBCK_LOG_LEVEL win).
type TokenStore ¶
type TokenStore struct {
// Persist overrides where rotations are stored (e.g. a Kubernetes Secret);
// default: rewrite the token fields of the config file
Persist func(cfg *config.AgentConfig) error
// contains filtered or unexported fields
}
TokenStore holds the current agent token and persists rotations
func NewTokenStore ¶
func NewTokenStore(cfg *config.AgentConfig, configPath string) *TokenStore
NewTokenStore wraps the loaded configuration; rotations are written to configPath
func (*TokenStore) ExpiresAt ¶
func (t *TokenStore) ExpiresAt() time.Time
func (*TokenStore) Token ¶
func (t *TokenStore) Token() string
Source Files