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 DialTunnel(cfg *config.AgentConfig, store *TokenStore) (*grpc.ClientConn, error)
- func FindDefaultConfig(agentType string) string
- 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 ServerHTTPClient(cfg *config.AgentConfig) *http.Client
- 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
- 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 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 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 ServerHTTPClient ¶
func ServerHTTPClient(cfg *config.AgentConfig) *http.Client
ServerHTTPClient builds the HTTP client for the FallBCK server (trusting a private CA if configured)
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.
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