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

engine

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

Documentation

Overview

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

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

Index

Constants

View Source 
const (
	DataAccessReadUser      = "karakoram-mcp-ro"
	DataAccessReadWriteUser = "karakoram-mcp-rw"
)

Data-access system user names shared by every engine.

View Source 
const (
	ArtifactName   = "karakoram.tar.gz"
	ArtifactBinary = "karakoram"
)

Release archive produced by ArtifactSource.

View Source 
const (
	DefaultReadinessTimeout = 300 * time.Second
	ReadinessRetryPeriod    = 10 * time.Second
)

Default readiness timings for member agents.

View Source 
const DataDirVariable = "KARAKORAM_DATA_DIR"

DataDirVariable records a runtime's data directory. On a runtime with a volume it is also mount evidence: it equals Layout.VolumePath(volume).

View Source 
const MaxPlatformRetryDuration = 30 * 24 * time.Hour

MaxPlatformRetryDuration is the longest durable engine retry schedule honored, including external Retry-After resets. It is deliberately independent of the ten-minute exponential backoff ceiling.

View Source 
const ObservationSweepTimeout = 5 * time.Second

A sweep gets five seconds and one immediate retry. Never carry a failed sample across cycles to suppress flapping: only a successful fresh retry may restore readiness. A stalled reconciliation cannot extend the readiness lease.

View Source 
const ObservationTimeout = 4 * time.Second

ObservationTimeout includes cold namespace/TLS setup and the native response. Keep headroom inside the sweep without extending the persisted readiness lease.

View Source 
const OwnerVariable = "KARAKORAM_OWNER"

OwnerVariable is the non-sensitive ownership marker written on every member service. Tokens without sudo mode can read it, unlike the agent token secret.

View Source 
const ReadinessInterval = 5 * time.Second
View Source 
const ReadinessMaxAge = ReadinessInterval + 2*ObservationSweepTimeout

Variables

View Source 
var (
	ErrNotFound     = errors.New("not found")
	ErrNotSupported = errors.New("not supported for this cluster")
	ErrConflict     = errors.New("conflict")
	ErrInvalid      = errors.New("invalid request")
	ErrUnavailable  = errors.New("temporarily unavailable")
)

Sentinel errors providers return so the API layer can map them to HTTP status codes (ErrNotFound → 404, ErrNotSupported and ErrConflict → 409, ErrInvalid → 400, ErrUnavailable → 503). Wrap them with fmt.Errorf("...: %w", err) for context.

Functions

func AdvanceUnplacedRetirement added in v0.2.0 

func AdvanceUnplacedRetirement(ctx context.Context, rc *Context, q *UnplacedRetirement, name, id, volume, volumeID string) (bool, error)

AdvanceUnplacedRetirement never deploys/restarts or creates storage. One step either observes an exact deletion or submits one, and its handle survives CP restart. Volume deletion follows authoritative logical runtime absence.

func ApplyAgentDiagnostic added in v0.2.0 

func ApplyAgentDiagnostic(member *domain.MemberStatus, diagnostic string)

ApplyAgentDiagnostic keeps engine configuration failures in control-plane health, not platform deployment readiness. A running old process must not hide an Apply failure or make a member/cluster Ready.

func ApplyDeploymentResourceRollback added in v0.2.0 

func ApplyDeploymentResourceRollback(err error, applied *infra.Resources) bool

ApplyDeploymentResourceRollback restores the provider's applied-resource view from durable conditional-resize failure evidence, including failures observed only after a later poll or control-plane restart.

func ApplyDeploymentStatus added in v0.2.0 

func ApplyDeploymentStatus(rc *Context, status *domain.ClusterStatus)

ApplyDeploymentStatus preserves durable fences across provider-owned health snapshots and exposes each terminal member without hiding other observations.

func ApplyInitialDataSourceStatus added in v0.2.0 

func ApplyInitialDataSourceStatus(p Provider, c *domain.Cluster, status *domain.ClusterStatus) error

ApplyInitialDataSourceStatus prevents an empty but healthy target from being published as Ready after supersession, cancellation or control-plane restart.

func ApplyProcessDiagnostics added in v0.2.0 

func ApplyProcessDiagnostics(member *domain.MemberStatus, processes map[string]agentapi.ProcessStatus, instance string, at time.Time) []domain.Condition

ApplyProcessDiagnostics projects supervised child failures independently of agent reachability and observed database role. Call after native observations so they cannot hide a paused child. An empty instance denotes the logical member observation; pinned observations should supply their instance ID. The caller owns aggregation of the returned conditions for the current sweep.

func ApplyRuntimeRecoveryStatus added in v0.2.0 

func ApplyRuntimeRecoveryStatus(status *domain.ClusterStatus, member, volume string, q RuntimeRecovery, now time.Time)

ApplyRuntimeRecoveryStatus keeps data loss visible while a safe replacement is queued or waiting for quorum. It cannot turn a cluster Ready.

func CheckCapabilities added in v0.2.0 

func CheckCapabilities(p Provider, spec domain.ClusterSpec, backend string, have infra.Capabilities) error

CheckCapabilities rejects a spec that needs capabilities the backend lacks, so a cluster that could never converge is refused at admission. The error wraps ErrNotSupported and names the missing capabilities.

func CheckDiskGrowthUpdate added in v0.4.1 

func CheckDiskGrowthUpdate(previous, next domain.ClusterSpec, backend string, have infra.Capabilities) error

CheckDiskGrowthUpdate checks transitions, not initial sizing: creating a new component or adding replicas does not grow an existing volume.

func CheckExposureSupport added in v0.2.0 

func CheckExposureSupport(ctx context.Context, backend infra.Backend, exposure domain.Exposure) (domain.Condition, error)

CheckExposureSupport refuses only a positively unsupported public IP family. Unknown capability does not change admission or convergence behavior.

func CleanupSupersedesDeployment added in v0.2.0 

func CleanupSupersedesDeployment(backend infra.Backend, op infra.Op) bool

CleanupSupersedesDeployment discards only runtime mutation readiness waits, and only when deletion itself provides the backend's durable mutation fence. Import outcomes and deletion operations must always be resolved normally.

func ComponentInstancesHealthy added in v0.2.0 

func ComponentInstancesHealthy(ctx context.Context, rc *Context, member string, replicas int, configVersion int64, probe ComponentProbe, observe ...func(string, agentapi.Status)) (bool, error)

ComponentInstancesHealthy requires fresh application and configuration observations from every live instance, not a sample of logical service DNS. At least replicas live instances must exist; extra live rollout instances must also pass. A false native probe is attributed to its individual instance. The caller owns probe timeouts and can return a credential-free native reason.

func ComponentObservedInstancesHealthy added in v0.2.0 

func ComponentObservedInstancesHealthy(ctx context.Context, rc *Context, member string, replicas int, configVersion int64, inventory InstanceInventory, probe ComponentProbe, observe ...func(string, agentapi.Status)) (bool, error)

ComponentObservedInstancesHealthy applies the same configuration/native checks to this sweep's inventory, with bounded concurrent instance probes.

func ConfirmedVolumeLoss added in v0.2.0 

func ConfirmedVolumeLoss(err error, volume, serviceID string) bool

ConfirmedVolumeLoss requires an owned logical incarnation. Generic conflicts, inaccessible storage and foreign identities never authorize replacement.

func CurrentAgentBuild added in v0.4.0 

func CurrentAgentBuild() domain.AgentBuild

CurrentAgentBuild is the executable deployed by this control plane.

func DataAccessLevels added in v0.3.0 

func DataAccessLevels(c *domain.Cluster) (read, readWrite bool)

DataAccessLevels reports which data-access identities c needs. Providers provision exactly these in Sync and remove the others (dropping the database user and its secret). Features other than the data MCP endpoint that need the identities extend this single condition.

func DataAccessUser added in v0.3.0 

func DataAccessUser(l DataAccessLevel) string

DataAccessUser returns the logical system user name for l (the name used by system-user listing and rotation). Engines whose identifier rules differ map it to their own username, reported in DataAccessCredentials.Username and domain.SystemUser.Username.

