Help us shape the future of Go! Take the 2026 Go Developer Survey

agentapi

package
v0.4.2 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors

Index

Constants

View Source
const (
	RoleReplicaSet   = "mongod-rs"
	RoleConfigServer = "mongod-cfg"
	RoleRouter       = "mongos"
)
View Source
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.

View Source
const ConfigCapabilityMySQLListenHost = "mysql-listen-host"

ConfigCapabilityMySQLListenHost advertises support for SQL listener policy.

View Source
const DefaultPort = 9443

DefaultPort is the private HTTPS port used by node agents.

View Source
const PBMRestoreFenceClockMargin = 30 * time.Second

PBMRestoreFenceClockMargin keeps the old command behind a new PBM listener.

Variables

This section is empty.

Functions

func AuthenticateBearer

func AuthenticateBearer(r *http.Request, expectedToken string) bool

AuthenticateBearer compares fixed-length hashes regardless of token length.

func AuthenticateBearerHash

func AuthenticateBearerHash(r *http.Request, expectedHash string) bool

AuthenticateBearerHash authenticates a token against its stored SHA-256 hash.

func ParseEngineConfig

func ParseEngineConfig(text string) (map[string]any, error)

ParseEngineConfig is the shared provider/agent override policy. Parent scalar replacements and dotted YAML keys cannot bypass managed-key ownership.

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

type Certificate struct {
	CertPEM string `json:"certPEM"`
	KeyPEM  string `json:"keyPEM"`
}

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

Bootstrap initializes the replica set and first administrator idempotently.

func (*Client) Close

func (c *Client) Close()

Close releases idle HTTPS connections.

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

func (c *Client) DialContext(ctx context.Context, network, logical string) (net.Conn, error)

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

func (c *Client) Engine(ctx context.Context, engine, action string, req, resp any) error

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

func (c *Client) ForInstance(host string) (*Client, error)

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) Logs

func (c *Client) Logs(ctx context.Context, process string, lines int) (LogsResponse, error)

Logs reads a bounded process log tail.

func (*Client) Maintenance

func (c *Client) Maintenance(ctx context.Context, v Maintenance) error

Maintenance sets database auto-restart suppression.

func (*Client) Metrics

func (c *Client) Metrics(ctx context.Context) ([]byte, error)

Metrics reads the agent Prometheus exposition.

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

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

Reload requests an immediate configuration pull. Applying it can include database startup and credential recovery, so it uses the engine-action budget.

func (*Client) Status

func (c *Client) Status(ctx context.Context) (Status, error)

Status reads observed node-agent state.

func (*Client) StreamingClient added in v0.3.0

func (c *Client) StreamingClient() *http.Client

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

type HTTPError struct {
	StatusCode              int
	Method, Action, Message string
}

HTTPError exposes the response status for protocol capability negotiation. Message contains only the client's bounded, redacted remote diagnostic.

func (*HTTPError) Error added in v0.2.0

func (e *HTTPError) Error() string

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL