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

agent

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: 42 Imported by: 0

Documentation

Overview

Package agent supervises member processes and the authenticated node API.

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Readiness 

func Readiness(ctx context.Context, o Options, args []string, engines ...Engine) error

Readiness dispatches the local probe, defaulting to the built-in PSMDB TCP probe.

func ReexecIfPID1 added in v0.2.0 

func ReexecIfPID1() (handled bool, code int, err error)

ReexecIfPID1 isolates init duties from the real member process. The child owns its os/exec waits; this parent alone reaps daemonized descendants adopted by PID 1. A broad reaper in the real member would race its command waiters. Outside a PID namespace's init position this function does nothing.

func RenderConfig 

func RenderConfig(c agentapi.MemberConfig, dataDir string) ([]byte, error)

RenderConfig renders a MongoDB configuration, rejecting overrides of agent-owned keys.

func Run 

func Run(ctx context.Context, o Options, engines ...Engine) error

Run pulls configuration, supervises member processes and serves the private HTTPS API.

Types

type Engine 

type Engine interface {
	Name() string
	Processes() []string
	Apply(context.Context, *Node, agentapi.MemberConfig) ([]string, error)
	Readiness(context.Context, Options, []string) error
	Version(context.Context) string
	Metrics(context.Context, *Node) []Metric
	Routes(*http.ServeMux, *Node)
}

Engine supplies node-local mechanisms; the agent owns transport and supervision.

type Metric 

type Metric struct {
	Name, Help string
	Labels     map[string]string
	Value      float64
	Counter    bool
}

Metric is an engine metric added to the generic member exposition.

type Node 

type Node struct {
	// contains filtered or unexported fields
}

Node exposes protected files and process control to an in-process engine.

func (*Node) Action 

func (n *Node) Action(ctx context.Context, name, action string) error

Action applies engine intent without releasing durable operator holds. Explicit API start/restart actions, unlike configuration pulls, release stop holds.

func (*Node) Config 

func (n *Node) Config() agentapi.MemberConfig

func (*Node) Configure 

func (n *Node) Configure(name string, spec ProcessSpec) error

func (*Node) DataDir 

func (n *Node) DataDir() string

func (*Node) LogTail 

func (n *Node) LogTail(name string, lines int) []agentapi.LogLine

func (*Node) Logger 

func (n *Node) Logger() *slog.Logger

func (*Node) Maintenance 

func (n *Node) Maintenance() bool

func (*Node) Options 

func (n *Node) Options() Options

func (*Node) Signal added in v0.2.0 

func (n *Node) Signal(name string, signal syscall.Signal) error

Signal targets only the supervisor's current owned child, never a discovered PID.

func (*Node) Snapshot 

func (n *Node) Snapshot() (map[string]agentapi.ProcessStatus, bool)

func (*Node) Start added in v0.4.0 

func (n *Node) Start(ctx context.Context, name string) error

Start releases a durable engine stop hold and reapplies start intent. The caller must only release a hold it owns; maintenance and desired intent remain enforced by Action.

func (*Node) Stop added in v0.2.0 

func (n *Node) Stop(ctx context.Context, name string) error

Stop persists a stop hold before stopping a process. Configuration pulls and restarts preserve the hold; an explicit process API start/restart releases it.

func (*Node) Stopped 

func (n *Node) Stopped(name string) bool

func (*Node) WithLock 

func (n *Node) WithLock(ctx context.Context, fn func(*Node) error) error

WithLock serializes an engine command with Apply and generic control changes. The callback toolkit allows nested Actions without re-locking. It is scoped to the callback and must not escape it. Context cancellation bounds the lock wait; the callback is responsible for using ctx to bound its own work.

func (*Node) WriteFile 

func (n *Node) WriteFile(name string, data []byte, mode os.FileMode) error

WriteFile atomically replaces a file below DATA_DIR/karakoram with owner-only permissions. Rooted filesystem operations also reject symlink escapes from this directory.

type Options 

type Options struct {
	ControlPlaneURL, InternalCAPEM, Token, Cluster, Member, DataDir string
	Listen                                                          string
	Engine                                                          string
	Logger                                                          *slog.Logger
}

Options configures node identity, its pinned control-plane connection and local storage.

func OptionsFromEnv 

func OptionsFromEnv() (Options, error)

OptionsFromEnv loads the member configuration injected by the infrastructure backend.

type ProcessSpec 

type ProcessSpec struct {
	Binary    string
	Args, Env []string
	Dir       string
	// StopSignal defaults to SIGTERM. Engines may select another graceful
	// shutdown mode, such as PostgreSQL's SIGINT fast shutdown.
	StopSignal syscall.Signal
	// StopTimeout optionally increases the shutdown checkpoint budget.
	StopTimeout time.Duration
}

ProcessSpec describes a supervised executable, not a remote execution request. Engine processes start from a minimal environment (PATH, LANG, LC_ALL, TZ) plus Env; they never inherit the agent's environment or credentials.

type ShutdownBudgetEngine added in v0.2.0 

type ShutdownBudgetEngine interface {
	ShutdownBudget() time.Duration
}

ShutdownBudgetEngine optionally reserves more than the default four seconds for native session draining. The agent caps this at 45 seconds to leave time for dependency-ordered child shutdown within its 60-second total budget.

type ShutdownEngine added in v0.2.0 

type ShutdownEngine interface {
	Shutdown(context.Context, *Node) error
}

ShutdownEngine optionally hands off leadership before the supervisor signals children. The context is independent of the canceled runtime context. Engines must not wait for control-plane publication. An unsuccessful handoff never skips the normal dependency-ordered shutdown.

Source Files

View all Source files

Directories

Path Synopsis
Package datamcp supervises private, authenticated data MCP upstreams.
 Package datamcp supervises private, authenticated data MCP upstreams.
Package elastic renders and supervises secured Elastic Stack node processes.
 Package elastic renders and supervises secured Elastic Stack node processes.
Package keycloak supervises the native Keycloak distribution.
 Package keycloak supervises the native Keycloak distribution.
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
 SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
Package neo4j supervises a single native Neo4j Community server JVM.
 Package neo4j supervises a single native Neo4j Community server JVM.
The member configuration is cached in plaintext by the shared agent.
 The member configuration is cached in plaintext by the shared agent.
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
 SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
Package rabbitmq renders and supervises a RabbitMQ member using the shared agent.Engine protocol.
 Package rabbitmq renders and supervises a RabbitMQ member using the shared agent.Engine protocol.
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
 SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
gateway
Package gateway renders a self-contained Envoy 1.39 bootstrap.
 Package gateway renders a self-contained Envoy 1.39 bootstrap.
initsql
Package initsql owns the curated Supabase prerequisites on PostgreSQL 17.
 Package initsql owns the curated Supabase prerequisites on PostgreSQL 17.
logship
Package logship pushes bounded batches of supervised process logs to a private Vector HTTP source.
 Package logship pushes bounded batches of supervised process logs to a private Vector HTTP source.
Package temporal supervises native Temporal server roles and the Web UI.
 Package temporal supervises native Temporal server roles and the Web UI.

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.