func Deploy added in v0.2.0 

func Deploy(ctx context.Context, rc *Context, hostname string, spec infra.RuntimeSpec) (infra.Op, error)

Deploy ships the release artifact with spec to hostname.

func DeploymentBlocked added in v0.2.0 

func DeploymentBlocked(rc *Context, name string, spec infra.RuntimeSpec) bool

DeploymentBlocked fences the same desired runtime until an operator advances the durable cluster epoch. A different desired runtime has its own budget.

func DescribePlacement added in v0.4.0 

func DescribePlacement(groups map[string][]string, authoritative bool) domain.Placement

DescribePlacement classifies groups from one evidence source. Callers must use backend groups exclusively when Placement is supported, otherwise fingerprints.

func EnsureOwnerMarker added in v0.1.1 

func EnsureOwnerMarker(ctx context.Context, b infra.Backend, s *infra.Service, agentToken, cluster, member string) error

EnsureOwnerMarker records the non-sensitive marker on a service whose ownership was proven by other evidence (recorded ID, own import, readable legacy secret), so later checks work without reading sensitive values.

func FreshStatus added in v0.2.0 

func FreshStatus(status domain.ClusterStatus, at time.Time) domain.ClusterStatus

FreshStatus applies a lease to a persisted observation, including legacy snapshots with no sample timestamp. Transition times are not sample times.

func HasOwnership added in v0.1.1 

func HasOwnership(s *infra.Service, agentToken, cluster, member string) bool

HasOwnership reports whether a service carries member ownership evidence: its non-sensitive marker, or the legacy agent-token secret when the token can read sensitive values. Masked values are absent from Ownership.

func ImportedServiceID added in v0.1.1 

func ImportedServiceID(op infra.Op, st infra.OpState, s *infra.Service) string

ImportedServiceID returns the ID a Karakoram import created for hostname, if observed s is that service. The IDs come from the import response recorded in the operation or from its own platform processes, never from the hostname.

func InitialDataSourceUnproven added in v0.2.0 

func InitialDataSourceUnproven(c *domain.Cluster) bool

InitialDataSourceUnproven marks only a legacy superseded create without any native restore receipt. Runtime management must continue, but initial data recovery must never be replayed against a database that may now be in use.

func Invalid 

func Invalid(format string, args ...any) error

Invalid returns a ValidationError with a formatted, caller-facing message.

func InvalidField 

func InvalidField(field, reason, format string, args ...any) error

InvalidField returns a ValidationError for one request field. The message should name the field so it reads well without the details object.

func MemberNeedsAgentUpgrade added in v0.4.0 

func MemberNeedsAgentUpgrade(member domain.MemberStatus, target AgentUpgradePayload) bool

MemberNeedsAgentUpgrade selects a rollout candidate. Providers must journal completion per member: includeCurrent selects every member initially, but a checkpoint's completed members must never be selected again.

func MemberResources added in v0.2.0 

func MemberResources(agent *agentapi.ContainerResources, autoscaling *domain.Resources) *domain.ObservedResources

MemberResources returns the CPU, memory, and root disk a member container currently has. Values the member agent read from its cgroup and filesystem in a successful status call win; each value the agent did not report (an unreachable agent, or one that predates the reading) falls back to the service's effective vertical autoscaling: start CPU or minimum CPU, minimum RAM, and minimum root disk. Zerops container records are not used: they keep creation-time values after vertical scaling. Nil when neither source is known.

func MountsVolume added in v0.2.0 

func MountsVolume(b infra.Backend, runtime *infra.Service, volume string) bool

MountsVolume reports whether an observed runtime records exactly volume's mount path as its data directory.

func ObserveAgentStatus added in v0.2.0 

func ObserveAgentStatus(ctx context.Context, client *agentapi.Client, engineName, member string) (agentapi.Status, error)

ObserveAgentStatus bounds a short configuration/process observation without shortening the caller's subsequent administration or engine operations.

func ObserveAgentVersions added in v0.4.0 

func ObserveAgentVersions(status *domain.ClusterStatus, target domain.AgentBuild, at time.Time)

ObserveAgentVersions adds informational fleet inventory, never changing phase, member health, or readiness conditions. Unreachable/stopped and legacy agents are unknown; display versions do not replace executable identity comparisons.

func ObservePlacement added in v0.4.0 

func ObservePlacement(status *domain.ClusterStatus, authoritative bool)

ObservePlacement rebuilds grouping from the same member evidence returned to clients, including unknown members so partial evidence cannot certify HA.

func ObserveRetiringService added in v0.2.0 

func ObserveRetiringService(ctx context.Context, b infra.Backend, hostname, recordedID, volume, volumeID string, volumeLost bool) (*infra.Service, error)

ObserveRetiringService preserves a confirmed original service observation despite physical storage loss. This is only for existing native retirement workflows: it does not prove a runtime stopped or permit fresh deployment.

func ObserveRuntimeStops added in v0.2.0 

func ObserveRuntimeStops(ctx context.Context, rc *Context, status *domain.ClusterStatus, recordEvents bool) error

ObserveRuntimeStops adds current platform shutdown diagnostics without treating elapsed time as fencing proof. It also runs during deletion, when ordinary provider health sweeps are intentionally skipped.

func ObserveStatus added in v0.2.0 

func ObserveStatus(ctx context.Context, p Provider, rc *Context) (domain.ClusterStatus, error)

ObserveStatus obtains a bounded fresh snapshot independently of recovery work. Providers must honor context cancellation; read-only probes must never inherit the much longer engine-mutation timeout.

func ObserveVolumeSize added in v0.4.1 

func ObserveVolumeSize(ctx context.Context, b infra.Backend, hostname, id string) (*domain.Resources, error)

ObserveVolumeSize reads the backend's volume record and fences identity reuse. A missing or still-importing record has no acknowledged sizing observation.

func OwnerMarker added in v0.1.1 

func OwnerMarker(agentToken, cluster, member, hostname string) string

OwnerMarker derives a service's ownership marker: an HMAC-SHA256 keyed by the member's random agent token over the cluster, member and service hostname. It reveals nothing about the token and cannot be produced for another service without it; a hostname alone is never ownership evidence.

func OwnerVars added in v0.1.1 

func OwnerVars(agentToken, cluster, member, hostname string) map[string]string

OwnerVars returns the non-sensitive import variables for one member service.

func OwnershipEnv added in v0.2.0 

func OwnershipEnv(cluster, member, token string) map[string]string

OwnershipEnv returns the legacy secret identity variables of a member service.

func PlatformFailureDefinitive added in v0.4.0 

func PlatformFailureDefinitive(err error) bool

PlatformFailureDefinitive reports failures that cannot be resolved by replaying the same platform intent.

func PlatformRetryDelay 

func PlatformRetryDelay(failures int) time.Duration

PlatformRetryDelay backs off safe, re-issuable infrastructure actions from thirty seconds to ten minutes, without limiting the number of attempts.

func PreflightVolumeGrowth added in v0.4.1 

func PreflightVolumeGrowth(ctx context.Context, b infra.Backend, hostname, id string, current, target domain.Resources) (domain.Resources, error)

PreflightVolumeGrowth checks actual backend sizing before disruption. On an incapable backend, refresh stale legacy disk caches only after proving that the requested bounds do not require growth. Other runtime fields are retained.

func PrepareInitialDeploymentResources added in v0.2.0 

func PrepareInitialDeploymentResources(ctx context.Context, rc *Context, name string, spec infra.RuntimeSpec, desired, applied infra.Resources) (infra.Op, bool, error)

PrepareInitialDeploymentResources brings capacity up to date before an imported member's already-authorized ordinary deployment/re-arm. A raced bootstrap may have initialized storage before stopping; this is not another never-placed shortcut. The normal stop/deploy lifecycle and durable failure fence apply. The provider tracks the resource operation before deploying.

func PublicHTTPS added in v0.2.0 

func PublicHTTPS(b infra.Backend) (infra.SubdomainAccess, error)

PublicHTTPS returns the backend's public HTTPS routing, or ErrNotSupported.

func ReconcileStatelessComponent added in v0.2.0 

func ReconcileStatelessComponent(ctx context.Context, def ComponentDef, current ComponentRuntime, desired domain.ComponentSpec, cb ComponentCallbacks) (bool, error)

ReconcileStatelessComponent drives enable (import, deploy, readiness, scale, optional resize) and disable (delete). It returns handled while a transition or readiness wait owns this reconciliation pass. Stateful definitions require engine-specific lifecycle logic and are rejected rather than losing volumes.

func RecordDeploymentExhausted added in v0.2.0 

func RecordDeploymentExhausted(ctx context.Context, rc *Context, name string, spec infra.RuntimeSpec, err error) error

RecordDeploymentExhausted retains terminal evidence and emits one event per member, desired runtime and epoch. Callers must preserve this state on errors.

func RecoverLostVolume added in v0.2.0 

func RecoverLostVolume(ctx context.Context, rc *Context, member, volume, volumeID string, replicated bool) error

RecoverLostVolume hands irreversible storage loss to the existing serialized, engine-native replacement workflow. A deterministic ID makes queueing crash-safe. The workflow retains its quorum, data-transfer and retirement safety checks.

func RequireDiskGrowth added in v0.2.0 

func RequireDiskGrowth(b infra.Backend) error

RequireDiskGrowth refuses growing a volume on a backend that cannot.

func RequirePublicTCP added in v0.2.0 

func RequirePublicTCP(b infra.Backend, exposure domain.Exposure) error

RequirePublicTCP refuses public TCP exposure the backend cannot provide or whose allowlist it cannot enforce.

func RequiredCapabilities added in v0.2.0 

func RequiredCapabilities(spec domain.ClusterSpec) []string

RequiredCapabilities returns the backend capabilities a cluster spec needs regardless of its engine: public TCP exposure, its allowlist, and dedicated CPU for any component.

func ResizeUnplacedDeployment added in v0.2.0 

func ResizeUnplacedDeployment(ctx context.Context, rc *Context, name string, desired infra.Resources, applied *infra.Resources, op *infra.Op) (bool, error)

ResizeUnplacedDeployment lets corrected capacity supersede a placement-blocked rollout before waiting for it. Initial deployment requires no allocation history; a stateless resource rollout may retain serving predecessors but must not have allocated its new version. The backend owns that distinction and its fences. The replacement receipt and target resources must be persisted together.

func ResumeImportPlan added in v0.2.0 

func ResumeImportPlan(ctx context.Context, rc *Context, plan *ImportPlan, member, token string) (*infra.Op, error)

ResumeImportPlan finishes backend-owned setup before operation polling or cleanup can wait on, or mutate, an incomplete logical reservation.

func RuntimeServiceSpec added in v0.2.0 

func RuntimeServiceSpec(l infra.Layout, m MemberService) infra.ServiceSpec

RuntimeServiceSpec returns the import spec of a member runtime. Its secret data-directory variable is the mount evidence checked by MountsVolume.

func RuntimeUnplaced added in v0.2.0 

func RuntimeUnplaced(ctx context.Context, rc *Context, name string) (bool, error)

RuntimeUnplaced is only an admission check for a provider-proven uninitialized member. Empty current allocations alone never prove an existing replica's data disposable. Reads fail closed; the subsequent delete supplies mutation fencing.

func RuntimeVolumeIdentity added in v0.2.0 

func RuntimeVolumeIdentity(uid, member, volume, volumeID string, initialized bool) *agentapi.VolumeIdentity

RuntimeVolumeIdentity publishes the CP's initialized-data receipt. Empty legacy service IDs are resolved by ownership reconciliation before opting in.

func StatelessReadiness added in v0.2.0 

func StatelessReadiness(rc *Context, member string, decision **bool, nativeArgs ...string) []string

StatelessReadiness freezes a deployment's probe choice until the engine has observed native convergence and clears decision. Fresh, healthy dependencies retain overlap-until-native-ready for rolling frontend replacements. Initial creation and dependency recovery must not wait on those dependencies while holding a platform deployment slot.

func UnknownObservation added in v0.2.0 

func UnknownObservation(status domain.ClusterStatus, at time.Time, reason string) domain.ClusterStatus

UnknownObservation retains diagnostics, but withdraws positive availability claims. Clone slices because API projections must not mutate stored snapshots.

func UnverifiedOwnership added in v0.1.1 

func UnverifiedOwnership(s *infra.Service) error

UnverifiedOwnership is the conflict for a service without ownership evidence. When legacy evidence exists only as masked sensitive values, it tells the operator how to recover instead of retrying silently.

func ValidElasticsearchDataIndexPattern added in v0.3.0 

func ValidElasticsearchDataIndexPattern(pattern string) bool

ValidElasticsearchDataIndexPattern validates the deliberately narrow pattern syntax shared by Elasticsearch data MCP admission and native tool routing. Only lowercase ASCII letters, digits, underscores, dots, hyphens and the wildcard characters '*' and '?' are allowed. Patterns must be 1–255 bytes and cannot start with a dot, underscore or hyphen; '_all' is therefore excluded.

func VisitLiveInstances added in v0.2.0 

func VisitLiveInstances(ctx context.Context, rc *Context, member string, visit func(*agentapi.Client) (bool, error)) (bool, int, error)

VisitLiveInstances obtains fresh infrastructure inventory and visits every ACTIVE/RUNNING instance using a pinned client that retains the logical member's TLS and bearer identity. It prefers the backend's private address family, then an individual hostname; missing or logical-service-only addresses fail closed. The visitor must not retain its client: it is closed after each call.

The results are the conjunction of visitor acknowledgements, the number of live instances, and any inventory/address/probe errors. Empty inventory (or a separately confirmed absent service) returns true with count zero; readiness callers must also require a positive count. No acknowledgements are cached, so stopped/disappeared instances are excluded and replacements are visited anew.

func VisitLiveInstancesConcurrent added in v0.2.0 

func VisitLiveInstancesConcurrent(ctx context.Context, rc *Context, member string, visit func(*agentapi.Client) (bool, error)) (bool, int, error)

VisitLiveInstancesConcurrent has the live-inventory contract of VisitLiveInstances, but visits at most eight instances concurrently. The visitor must be concurrency-safe and must honor the supplied context.

func VisitLiveInstancesWithIdentity added in v0.2.0 

func VisitLiveInstancesWithIdentity(ctx context.Context, rc *Context, member string, visit func(*agentapi.Client, string) (bool, error)) (bool, int, error)

VisitLiveInstancesWithIdentity collects fresh inventory and visits each pinned instance sequentially, passing the platform instance ID to the visitor.

func VisitObservedInstances added in v0.2.0 

func VisitObservedInstances(ctx context.Context, rc *Context, member string, inventory InstanceInventory, visit func(*agentapi.Client) (bool, error)) (bool, int, error)

VisitObservedInstances visits a freshly collected inventory without reading the platform again. At most eight pinned instance probes run concurrently. The inventory belongs to the current sweep; it must never be carried forward.

func VisitObservedInstancesWithIdentity added in v0.2.0 

func VisitObservedInstancesWithIdentity(ctx context.Context, rc *Context, member string, inventory InstanceInventory, visit func(*agentapi.Client, string) (bool, error)) (bool, int, error)

VisitObservedInstancesWithIdentity is VisitObservedInstances with the platform instance ID passed to each visitor, for instance-specific diagnostics.

func VolumeAdmissionBaseline added in v0.4.1 

func VolumeAdmissionBaseline(ctx context.Context, p Provider, c *domain.Cluster, target domain.ClusterSpec, b infra.Backend) (*domain.Cluster, error)

VolumeAdmissionBaseline checks growth against EACH existing volume, then uses the largest acknowledged bounds as the shrink floor. Mixed-size volumes must not turn an unsupported resize of their smaller peer into an accepted no-op.

func VolumeServiceSpec added in v0.2.0 

func VolumeServiceSpec(cluster, member, volume, token string, r domain.Resources) infra.ServiceSpec

VolumeServiceSpec returns the import spec of a member's persistent volume sized by the disk bounds of r, spread across the cluster's placement group.

Types

type AgentConfigSource 

type AgentConfigSource interface {
	MemberConfig(ctx context.Context, rc *Context, member string) (agentapi.MemberConfig, error)
}

AgentConfigSource is implemented by providers to render the configuration a node agent pulls from the control plane. member is the member hostname the authenticated agent token belongs to.

type AgentDialer 

type AgentDialer interface {
	Dial(context.Context, domain.ClusterRef, string) (*agentapi.Client, error)
}

AgentDialer constructs authenticated, CA-pinned member clients.

type AgentRuntime added in v0.2.0 

type AgentRuntime struct {
	Cluster, Member string
	// Engine sets KARAKORAM_ENGINE when non-empty.
	Engine        string
	Volume        string
	AgentURL      string
	InternalCAPEM string
	Ports         []infra.Port
	Prepare       []string
	// Env adds engine-specific non-secret variables.
	Env map[string]string
	// ReadinessArgs overrides startup readiness for stateless replacements whose
	// dependencies were healthy when the engine selected this deployment.
	ReadinessArgs []string
	// ReadinessTimeout defaults to DefaultReadinessTimeout.
	ReadinessTimeout time.Duration
}

AgentRuntime describes one member service that runs `karakoram agent`.

func (AgentRuntime) Spec added in v0.2.0 

func (a AgentRuntime) Spec(l infra.Layout) infra.RuntimeSpec

Spec returns the neutral runtime description of a member agent: the release binary started as `karakoram agent`, its data directory on the mounted volume, a readiness probe and stop-before-start replacement.

type AgentUpgradePayload added in v0.4.0 

type AgentUpgradePayload struct {
	IncludeCurrent bool   `json:"includeCurrent"`
	TargetBuild    string `json:"targetBuild"`
	TargetVersion  string `json:"targetVersion"`
}

AgentUpgradePayload freezes the enqueue target. Providers must copy this target into their durable rolling checkpoint before their first disruption, preserve the engine version/runtime/volume, and use normal Deploy admission and native gates.

func AgentUpgradeTarget added in v0.4.0 

func AgentUpgradeTarget(op *domain.Operation) (AgentUpgradePayload, error)

AgentUpgradeTarget decodes the immutable enqueue target; it never substitutes the current CP build after a restart. A different running build must not deploy its bytes under the frozen identity: providers should fail before disruption.

type ArtifactSource 

type ArtifactSource interface {
	Open(context.Context) (io.ReadCloser, error)
}

ArtifactSource opens a stream of the deployable agent tar.gz artifact.

type BackendValidator added in v0.4.0 

type BackendValidator interface {
	ValidateBackend(infra.Backend) error
}

BackendValidator is implemented by providers with admission requirements on the backend's runtime contract, beyond its optional capability flags. A nil backend means the namespace backend could not be resolved.

type CapabilityRequirer added in v0.2.0 

type CapabilityRequirer interface {
	RequiredCapabilities(domain.ClusterSpec) []string
}

CapabilityRequirer is implemented by providers whose cluster specs need optional backend capabilities beyond the engine-neutral ones returned by RequiredCapabilities (e.g. public HTTPS for a management UI, horizontal scaling for stateless routers). Names are infra capability names.

type Clock 

type Clock interface{ Now() time.Time }

Clock supplies timestamps and supports deterministic tests.

type ClusterStore 

type ClusterStore interface {
	GetCluster(context.Context, domain.ClusterRef) (*domain.Cluster, error)
	ListClusters(context.Context, string) ([]domain.Cluster, error)
	GetBackupStorage(context.Context, string, string) (*domain.BackupStorage, error)
	GetBackup(context.Context, domain.ClusterRef, string) (*domain.Backup, error)
	ListBackups(context.Context, domain.ClusterRef) ([]domain.Backup, error)
	UpdateBackup(context.Context, *domain.Backup) error
	DeleteBackup(context.Context, domain.ClusterRef, string) error
	CreateBackup(context.Context, *domain.Backup) error
	CreateRestore(context.Context, *domain.Restore) error
	// EnqueueOperation durably queues an operation for the cluster's worker.
	EnqueueOperation(context.Context, *domain.Operation) error
	// EnqueueBackup atomically creates a Pending backup record and its backup operation.
	EnqueueBackup(context.Context, *domain.Backup, *domain.Operation) error
	// EnqueueRestore atomically creates a Pending restore record and its restore operation.
	EnqueueRestore(context.Context, *domain.Restore, *domain.Operation) error
	// ClaimInitialDataSource atomically closes provisioning-amendment admission
	// before a provider executes its first native initial import.
	ClaimInitialDataSource(context.Context, domain.ClusterRef) error
	GetOperation(context.Context, string) (*domain.Operation, error)
	GetRestore(context.Context, domain.ClusterRef, string) (*domain.Restore, error)
	UpdateRestore(context.Context, *domain.Restore) error
	ListRetainedVolumes(context.Context, domain.ClusterRef) ([]domain.RetainedVolume, error)
	CreateRetainedVolume(context.Context, *domain.RetainedVolume) error
	DeleteRetainedVolume(context.Context, domain.ClusterRef, string) error
	PutOrphanedVolume(context.Context, *domain.OrphanedVolume) error
	GetOrphanedVolume(context.Context, string, string) (*domain.OrphanedVolume, error)
	ListOrphanedVolumes(context.Context, string) ([]domain.OrphanedVolume, error)
	DeleteOrphanedVolume(context.Context, string, string) error
}

ClusterStore exposes the inventory and cluster reads needed by a provider.

type ComponentCallbacks added in v0.2.0 

type ComponentCallbacks struct {
	Import     func(context.Context) error
	Deploy     func(context.Context) error
	AwaitReady func(context.Context) error
	Scale      func(context.Context, int) error
	Resize     func(context.Context, domain.Resources) error
	Delete     func(context.Context) error
}

ComponentCallbacks bind lifecycle actions to an engine's existing operation tracking. Import may allocate its service identity first. Deploy supplies the component-specific RuntimeSpec. AwaitReady must persist Joined once ready; its pass always ends, including while waiting. Resize is optional for engines that reconcile resources separately. Callbacks persist all resulting stages, applied values and operation handles themselves. Each call performs at most one callback, allowing asynchronous backends and restarts.

type ComponentChange added in v0.2.0 

type ComponentChange struct {
	Name   string
	Kind   ComponentChangeKind
	Before domain.ComponentSpec
	After  domain.ComponentSpec
}

ComponentChange describes desired intent, not an operation handle. Engines retain their own durable stages and decide when stateful changes are safe.

type ComponentChangeKind added in v0.2.0 

type ComponentChangeKind string

ComponentChangeKind identifies an infrastructure transition. Enable and Disable subsume scaling/resizing; an existing enabled component may need both Scale and Resize, emitted in that order. 

const (
	ComponentEnable  ComponentChangeKind = "enable"
	ComponentDisable ComponentChangeKind = "disable"
	ComponentScale   ComponentChangeKind = "scale"
	ComponentResize  ComponentChangeKind = "resize"
)

type ComponentDef added in v0.2.0 

type ComponentDef struct {
	Name              string
	DisplayName       string
	Stateful          bool
	Defaults          domain.ComponentSpec
	MinReplicas       int      // Lower bound when enabled; zero means one.
	MaxReplicas       int      // Upper bound when enabled; must be positive.
	Requires          []string // Names in this set that must also be enabled.
	PublicHTTPS       bool
	ValidateResources func(domain.Resources) error
}

ComponentDef declares an optional per-cluster service stored in Components.Extra. A zero replica count disables it. Stateful components participate in defaults, validation and planning, but their volume lifecycle remains engine-owned. Definitions are ordered: ComponentSet preserves declaration order in plans, enabled names and reconciliation, so dependencies should be declared first. PublicHTTPS describes eligibility, not whether public access is requested. ValidateResources optionally adds engine-specific constraints to the common finite, ordered CPU/RAM/disk bounds; it runs before the common checks. A future engine can declare auth, rest, realtime, storage and studio here without introducing new domain fields or backend-specific lifecycle code.

type ComponentProbe added in v0.2.0 

type ComponentProbe struct {
	Ready  func(*agentapi.Client) (bool, error)
	Failed func(*agentapi.Client) error
}

ComponentProbe enriches failed-child observations without relaxing readiness. Failed is optional and runs only after configuration and pause/maintenance gates.

type ComponentRuntime added in v0.2.0 

type ComponentRuntime struct {
	Exists            bool
	Stage             ComponentStage
	Replicas          int
	Resources         domain.Resources
	HorizontalScaling bool
}

ComponentRuntime is a stateless service's currently observed lifecycle state. Replicas and Resources are the applied values, not desired values. HorizontalScaling reports whether the backend permits multiple containers.

type ComponentSet added in v0.2.0 

type ComponentSet []ComponentDef

ComponentSet is an engine's ordered catalog of optional components. Treat its definitions as immutable after construction. Engine/configServer/router are not managed here; only Extra entries are defaulted and validated.

func (ComponentSet) ApplyDefaults added in v0.2.0 

func (s ComponentSet) ApplyDefaults(c *domain.Components)

ApplyDefaults fills missing resource fields and applies replica defaults only to absent entries. A present entry with zero replicas explicitly disables the component. Unknown entries are retained for Validate to report.

func (ComponentSet) Enabled added in v0.2.0 

func (s ComponentSet) Enabled(c domain.Components) []string

Enabled returns enabled Extra component names in declaration order.

func (ComponentSet) Info added in v0.2.0 

func (s ComponentSet) Info() map[string]domain.ComponentInfo

Info returns independent entries suitable for TopologyInfo.Components. Zero remains the catalog minimum because optional components can be disabled.

func (ComponentSet) Plan added in v0.2.0 

func (s ComponentSet) Plan(observed map[string]domain.ComponentSpec, desired domain.Components) []ComponentChange

Plan compares observed replicas AND resources with a defaulted desired spec. The observed map uses ComponentSpec rather than just replica counts so resize decisions are based on actual applied resources, not guessed from defaults. Missing observations mean absent; missing desired entries mean disabled.

func (ComponentSet) Validate added in v0.2.0 

func (s ComponentSet) Validate(c domain.Components) error

Validate rejects unknown entries, invalid enabled replica counts, missing dependencies and invalid resources (including explicitly disabled entries). Call ApplyDefaults first when accepting a partial user specification.

type ComponentStage added in v0.2.0 

type ComponentStage string

ComponentStage describes the engine's durable provisioning observation. Joined means application readiness passed, not merely that deployment ended. 

const (
	ComponentPlanned  ComponentStage = "planned"
	ComponentImported ComponentStage = "imported"
	ComponentDeployed ComponentStage = "deployed"
	ComponentJoined   ComponentStage = "joined"
)

type Context 

type Context struct {
	Namespace string
	Dialer    ContextDialer
	AgentURL  string
	Cluster   *domain.Cluster
	// AgentConfigCapabilities applies only to the authenticated config pull
	// being served. Unknown/absent capabilities must retain the legacy schema.
	AgentConfigCapabilities []string
	// Operation is set only while an imperative operation owns this invocation.
	Operation *domain.Operation
	Backend   infra.Backend
	Secrets   SecretStore
	Store     ClusterStore
	Events    Recorder
	Agents    AgentDialer
	Artifact  ArtifactSource
	Logger    *slog.Logger
	Clock     Clock
	// ObservationEpoch is unique per CP process and shared with the API.
	// Availability embeddings must supply the same nonempty value to both;
	// timestamps alone cannot distinguish old snapshots after clock steps.
	ObservationEpoch string
	// AvailabilityOnly excludes inventory adoption/reconciliation from Status.
	// An imperative operation may temporarily own a different native backup
	// destination; probing availability must not reinterpret that inventory.
	AvailabilityOnly bool
	// DeploymentWait retains non-terminal platform backpressure for status.
	DeploymentWait       string
	DeploymentWaitReason string
	DeploymentWaitKey    string
	// SyncWait describes the current generation barrier, independently of health.
	// Providers replace it on every attempt; it is not an availability condition.
	SyncWait string
	// contains filtered or unexported fields
}

Context contains the dependencies and mutable state for one provider invocation.

func (*Context) DisruptionAllowed added in v0.4.0 

func (rc *Context) DisruptionAllowed() (allowed bool, nextStart time.Time)

DisruptionAllowed checks permission to start a NEW member disruption. Providers call it before crossing the stop/drain boundary, never to pause a member already beyond that boundary. Healing, scale-out, leaf certificates with at most seven days remaining, and agent transport certificate renewal are exempt: their paths must not call this gate. A desired-state override applies only to its generation; an imperative override belongs only to the current operation.

func (*Context) WaitForWindow added in v0.4.0 

func (rc *Context) WaitForWindow() Result

WaitForWindow publishes MaintenanceWindow and returns a bounded requeue delay. Call before a new disruption; a zero RequeueAfter means work may proceed. Operation providers can return OpResult{RequeueAfter: result.RequeueAfter}.

func (*Context) WaitingForMaintenance added in v0.4.0 

func (rc *Context) WaitingForMaintenance(op *domain.Operation) bool

WaitingForMaintenance reports a wait observed for this operation during the current invocation, never a persisted condition left by desired-state work.

type ContextDialer 

type ContextDialer interface {
	DialContext(ctx context.Context, network, addr string) (net.Conn, error)
}

ContextDialer routes connections through a namespace's network.

type DataAccessCredentials added in v0.3.0 

type DataAccessCredentials struct {
	Username string
	Password string
	Hosts    []string
	// Database is the default database for engines that need one.
	Database string
	// URI is an engine-native connection string including credentials
	// (mongodb://, postgresql://, https:// for Elasticsearch and the
	// RabbitMQ management API).
	URI   string
	TLS   bool
	CAPEM []byte
}

DataAccessCredentials describe how a control-plane component reaches a cluster's data endpoint with a Karakoram-managed data-access identity. Hosts are logical host:port addresses dialled through Context.Dialer (nil means the namespace network is directly reachable). Values are secret and must never be returned through an API or logged.

type DataAccessLevel added in v0.3.0 

type DataAccessLevel string

DataAccessLevel selects a least-privilege database identity managed by Karakoram for tools that read (or explicitly write) application data. 

const (
	// DataAccessRead is a read-only identity enforced by the database itself.
	DataAccessRead DataAccessLevel = "read"
	// DataAccessReadWrite may change data but never administers users,
	// roles or cluster configuration.
	DataAccessReadWrite DataAccessLevel = "readWrite"
)

func (DataAccessLevel) Valid added in v0.3.0 

func (l DataAccessLevel) Valid() bool

Valid reports whether l is a known level.

type DataAccessProvider added in v0.3.0 

type DataAccessProvider interface {
	DataAccessCredentials(ctx context.Context, rc *Context, level DataAccessLevel) (DataAccessCredentials, error)
}

DataAccessProvider is implemented by providers that provision the read-only and opt-in read-write data-access system users. The read identity always exists while data access is enabled; the read-write identity exists only when the cluster opted into writes.

type DataMcpBackend added in v0.3.0 

type DataMcpBackend struct {
	Kind     DataMcpKind
	Upstream string
}

DataMcpBackend declares the data MCP implementation of an engine. Upstream names the tool manifest (and, for companions, the native artifact) used by the gateway.

type DataMcpKind added in v0.3.0 

type DataMcpKind string

DataMcpKind selects how a cluster's data MCP endpoint is served. 

const (
	// DataMcpCompanion runs a pinned upstream MCP server in a private
	// per-cluster companion service reached through its agent.
	DataMcpCompanion DataMcpKind = "companion"
	// DataMcpNative serves Karakoram's in-process Go tools.
	DataMcpNative DataMcpKind = "native"
)

type DataMcpProvider added in v0.3.0 

type DataMcpProvider interface {
	DataAccessProvider
	DataMcp(c *domain.Cluster) (DataMcpBackend, error)
}

DataMcpProvider is implemented by providers that support spec.dataMcp. DataMcp validates the engine-specific parts of c.Spec.DataMcp (scope entries) and returns the backend; a returned error is an admission error.

type DataPlane 

type DataPlane interface {
	// Connection returns connection details including credentials. Callers
	// enforce the cluster-credentials read permission.
	Connection(ctx context.Context, rc *Context) (domain.ConnectionDetails, error)
	// SystemUsers lists the provider-managed system users (no passwords).
	SystemUsers(ctx context.Context, rc *Context) ([]domain.SystemUser, error)

	ListDatabaseUsers(ctx context.Context, rc *Context) ([]domain.DatabaseUser, error)
	GetDatabaseUser(ctx context.Context, rc *Context, db, name string) (*domain.DatabaseUser, error)
	// CreateDatabaseUser creates an application user. An empty password makes
	// the provider generate one; the effective password is returned once.
	CreateDatabaseUser(ctx context.Context, rc *Context, user domain.DatabaseUser, password string) (string, error)
	// UpdateDatabaseUser replaces roles and, when password is non-empty, the password.
	UpdateDatabaseUser(ctx context.Context, rc *Context, user domain.DatabaseUser, password string) error
	DeleteDatabaseUser(ctx context.Context, rc *Context, db, name string) error

	ListDatabaseRoles(ctx context.Context, rc *Context) ([]domain.DatabaseRole, error)
	GetDatabaseRole(ctx context.Context, rc *Context, db, name string) (*domain.DatabaseRole, error)
	CreateDatabaseRole(ctx context.Context, rc *Context, role domain.DatabaseRole) error
	UpdateDatabaseRole(ctx context.Context, rc *Context, role domain.DatabaseRole) error
	DeleteDatabaseRole(ctx context.Context, rc *Context, db, name string) error

	// Balancer and SetBalancer are only valid for sharded clusters; providers
	// return ErrNotSupported for other topologies.
	Balancer(ctx context.Context, rc *Context) (domain.BalancerStatus, error)
	SetBalancer(ctx context.Context, rc *Context, enabled bool) error

	// PITRWindow returns the current restorable point-in-time windows.
	PITRWindow(ctx context.Context, rc *Context) ([]domain.TimeWindow, error)
	// Placement returns best-effort host placement of the members.
	Placement(ctx context.Context, rc *Context) (domain.Placement, error)
	// MemberLogs returns the last lines of a member process log.
	MemberLogs(ctx context.Context, rc *Context, member, process string, lines int) ([]domain.MemberLogLine, error)
}

DataPlane is implemented by providers for synchronous requests that the API serves directly against a running cluster (as opposed to declarative spec changes, which go through Sync, and long-running actions, which go through RunOperation). Every method receives a fully populated Context for the target cluster.

type DatabasePasswordValidator 

type DatabasePasswordValidator interface {
	ValidateDatabasePassword(string) error
}

DatabasePasswordValidator optionally enforces engine authentication rules. It validates supplied passwords only; omission retains/generates a password.

type ExecutableArtifact 

type ExecutableArtifact struct{}

ExecutableArtifact streams the running control plane binary as a tar.gz named karakoram, matching the runtime deployment command without temporary files.

func (ExecutableArtifact) ArtifactIdentity added in v0.2.0 

func (ExecutableArtifact) ArtifactIdentity() string

ArtifactIdentity supplies a cheap, stable identity without opening or hashing a deployment archive. Custom artifact sources may implement it as well.

func (ExecutableArtifact) Open 

func (ExecutableArtifact) Open(ctx context.Context) (io.ReadCloser, error)

Open streams the current executable as a deployment tar.gz.

type ExposureAdmission added in v0.4.2 

type ExposureAdmission struct {
	Admitted *domain.Exposure `json:"admitted,omitempty"`
}

ExposureAdmission is a durable cluster/component policy receipt, independent of runtime route application. Providers must retain it across runtime loss and suspension and persist Resolve's result before changing platform routes.

func (*ExposureAdmission) Resolve added in v0.4.2 

func (a *ExposureAdmission) Resolve(rc *Context, desired domain.Exposure) (effective domain.Exposure, deferred bool)

Resolve returns the policy that recovery may apply and whether the desired generation remains deferred. Initial provisioning is exempt. Legacy state without a recoverable policy starts private: a lost application receipt is never permission to publish current desired access outside a window. Keep reconciling the returned policy while deferred, but do not acknowledge the desired generation. A successful Resolve must be durably saved before any external mutation; admission is separate from application completion.

func (*ExposureAdmission) Seed added in v0.4.2 

func (a *ExposureAdmission) Seed(applied domain.Exposure)

Seed migrates known previously applied policy, never current desired policy. Call before clearing legacy runtime receipts. It does not replace an existing admission, including when desired state has since changed.

type FCVValidator 

type FCVValidator interface {
	ValidateFCV(context.Context, *Context, string) error
}

FCVValidator optionally checks the accepted version form and deployed members before accepting feature compatibility promotion.

type ImportPlan added in v0.2.0 

type ImportPlan struct {
	RetrySchedule
	Specs   []infra.ServiceSpec `json:"specs"`
	RetryAt time.Time           `json:"retryAt,omitempty"`
}

ImportPlan freezes a backend batch before submission without persisting bearer credentials. The member's sealed token remains stable throughout an import. Callers must return for persistence after creating the plan, before Submit.

func NewImportPlan added in v0.2.0 

func NewImportPlan(specs []infra.ServiceSpec) *ImportPlan

func (*ImportPlan) Services added in v0.2.0 

func (p *ImportPlan) Services(layout infra.Layout, cluster, member, token string) []infra.ServiceSpec

func (*ImportPlan) Submit added in v0.2.0 

func (p *ImportPlan) Submit(ctx context.Context, rc *Context, member, token string) (infra.Op, error)

type InitialDataSourceMigrator added in v0.2.0 

type InitialDataSourceMigrator interface {
	MigrateInitialDataSource(context.Context, *Context) error
}

InitialDataSourceMigrator upgrades validated pre-marker native receipts before historical convergence-tracker retirement is interpreted as an aborted restore. It must not enqueue, replay native work, or infer success from process health.

type InitialDataSourceObserver added in v0.2.0 

type InitialDataSourceObserver interface {
	InitialDataSourceApplied(*domain.Cluster) (bool, error)
}

InitialDataSourceObserver reports durable native restore completion, not process health or the desired generation observed by an earlier operation. A provider supporting dataSource must implement this fail-closed contract.

type InitialDataSourceRecoveryPolicy added in v0.2.0 

type InitialDataSourceRecoveryPolicy interface {
	InitialDataSourceRecoveryPending(*domain.Cluster) (bool, error)
}

InitialDataSourceRecoveryPolicy permits only an already-owned, frozen native recovery journal to progress through Sync after its queue operation retired. Providers must return before ordinary convergence while this policy is true.

type InstanceInventory added in v0.2.0 

type InstanceInventory struct {
	Containers []infra.Container
	Err        error
}

InstanceInventory is one member's infrastructure observation from this sweep. Consumers must not mutate Containers or reuse this sample in another sweep.

func ObserveInstanceInventory added in v0.4.1 

func ObserveInstanceInventory(ctx context.Context, rc *Context, member string) InstanceInventory

ObserveInstanceInventory reads this sweep's instances, distinguishing verified runtime absence from a failed platform read.

type MemberReplacementValidator added in v0.4.0 

type MemberReplacementValidator interface {
	ValidateMemberReplacement(*domain.Cluster, string) error
}

MemberReplacementValidator applies a provider's native replacement target restrictions before admitting either replacement or relocation.

type MemberService added in v0.2.0 

type MemberService struct {
	Cluster, Member, Token string
	// Volume is the member's volume hostname, empty for stateless services.
	Volume     string
	Resources  domain.Resources
	Containers int
}

MemberService describes a member runtime service to import.

type MetricsCatalog 

type MetricsCatalog interface {
	Metrics() []domain.MetricDescriptor
}

MetricsCatalog maps agent exposition metric names to monitoring series.

type Namespaces 

type Namespaces interface {
	Backend(namespace string) (infra.Backend, error)
	Dialer(namespace string) ContextDialer
	AgentURL(namespace string) string
}

Namespaces resolves project-scoped infrastructure and transport dependencies.

type OpResult 

type OpResult struct {
	Done bool
	// Recovered confirms a successful native outcome during failure cleanup.
	// Only a completed backup may override its exhausted initiation retries.
	Recovered    bool
	RequeueAfter time.Duration
	Step         string
	Message      string
	Checkpoint   json.RawMessage
}

OpResult reports operation completion and the next durable checkpoint.

type OperationCanceller 

type OperationCanceller interface {
	CanCancelOperation(context.Context, *domain.Operation) error
	CancelOperation(context.Context, *Context, *domain.Operation) (OpResult, error)
}

OperationCanceller is optional: only the serialized worker executes cancellation. CanCancelOperation must be side-effect free and explain unsafe checkpoints. CancelOperation cooperatively restores safe invariants before returning Done.

type OperationClaimPolicy added in v0.2.0 

type OperationClaimPolicy interface {
	CanClaimOperation(*domain.Cluster) (bool, error)
}

OperationClaimPolicy optionally reserves ordinary convergence's maintenance ownership before a pending operation is claimed. False leaves queued work pending without consuming attempts or its execution retry budget. Opt-in providers' imperative deadlines start at StartedAt, not time spent queued. Running operations still resume before Sync.

type OperationObservationInvalidator added in v0.2.0 

type OperationObservationInvalidator interface {
	InvalidateOperationObservation(*domain.Operation) error
}

OperationObservationInvalidator discards transient observation windows before an attempt, including failures resolving dependencies before provider entry. Only a successful fresh provider observation may renew the prior checkpoint.

type OperationSyncPolicy 

type OperationSyncPolicy interface {
	SyncDuringOperation(op *domain.Operation) bool
}

OperationSyncPolicy optionally permits ordinary Sync after a nonterminal, successful RunOperation call. Without this policy, Running operations exclude Sync and Status, which may be unsafe while restore stops database processes. The decision uses the newly returned checkpoint. PSMDB must opt in only at replacement provisioning/join checkpoints so Sync can create the new member; restore, restart and credential-recovery checkpoints must remain isolated.

type PITRRestoreValidator 

type PITRRestoreValidator interface {
	ValidatePITRRestore(context.Context, *Context, time.Time) ([]domain.TimeWindow, error)
}

PITRRestoreValidator optionally validates a source cluster's current recovery coverage before accepting a restore. Windows are returned even on a rejected target so callers can show the current bounds. No coverage is an invalid-state conflict; a target outside continuous coverage is a field error.

type PlatformObservation added in v0.2.0 

type PlatformObservation struct {
	Project     infra.Project
	ProjectErr  error
	Services    []infra.Service
	ServicesErr error
	Members     []InstanceInventory
}

PlatformObservation shares project, service and instance inventory within one sweep. Member results preserve the caller's member order.

func ObservePlatform added in v0.2.0 

func ObservePlatform(ctx context.Context, backend infra.Backend, cluster string, members []string) PlatformObservation

ObservePlatform overlaps independent read-only platform calls with at most eight requests in flight. Callers can overlap it with native/agent probes. Each result retains its own error instead of substituting cached success.

type PlatformRetryWait 

type PlatformRetryWait struct {
	RetryAt time.Time
	Message string
	// Cause preserves backend retry constraints through wait conversion.
	Cause error
}

PlatformRetryWait reports an already scheduled retry, not a new failed attempt. Reconcilers retain its status message without recording another error event, and wake at RetryAt instead of applying error backoff.

func (*PlatformRetryWait) Error 

func (e *PlatformRetryWait) Error() string

func (*PlatformRetryWait) Unwrap added in v0.2.0 

func (e *PlatformRetryWait) Unwrap() error

type Provider 

type Provider interface {
	Name() string
	Describe() domain.ProviderInfo
	ApplyDefaults(*domain.ClusterSpec)
	Validate(context.Context, *domain.Cluster, *domain.Cluster) error
	Sync(context.Context, *Context) (Result, error)
	// Status may return a useful partial snapshot with a secondary error when
	// Phase is nonempty. Reconciliation publishes its safety observations but
	// does not declare readiness or advance the applied generation on that error.
	Status(context.Context, *Context) (domain.ClusterStatus, error)
	RunOperation(context.Context, *Context, *domain.Operation) (OpResult, error)
	Cleanup(context.Context, *Context, domain.DeleteOptions) (bool, error)
}

Provider defines idempotent engine reconciliation and resumable operations.

type RealClock 

type RealClock struct{}

RealClock supplies wall-clock UTC timestamps.

func (RealClock) Now 

func (RealClock) Now() time.Time

Now returns the current UTC wall-clock timestamp.

type Recorder 

type Recorder interface {
	Record(context.Context, domain.Event) error
}

Recorder persists an event before publishing it to live subscribers.

type Registry 

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

Registry owns providers indexed by their unique names.

func NewRegistry 

func NewRegistry(providers ...Provider) (*Registry, error)

NewRegistry registers providers, rejecting duplicate or empty names.

func (*Registry) Get 

func (r *Registry) Get(name string) (Provider, error)

Get returns the provider registered under a name.

func (*Registry) List 

func (r *Registry) List() []domain.ProviderInfo

List returns provider descriptions in name order.

func (*Registry) Register 

func (r *Registry) Register(p Provider) error

Register adds a uniquely named provider.

type RelayTargeter 

type RelayTargeter interface {
	RelayTargets(c *domain.Cluster) []string
}

RelayTargeter lists host:port targets a namespace relay may dial for a cluster.

type Result 

type Result struct {
	RequeueAfter time.Duration
	// ConvergenceError fails tracking operations for the current generation
	// without blocking independent queued operations or retrying reconciliation
	// as an error. Providers retain diagnostics in status and own warning deduplication.
	ConvergenceError error
}

Result requests a delay before the next level-triggered reconciliation.

type RetainedBackupDeleter 

type RetainedBackupDeleter interface {
	DeleteRetainedBackup(ctx context.Context, storage domain.BackupStorage, b domain.Backup) error
}

RetainedBackupDeleter deletes backup artifacts after their cluster is deleted.

type RetentionPolicy added in v0.2.0 

type RetentionPolicy interface {
	FilterRetention(backups, candidates []domain.Backup) []domain.Backup
}

RetentionPolicy optionally protects recovery chains from scheduled expiration. FilterRetention may only remove candidates; backups contains the full inventory. Explicit user deletions are not subject to schedule retention policy.

type RetrySchedule added in v0.2.0 

type RetrySchedule struct {
	RetryRecordedAt time.Time     `json:"retryRecordedAt,omitempty"`
	RetryDuration   time.Duration `json:"retryDuration,omitempty"`
}

RetrySchedule preserves the duration actually honored when a wall-clock deadline was recorded. The fields are additive so old checkpoints still load.

func (*RetrySchedule) Schedule added in v0.2.0 

func (r *RetrySchedule) Schedule(now, at time.Time) time.Time

Schedule records a deadline and its provenance using one clock observation.

func (RetrySchedule) Waiting added in v0.2.0 

func (r RetrySchedule) Waiting(now, at time.Time) bool

Waiting rejects impossible future deadlines after clock rollback. A legacy deadline (or one overwritten without matching provenance) retains its ordinary behavior up to the global maximum. Forward clock steps may make retries early. This is cadence only: callers must still apply every backend/process fence.

type RuntimeMember added in v0.2.0 

type RuntimeMember struct {
	MemberService
	ServiceID *string
	VolumeID  string
	Recovery  *RuntimeRecovery
}

RuntimeMember supplies persisted identity, not hostname-based adoption.

type RuntimeRecovery added in v0.2.0 

type RuntimeRecovery struct {
	RetrySchedule
	Op          *infra.Op   `json:"op,omitempty"`
	Action      string      `json:"action,omitempty"`
	ImportPlan  *ImportPlan `json:"importPlan,omitempty"`
	RetryAt     time.Time   `json:"retryAt,omitempty"`
	Initialized bool        `json:"initialized,omitempty"`
	VolumeLost  bool        `json:"volumeLost,omitempty"`
}

