Documentation
¶
Overview ¶
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
Index ¶
- Constants
- func AuthenticateBearer(r *http.Request, expectedToken string) bool
- func AuthenticateBearerHash(r *http.Request, expectedHash string) bool
- func ParseEngineConfig(text string) (map[string]any, error)
- type ActionResponse
- type AgentBuild
- type BootstrapMember
- type BootstrapRequest
- type BootstrapResponse
- type Certificate
- type Client
- func (c *Client) Bootstrap(ctx context.Context, v BootstrapRequest) (BootstrapResponse, error)
- func (c *Client) Close()
- func (c *Client) Config(ctx context.Context) (MemberConfig, error)
- func (c *Client) DialContext(ctx context.Context, network, logical string) (net.Conn, error)
- func (c *Client) Engine(ctx context.Context, engine, action string, req, resp any) error
- func (c *Client) FencePBMRestore(ctx context.Context, requestID string, commandTS int64) (PBMRestartFence, error)
- func (c *Client) ForInstance(host string) (*Client, error)
- func (c *Client) Logs(ctx context.Context, process string, lines int) (LogsResponse, error)
- func (c *Client) Maintenance(ctx context.Context, v Maintenance) error
- func (c *Client) Metrics(ctx context.Context) ([]byte, error)
- func (c *Client) PBM(ctx context.Context, v PBMRequest) (PBMResponse, error)
- func (c *Client) Process(ctx context.Context, a ProcessAction) error
- func (c *Client) Reload(ctx context.Context) error
- func (c *Client) Status(ctx context.Context) (Status, error)
- func (c *Client) StreamingClient() *http.Client
- type ClientOptions
- type ContainerResources
- type Credentials
- type DiskUsage
- type ErrorResponse
- type HTTPError
- type LogLine
- type LogsResponse
- type Maintenance
- type MemberConfig
- type PBMRequest
- type PBMResponse
- type PBMRestartFence
- type ProcessAction
- type ProcessStatus
- type Status
- type TLSConfig
- type VolumeIdentity
- type VolumeStatus
Constants ¶
const ( RoleReplicaSet = "mongod-rs" RoleConfigServer = "mongod-cfg" RoleRouter = "mongos" )
const ConfigCapabilityGaleraListenHost = "mysql-galera-listen-host"
ConfigCapabilityGaleraListenHost advertises strict-decoder support for the numeric Galera bind policy on a configuration pull, including the first pull.
const ConfigCapabilityMySQLListenHost = "mysql-listen-host"
ConfigCapabilityMySQLListenHost advertises support for SQL listener policy.
const DefaultPort = 9443
DefaultPort is the private HTTPS port used by node agents.
const PBMRestoreFenceClockMargin = 30 * time.Second
PBMRestoreFenceClockMargin keeps the old command behind a new PBM listener.
Variables ¶
This section is empty.
Functions ¶
func AuthenticateBearer ¶
AuthenticateBearer compares fixed-length hashes regardless of token length.
func AuthenticateBearerHash ¶
AuthenticateBearerHash authenticates a token against its stored SHA-256 hash.
Types ¶
type ActionResponse ¶
type ActionResponse struct {
Success bool `json:"success"`
Message string `json:"message,omitempty"`
PBMFence *PBMRestartFence `json:"pbmFence,omitempty"`
}
ActionResponse acknowledges an agent control request.
type AgentBuild ¶ added in v0.4.0
type AgentBuild struct {
Version string `json:"version"`
Commit string `json:"commit"`
Build string `json:"build"`
}
AgentBuild is the running Karakoram executable, not the database version.
type BootstrapMember ¶
type BootstrapMember struct {
ID int `json:"id"`
Host string `json:"host"`
Priority *float64 `json:"priority,omitempty"`
Votes *int `json:"votes,omitempty"`
}
BootstrapMember defines one initial replica-set member.
type BootstrapRequest ¶
type BootstrapRequest struct {
ReplSetName string `json:"replSetName"`
Members []BootstrapMember `json:"members"`
UserAdmin Credentials `json:"userAdmin"`
ConfigServer bool `json:"configServer"`
}
BootstrapRequest describes idempotent localhost-exception replica-set initialization.
type BootstrapResponse ¶
type BootstrapResponse struct {
Initialized bool `json:"initialized"`
UserCreated bool `json:"userCreated"`
// Primary redirects localhost-exception creation to the elected member.
// Empty means credentials were created or verified on this invocation.
Primary string `json:"primary,omitempty"`
}
BootstrapResponse reports replica-set and user bootstrap outcomes.
type Certificate ¶
Certificate contains a PEM certificate and its private key.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client performs bearer-authenticated requests over pinned-CA HTTPS.
func NewClient ¶
func NewClient(opts ClientOptions) (*Client, error)
NewClient trusts only the supplied private CA and verifies the hostname.
func (*Client) Bootstrap ¶
func (c *Client) Bootstrap(ctx context.Context, v BootstrapRequest) (BootstrapResponse, error)
Bootstrap initializes the replica set and first administrator idempotently.
func (*Client) Config ¶
func (c *Client) Config(ctx context.Context) (MemberConfig, error)
Config pulls the member configuration from the control plane.
func (*Client) DialContext ¶ added in v0.2.0
DialContext uses this client's namespace transport and instance pin for a native application probe. The caller retains the logical host for TLS.
func (*Client) Engine ¶
Engine invokes an engine-owned authenticated JSON action using the longer engine deadline. Engine and action names share the process-name syntax.
func (*Client) FencePBMRestore ¶ added in v0.2.0
func (c *Client) FencePBMRestore(ctx context.Context, requestID string, commandTS int64) (PBMRestartFence, error)
FencePBMRestore actively replaces PBM only on an agent advertising the stop/wait/start protocol. Legacy success-only responses are never proof.
func (*Client) ForInstance ¶ added in v0.2.0
ForInstance pins connections to one runtime address while retaining the logical member's HTTPS hostname, CA, bearer token and namespace transport. The caller owns the returned client and must Close it; the original client is unchanged.
func (*Client) Maintenance ¶
func (c *Client) Maintenance(ctx context.Context, v Maintenance) error
Maintenance sets database auto-restart suppression.
func (*Client) PBM ¶
func (c *Client) PBM(ctx context.Context, v PBMRequest) (PBMResponse, error)
PBM executes a whitelisted backup-agent command.
func (*Client) Process ¶
func (c *Client) Process(ctx context.Context, a ProcessAction) error
Process executes a whitelisted supervisor process action.
func (*Client) Reload ¶
Reload requests an immediate configuration pull. Applying it can include database startup and credential recovery, so it uses the engine-action budget.
func (*Client) StreamingClient ¶ added in v0.3.0
StreamingClient returns an independent authenticated transport without a whole request or response-header deadline: MCP servers may answer only after a tool finishes, so the caller's context bounds each request. TLS trust, namespace routing and instance pinning are retained. Only requests to this member's exact HTTPS origin may carry its bearer.
type ClientOptions ¶
type ClientOptions struct {
BaseURL string
Token string
CAPEM []byte
Timeout time.Duration
EngineTimeout time.Duration
DialContext func(context.Context, string, string) (net.Conn, error)
// DialInstanceContext authorizes and pins a runtime within the logical
// member's namespace. Arguments are network, logical host:port and instance host.
DialInstanceContext func(context.Context, string, string, string) (net.Conn, error)
}
ClientOptions supplies the HTTPS endpoint, token, trust roots, and request deadlines. EngineTimeout bounds engine-owned actions such as broker drains, which may legitimately outlast ordinary requests; it defaults to three minutes.
type ContainerResources ¶ added in v0.2.0
type ContainerResources struct {
// CPUCores are usable cores: the effective cgroup cpuset size, capped by
// a cpu.max quota when one is set.
CPUCores float64 `json:"cpuCores"`
// MemoryBytes is the cgroup memory limit, or MemTotal without one.
MemoryBytes uint64 `json:"memoryBytes"`
// RootDiskBytes is the size of the filesystem mounted at /.
RootDiskBytes uint64 `json:"rootDiskBytes"`
}
ContainerResources reports the CPU, memory, and root disk a member container currently has. Zero means the value could not be read.
type Credentials ¶
type Credentials struct {
Username string `json:"username"`
Password string `json:"password"`
Database string `json:"database"`
}
Credentials contains local system-user authentication material.
type DiskUsage ¶
type DiskUsage struct {
TotalBytes uint64 `json:"totalBytes"`
UsedBytes uint64 `json:"usedBytes"`
FreeBytes uint64 `json:"freeBytes"`
}
DiskUsage reports data-directory filesystem capacity.
type ErrorResponse ¶
type ErrorResponse struct {
Error string `json:"error"`
}
ErrorResponse describes an agent protocol error.
type HTTPError ¶ added in v0.2.0
HTTPError exposes the response status for protocol capability negotiation. Message contains only the client's bounded, redacted remote diagnostic.
type LogLine ¶
type LogLine struct {
Timestamp time.Time `json:"timestamp"`
Process string `json:"process"`
Stream string `json:"stream"`
Message string `json:"message"`
// Launch identity scopes retained process output to one supervised child.
SupervisorSession string `json:"supervisorSession,omitempty"`
Launch uint64 `json:"launch,omitempty"`
// ExitCode is populated in retained logs only after this launch is reaped.
ExitCode *int `json:"exitCode,omitempty"`
}
LogLine is a timestamped process or container log entry.
type LogsResponse ¶
type LogsResponse struct {
Lines []LogLine `json:"lines"`
}
LogsResponse contains bounded agent process logs.
type Maintenance ¶
type Maintenance struct {
Enabled bool `json:"enabled"`
}
Maintenance controls automatic database process restart suppression.
type MemberConfig ¶
type MemberConfig struct {
Cluster string `json:"cluster"`
Member string `json:"member"`
Volume *VolumeIdentity `json:"volume,omitempty"`
Engine string `json:"engine,omitempty"`
EngineSpec json.RawMessage `json:"engineSpec,omitempty"`
Role string `json:"role"`
ReplSetName string `json:"replSetName"`
Port int `json:"port"`
ConfigDB string `json:"configDB,omitempty"`
ShardServer bool `json:"shardServer,omitempty"`
WiredTigerCacheSizeGB float64 `json:"wiredTigerCacheSizeGB,omitempty"`
SlowOpThresholdMS int64 `json:"slowOpThresholdMS,omitempty"`
EngineVersion string `json:"engineVersion"`
EngineConfig string `json:"engineConfig"`
Keyfile string `json:"keyfile"`
TLS TLSConfig `json:"tls"`
AgentTLS Certificate `json:"agentTLS"`
SystemUsers map[string]Credentials `json:"systemUsers"`
PBMEnabled bool `json:"pbmEnabled"`
// PBMGoMemoryLimitBytes is the CP-derived Go runtime soft limit for the
// next PBM child launch. Zero means an old/unknown budget, not unlimited RAM.
PBMGoMemoryLimitBytes uint64 `json:"pbmGoMemoryLimitBytes,omitempty"`
DesiredProcesses []string `json:"desiredProcesses"`
Maintenance bool `json:"maintenance"`
ConfigVersion int64 `json:"configVersion"`
// CertificateReloadOnly requests identity publication without engine rollout.
// The CP must first observe the matching agent capability.
CertificateReloadOnly bool `json:"certificateReloadOnly,omitempty"`
}
MemberConfig is the secret-bearing desired configuration pulled by a node agent.
type PBMRequest ¶
type PBMRequest struct {
Command string `json:"command"`
RequestID string `json:"requestID,omitempty"`
Args []string `json:"args,omitempty"`
Config json.RawMessage `json:"config,omitempty"`
}
PBMRequest selects a whitelisted PBM command and arguments.
type PBMResponse ¶
type PBMResponse struct {
Output json.RawMessage `json:"output,omitempty"`
Stderr string `json:"stderr,omitempty"`
ExitCode int `json:"exitCode"`
}
PBMResponse contains structured PBM output and exit status.
type PBMRestartFence ¶ added in v0.2.0
type PBMRestartFence struct {
OldExited bool `json:"oldExited"`
PID int `json:"pid"`
StartedAfter time.Time `json:"startedAfter"`
MemberTime time.Time `json:"memberTime"`
}
PBMRestartFence confirms active process replacement, not inferred history.
type ProcessAction ¶
type ProcessAction struct {
Process string `json:"process"`
Action string `json:"action"`
// RequestID is stable across retries of one logical restart.
RequestID string `json:"requestID,omitempty"`
// RestoreCommandTS requests a PBM-only active fence with a member clock guard.
RestoreCommandTS int64 `json:"restoreCommandTS,omitempty"`
}
ProcessAction selects a whitelisted process and supervisor action.
type ProcessStatus ¶
type ProcessStatus struct {
State string `json:"state"`
PID int `json:"pid"`
Restarts int `json:"restarts"`
StartedAt *time.Time `json:"startedAt,omitempty"`
ExitCode *int `json:"exitCode,omitempty"`
Error string `json:"error,omitempty"`
// SupervisorSession and Launch identify actual successful child launches.
// A higher Launch in the same session proves the previous child was reaped;
// unlike StartedAt, these identities do not compare wall clocks.
SupervisorSession string `json:"supervisorSession,omitempty"`
Launch uint64 `json:"launch,omitempty"`
// GoMemoryLimitBytes reports the limit configured at this child's launch;
// changing desired configuration alone does not change a running process.
GoMemoryLimitBytes uint64 `json:"goMemoryLimitBytes,omitempty"`
}
ProcessStatus describes one supervised child process.
type Status ¶
type Status struct {
Agent AgentBuild `json:"agent"`
Processes map[string]ProcessStatus `json:"processes"`
Volume *VolumeStatus `json:"volume,omitempty"`
EngineVersion string `json:"engineVersion"`
ConfigVersion int64 `json:"configVersion"`
Disk DiskUsage `json:"disk"`
HostFingerprint string `json:"hostFingerprint"`
Maintenance bool `json:"maintenance"`
UptimeSeconds int64 `json:"uptimeSeconds"`
// PBMRestoreFence advertises supervised stop/wait/start confirmation.
PBMRestoreFence bool `json:"pbmRestoreFence,omitempty"`
// PBMRestoreIdentity advertises restore-scoped PBM authentication support.
PBMRestoreIdentity bool `json:"pbmRestoreIdentity,omitempty"`
// CertificateReloadOnly advertises reload-only native certificate application.
CertificateReloadOnly bool `json:"certificateReloadOnly,omitempty"`
// Error explains a blocked local recovery without making status unreachable.
Error string `json:"error,omitempty"`
// MongoReady observes authenticated router access to config-server metadata.
// Nil means this agent did not observe router application readiness.
MongoReady *bool `json:"mongoReady,omitempty"`
MongoError string `json:"mongoError,omitempty"`
// Resources is what the container can currently use, read at request
// time. Nil from agents that predate the field or could read nothing.
Resources *ContainerResources `json:"resources,omitempty"`
}
Status reports process, disk, and applied agent configuration state.
type TLSConfig ¶
type TLSConfig struct {
Mode string `json:"mode"`
CAPEM string `json:"caPEM"`
CertPEM string `json:"certPEM"`
KeyPEM string `json:"keyPEM"`
}
TLSConfig configures transport encryption and certificate material.
type VolumeIdentity ¶ added in v0.2.0
type VolumeIdentity struct {
ClusterUID string `json:"clusterUid"`
Member string `json:"member"`
Volume string `json:"volume"`
VolumeID string `json:"volumeId"`
Initialized bool `json:"initialized"`
}
VolumeIdentity binds a durable data directory to one cluster/member incarnation. Initialized is a control-plane receipt: a missing sentinel must not authorize fresh initialization after this member has previously held initialized data.
type VolumeStatus ¶ added in v0.2.0
type VolumeStatus struct {
Identity VolumeIdentity `json:"identity"`
Verified bool `json:"verified"`
Lost bool `json:"lost"`
Message string `json:"message,omitempty"`
}
VolumeStatus remains observable even when the data safety gate blocks Apply.