RuntimeRecovery is a member's durable, bounded infrastructure repair journal. Engine operations and cleanup must exclude this reconciler while they own a stop.

type RuntimeRecoveryResult added in v0.2.0 

type RuntimeRecoveryResult struct {
	Busy       bool
	Imported   bool
	VolumeLost bool
}

func ObserveRuntimeRecovery added in v0.2.0 

func ObserveRuntimeRecovery(ctx context.Context, rc *Context, m RuntimeMember) (RuntimeRecoveryResult, error)

ObserveRuntimeRecovery drains accepted work before another lifecycle owner can act. In particular, absent inventory never proves an accepted import finished.

func ReconcileRuntime added in v0.2.0 

func ReconcileRuntime(ctx context.Context, rc *Context, m RuntimeMember) (RuntimeRecoveryResult, error)

ReconcileRuntime restores running intent without creating storage. Call only for deployed, desired-running members, outside intentional stop/restore work. Derived-resource restoration belongs to the backend: transitional observations are left alone. Only confirmed logical absence permits a runtime-only import.

type SecretStore 

type SecretStore interface {
	GetClusterSecret(context.Context, domain.ClusterRef, string) ([]byte, error)
	SetClusterSecret(context.Context, domain.ClusterRef, string, []byte) error
	DeleteClusterSecret(context.Context, domain.ClusterRef, string) error
	GetAgentToken(context.Context, domain.ClusterRef, string) (*domain.AgentToken, error)
	SetAgentToken(context.Context, *domain.AgentToken) error
	DeleteAgentToken(context.Context, domain.ClusterRef, string) error
}

SecretStore provides encrypted cluster and agent credential persistence.

type StaticNamespaces 

type StaticNamespaces struct {
	DefaultBackend  infra.Backend
	DefaultAgentURL string
}

StaticNamespaces preserves single-project installations.

func (StaticNamespaces) AgentURL 

func (s StaticNamespaces) AgentURL(namespace string) string

func (StaticNamespaces) Backend 

func (s StaticNamespaces) Backend(namespace string) (infra.Backend, error)

func (StaticNamespaces) Dialer 

func (s StaticNamespaces) Dialer(string) ContextDialer

type UnplacedRetirement added in v0.2.0 

type UnplacedRetirement struct {
	Phase string    `json:"phase,omitempty"`
	Op    *infra.Op `json:"op,omitempty"`
}

UnplacedRetirement owns infrastructure-only retirement of a scale-up member which never joined the data plane. The provider must persist this intent before advancing it, retain import/ownership evidence, and exclude provisioning until retirement finishes. Native members must use their normal retirement workflow.

type ValidationError 

type ValidationError struct{ Field, Reason, Message string }

ValidationError is an ErrInvalid whose Message is safe to show to the API caller: it explains which part of the request was rejected and why. Field (JSON path such as spec.components.engine.replicas) and Reason (one of the domain.Reason* constants) are optional and become the API error details.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

func (*ValidationError) Is 

func (e *ValidationError) Is(target error) bool

Is makes errors.Is(err, ErrInvalid) hold for validation errors.

type VolumeInventory added in v0.4.1 

type VolumeInventory interface {
	VolumeReferences(*domain.Cluster) ([]VolumeReference, error)
}

VolumeInventory exposes identities, not provider sizing caches: legacy import checkpoints may contain desired bounds that were never applied to a volume.

type VolumeReference added in v0.4.1 

type VolumeReference struct {
	Component string
	Hostname  string
	ID        string
}

VolumeReference identifies a persistent volume, never a runtime disk.

type WriteOnlyOptions added in v0.4.0 

type WriteOnlyOptions interface {
	ExtractWriteOnlyOptions(old *domain.ClusterSpec, spec *domain.ClusterSpec) (map[string][]byte, error)
}

WriteOnlyOptions extracts credentials before validation, persistence and API response construction. Implementations validate required creation credentials here; omitted update credentials leave existing secrets unchanged.

Source Files

View all Source files

Directories

Path Synopsis
Package elastic reconciles Elasticsearch nodes and their Kibana, Logstash and APM component services.
 Package elastic reconciles Elasticsearch nodes and their Kibana, Logstash and APM component services.
agentspec
Package agentspec defines the Elasticsearch engine payload carried in agentapi.MemberConfig.EngineSpec.
 Package agentspec defines the Elasticsearch engine payload carried in agentapi.MemberConfig.EngineSpec.
esapi
Package esapi implements Elasticsearch administration over CA-pinned HTTPS.
 Package esapi implements Elasticsearch administration over CA-pinned HTTPS.
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
 SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
Package keycloak reconciles an independent PostgreSQL binding consumer.
 Package keycloak reconciles an independent PostgreSQL binding consumer.
kcspec
Package kcspec defines the private Keycloak member configuration.
 Package kcspec defines the private Keycloak member configuration.
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
 SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
myspec
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
 SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
Package nativeartifacts pins the native programs installed by engine members.
 Package nativeartifacts pins the native programs installed by engine members.
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
 SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
neo4jspec
Package neo4jspec defines the Neo4j Community member payload carried in agentapi.MemberConfig.EngineSpec and the bounded agent action protocol shared by the control-plane provider (internal/engine/neo4j) and the member runner (internal/agent/neo4j).
 Package neo4jspec defines the Neo4j Community member payload carried in agentapi.MemberConfig.EngineSpec and the bounded agent action protocol shared by the control-plane provider (internal/engine/neo4j) and the member runner (internal/agent/neo4j).
Package openbao manages TLS-only OpenBao servers with Raft or opt-in PostgreSQL storage.
 Package openbao manages TLS-only OpenBao servers with Raft or opt-in PostgreSQL storage.
baoapi
Package baoapi is a minimal OpenBao HTTP API client shared by the control plane and the member agent.
 Package baoapi is a minimal OpenBao HTTP API client shared by the control plane and the member agent.
baospec
Package baospec defines the OpenBao member specification and the bounded control-plane ↔ member-agent protocol.
 Package baospec defines the OpenBao member specification and the bounded control-plane ↔ member-agent protocol.
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
 SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
pgprofile
Package pgprofile is the shared availability and curated SQL authority for PostgreSQL profiles.
 Package pgprofile is the shared availability and curated SQL authority for PostgreSQL profiles.
pgspec
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
 SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
Package psmdb manages Percona Server for MongoDB without Kubernetes.
 Package psmdb manages Percona Server for MongoDB without Kubernetes.
mongoadmin
Package mongoadmin implements authenticated, quorum-aware MongoDB administration.
 Package mongoadmin implements authenticated, quorum-aware MongoDB administration.
pbm
Package pbm orchestrates durable Percona Backup for MongoDB operations through node agents.
 Package pbm orchestrates durable Percona Backup for MongoDB operations through node agents.
users
Package users manages MongoDB application users, custom roles, and the Percona system-user split.
 Package users manages MongoDB application users, custom roles, and the Percona system-user split.
Package pxc composes the shared MySQL lifecycle with Galera replication.
 Package pxc composes the shared MySQL lifecycle with Galera replication.
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
 SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
mgmt
Package mgmt implements the RabbitMQ Management HTTP API.
 Package mgmt implements the RabbitMQ Management HTTP API.
rmqspec
Package rmqspec defines the RabbitMQ member and bounded agent protocol.
 Package rmqspec defines the RabbitMQ member and bounded agent protocol.
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
 SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
sbkeys
Package sbkeys generates Supabase credentials without persistence or logging.
 Package sbkeys generates Supabase credentials without persistence or logging.
sbspec
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
 SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
 SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
tspec
Package tspec defines the secret-bearing Temporal member contract shared by the control plane and the member agent.
 Package tspec defines the secret-bearing Temporal member contract shared by the control plane and the member agent.
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
 SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
wvapi
Package wvapi implements the Weaviate v1 REST administration API.
 Package wvapi implements the Weaviate v1 REST administration API.
wvspec
Package wvspec defines the encrypted Weaviate member wire contract.
 Package wvspec defines the encrypted Weaviate member wire contract.

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.