client

package
v0.6.0 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source 
const ReachabilityPollInterval = 3 * time.Second

ReachabilityPollInterval is how often WaitReachable re-checks reachability while polling.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	StatusCode int
	Code       string
	Message    string
	// NeedsConfirmation is true when a guardrail held the operation for confirmation
	// rather than refusing it: retrying with confirm set lets it proceed (ADR-0020).
	NeedsConfirmation bool
}

APIError is a non-2xx response from the control plane, carrying its structured error (a machine-readable code and a human message) so a tool can surface both.

func (*APIError) Error 

func (e *APIError) Error() string

type AddProviderRequest added in v0.2.0 

type AddProviderRequest struct {
	Name      string `json:"name,omitempty"`
	Type      string `json:"type"`
	SecretKey string `json:"secret_key,omitempty"`
	Token     string `json:"token,omitempty"`
}

AddProviderRequest registers a vendor credential. The token VALUE travels in this request over burrowd's authenticated, TLS-protected control-plane API; burrowd validates it and writes it into the burrow-credentials Secret (ADR-0030). The value is never logged, never stored in Postgres, never echoed back, and still never carried over MCP — provider add is a human/CLI operation.

type Addon added in v0.4.0 

type Addon struct {
	Name         string   `json:"name"`
	Type         string   `json:"type"`
	Mode         string   `json:"mode"`
	Image        string   `json:"image,omitempty"`
	Endpoint     string   `json:"endpoint"`
	Capabilities []string `json:"capabilities"`
	Ready        bool     `json:"ready"`
}

Addon is one installed (and, later, connected) add-on instance.

type AttachResult added in v0.6.0 

type AttachResult struct {
	App       string `json:"app"`
	Addon     string `json:"addon"`
	SecretKey string `json:"secret_key"`
}

AttachResult is the non-secret outcome of attaching an app to an add-on (ADR-0031): the KEY NAME the generated connection string was written under in the app's Secret — never the value.

type AuditEntry added in v0.5.0 

type AuditEntry struct {
	ID            int64             `json:"id,omitempty"`
	Timestamp     time.Time         `json:"timestamp"`
	Operation     string            `json:"operation"`
	Target        string            `json:"target,omitempty"`
	Args          map[string]string `json:"args,omitempty"`
	GuardrailCode string            `json:"guardrail_code,omitempty"`
	Disposition   string            `json:"disposition,omitempty"`
	Outcome       string            `json:"outcome"`
	Result        string            `json:"result,omitempty"`
	Caller        string            `json:"caller,omitempty"`
}

AuditEntry mirrors a control-plane audit row (ADR-0027): a guarded mutating operation and the guardrail decision and outcome that applied. Args is redacted at the source — it carries only safe metadata (names, image reference, replica count, env/secret key NAMES), never a value.

type AuditFilter added in v0.5.0 

type AuditFilter struct {
	App       string
	Operation string
	Outcome   string
	Limit     int
}

AuditFilter narrows an audit query. A zero value lists the latest rows across all apps.

type Backup added in v0.6.0 

type Backup struct {
	ID        string `json:"id"`
	App       string `json:"app"`
	CreatedAt string `json:"created_at"`
	Path      string `json:"path,omitempty"`
	SizeBytes int64  `json:"size_bytes,omitempty"`
	Status    string `json:"status"`
}

Backup is one recorded per-app database backup (ADR-0032): the control-plane index row for a dump on the backup PVC. It names the app, the on-PVC path, the size, and the status — never a credential.

type BackupResult added in v0.6.0 

type BackupResult struct {
	Backup Backup `json:"backup"`
}

BackupResult is the outcome of an on-demand backup (ADR-0032): the recorded backup row.

type CertManagerCapability added in v0.6.0 

type CertManagerCapability struct {
	Present bool `json:"present"`
}

CertManagerCapability reports whether cert-manager is installed (detected via its API group).

type Client 

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

Client is a thin HTTP client for the control-plane API (ADR-0005). The MCP server holds the API bearer token to authenticate to the control plane, but never any cluster credentials — those live only in the control plane. These DTOs mirror the API's JSON contract; the MCP layer deliberately does not import the control-plane packages, so it stays a decoupled client across the module boundary (LICENSING.md).

func NewClient 

func NewClient(baseURL, token string) *Client

NewClient returns a control-plane API client for baseURL authenticating with token, using a default HTTP client.

func NewClientWithHTTP 

func NewClientWithHTTP(baseURL, token string, hc *http.Client) *Client

NewClientWithHTTP is like NewClient but uses the supplied *http.Client. The connect package uses this to route requests through the Kubernetes API-server proxy with a kubeconfig-authenticated transport (ADR-0014). A nil hc gets a default client.

func (*Client) AddDomain added in v0.2.0 

func (c *Client) AddDomain(ctx context.Context, host, provider, address, app string, confirm bool) (DomainResult, error)

AddDomain points host at an address through the named DNS provider (ADR-0018). Give either an explicit address or the name of an exposed app whose ingress address the control plane reads.

func (*Client) AddProvider added in v0.2.0 

func (c *Client) AddProvider(ctx context.Context, req AddProviderRequest) (Provider, error)

AddProvider registers a vendor credential in the control-plane registry and returns the recorded provider (ADR-0023).

func (*Client) Addons added in v0.4.0 

func (c *Client) Addons(ctx context.Context) ([]Addon, error)

Addons lists the installed add-on instances.

func (*Client) Apps added in v0.3.0 

func (c *Client) Apps(ctx context.Context) ([]WorkloadStatus, error)

Apps lists the workload status of every Burrow-managed app.

func (*Client) AttachAddon added in v0.6.0 

func (c *Client) AttachAddon(ctx context.Context, addonType, app string) (AttachResult, error)

AttachAddon gives an app its own database on the installed Postgres add-on and wires it in (ADR-0031). The agent supplies only the add-on type and app name; burrowd generates the DATABASE_URL server-side and writes it into the app's Secret — no secret value crosses this API or MCP. The result carries the KEY name only, never the value.

func (*Client) Audit added in v0.5.0 

func (c *Client) Audit(ctx context.Context, f AuditFilter) ([]AuditEntry, error)

Audit lists audit rows newest-first, optionally filtered by app, operation, and outcome (ADR-0027). It is read-only — the audit log has no write or delete path through the API.

func (*Client) BackupAddon added in v0.6.0 

func (c *Client) BackupAddon(ctx context.Context, addonType, app string) (BackupResult, error)

BackupAddon backs up an app's database on the installed Postgres add-on (ADR-0032). burrowd runs an in-cluster Job that pg_dumps to the backup PVC and records the backup; no secret value crosses this API. The result is the recorded backup (id, app, path, size, status), never a credential.

func (*Client) Backups added in v0.6.0 

func (c *Client) Backups(ctx context.Context, addonType, app string) ([]Backup, error)

Backups lists recorded backups from the control-plane database (ADR-0032). An empty app lists every app's backups; a non-empty app restricts to that app. Read-only; no secret value.

func (*Client) Cluster added in v0.6.0 

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

Cluster reports the cluster's capabilities, read live (ADR-0034). It is read-only — it changes nothing and carries no secret value.

func (*Client) ConnectAddon added in v0.4.0 

func (c *Client) ConnectAddon(ctx context.Context, backend, endpoint, secretKey, token string) (Addon, error)

ConnectAddon registers an existing backend the user already runs (e.g. an in-cluster Loki) as a queryable add-on, recording its endpoint (ADR-0026). Unlike install it deploys nothing. secretKey, when non-empty, names the key in the burrow-credentials Secret under which the backend's bearer token lives; token is the bearer token VALUE for an authenticated backend, which travels over burrowd's authenticated, TLS-protected API and is written to the Secret (ADR-0030) — never logged, never stored in Postgres, never echoed back, never over MCP. Pass an empty token (and empty secretKey) for an unauthenticated backend.

func (*Client) DeleteApp added in v0.4.0 

func (c *Client) DeleteApp(ctx context.Context, app string, confirm bool) error

DeleteApp removes an app entirely — its workload, routing, and release history. The delete is guarded and held for confirmation by default; pass confirm=true to proceed past the hold.

func (*Client) Deploy 

func (c *Client) Deploy(ctx context.Context, app string, req DeployRequest) (DeployResult, error)

func (*Client) DetachAddon added in v0.6.0 

func (c *Client) DetachAddon(ctx context.Context, addonType, app string, confirm bool) error

DetachAddon detaches an app from an add-on, dropping its data (e.g. its Postgres database). It is held for confirmation by a guardrail by default; pass confirm=true to proceed past the hold.

func (*Client) Env added in v0.5.0 

func (c *Client) Env(ctx context.Context, app string) (map[string]string, error)

Env returns the app's non-secret env store (ADR-0028).

func (*Client) Expose added in v0.2.0 

func (c *Client) Expose(ctx context.Context, app, host string, port int32, tls bool, issuer string, confirm bool) (ExposeResult, error)

func (*Client) Guardrails added in v0.2.0 

func (c *Client) Guardrails(ctx context.Context) ([]Guardrail, error)

Guardrails lists the control-plane guardrails and their current dispositions.

func (*Client) InstallAddon added in v0.4.0 

func (c *Client) InstallAddon(ctx context.Context, addonType string, confirm bool) (Addon, error)

InstallAddon installs the vetted backing service for an add-on type (e.g. "logs").

func (*Client) Logs 

func (c *Client) Logs(ctx context.Context, app string, tail int) ([]LogLine, error)

func (*Client) Providers added in v0.2.0 

func (c *Client) Providers(ctx context.Context) ([]Provider, error)

Providers lists the configured providers, name order.

func (*Client) QueryLogs added in v0.4.0 

func (c *Client) QueryLogs(ctx context.Context, query string, limit int, backend string) ([]LogEntry, error)

QueryLogs queries the installed logs add-on with a LogsQL query (empty matches everything). A non-empty backend targets a specific logs add-on (by its concrete backend or registry name) when more than one serves the logs capability; empty picks the first.

func (*Client) QueryMetrics added in v0.4.0 

func (c *Client) QueryMetrics(ctx context.Context, query string, backend string) ([]MetricSample, error)

QueryMetrics runs an instant PromQL query against the connected metrics add-on (e.g. Prometheus). A non-empty backend targets a specific metrics add-on (by its concrete backend or registry name) when more than one serves the metrics capability; empty picks the first.

func (*Client) Reachability added in v0.2.0 

func (c *Client) Reachability(ctx context.Context, app string) (ReachabilityResult, error)

Reachability reports whether an app is reachable at its hostname, link by link.

func (*Client) RemoveAddon added in v0.4.0 

func (c *Client) RemoveAddon(ctx context.Context, name string, confirm bool) error

RemoveAddon removes the named add-on instance.

func (*Client) RemoveDomain added in v0.2.0 

func (c *Client) RemoveDomain(ctx context.Context, host, provider string, confirm bool) (DomainResult, error)

RemoveDomain removes the DNS record the provider holds for host.

func (*Client) RestoreAddon added in v0.6.0 

func (c *Client) RestoreAddon(ctx context.Context, addonType, app, backupID string, confirm bool) error

RestoreAddon restores an app's database from a recorded backup, overwriting its live contents (ADR-0032). It is held for confirmation by a guardrail by default; pass confirm=true to proceed.

func (*Client) Rollback 

func (c *Client) Rollback(ctx context.Context, app string, confirm bool) (RollbackResult, error)

func (*Client) Scale 

func (c *Client) Scale(ctx context.Context, app string, replicas int32, confirm bool) (ScaleResult, error)

func (*Client) Secrets added in v0.5.0 

func (c *Client) Secrets(ctx context.Context, app string) ([]string, error)

Secrets returns the KEYS in an app's per-app Secret, never the values (ADR-0028/0004). Secret values live only in the Kubernetes Secret; a list reads keys only and never returns a value.

func (*Client) SetEnv added in v0.5.0 

func (c *Client) SetEnv(ctx context.Context, app, key, value string, noRestart bool) error

SetEnv upserts one non-secret env key for an app (ADR-0028). By default the running workload rolls so the app picks the value up; noRestart only persists, landing the change on the next deploy.

func (*Client) SetGuardrail added in v0.2.0 

func (c *Client) SetGuardrail(ctx context.Context, code, disposition string) ([]Guardrail, error)

SetGuardrail sets a guardrail's disposition and returns the updated policy.

func (*Client) SetSecret added in v0.5.0 

func (c *Client) SetSecret(ctx context.Context, app, key, value string, noRestart bool) error

SetSecret upserts one secret key=value for an app (ADR-0029). The value travels over burrowd's authenticated, TLS-protected control-plane API, which writes it to the per-app Kubernetes Secret; it is never logged, never stored in Postgres, and is still never carried over MCP (there is no secret-set MCP tool). By default the running workload rolls so it picks the value up; with noRestart the change only persists and lands on the next deploy.

func (*Client) Status 

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

func (*Client) Unexpose added in v0.2.0 

func (c *Client) Unexpose(ctx context.Context, app string) error

func (*Client) UnsetEnv added in v0.5.0 

func (c *Client) UnsetEnv(ctx context.Context, app, key string, noRestart bool) error

UnsetEnv removes one env key for an app (ADR-0028). By default the running workload rolls; with noRestart the removal only persists and lands on the next deploy.

func (*Client) UnsetSecret added in v0.5.0 

func (c *Client) UnsetSecret(ctx context.Context, app, key string, noRestart bool) error

UnsetSecret removes one key from an app's per-app Secret (ADR-0028). Removing a key carries no value, so it is allowed over the API/MCP. By default the running workload rolls so it drops the value; with noRestart the change only persists and lands on the next deploy.

func (*Client) WaitReachable added in v0.6.0 

func (c *Client) WaitReachable(ctx context.Context, app string, timeout time.Duration, after func(time.Duration) <-chan time.Time) (ReachabilityResult, error)

WaitReachable polls Reachability until the app converges to live (Reachable) or timeout elapses, then returns the last verdict. It is the thin-client wait-until-live behind `burrow app reachability --wait` and the burrow_reachability MCP tool's wait mode; the control-plane engine stays point-in-time, so the polling and the clock live here, never in the engine (ADR-0034 slice 3).

A returned result with Reachable true means the app is live at result.URL; a returned result with Reachable false means the timeout elapsed and result.BlockedOn names the link to fix. after supplies the poll clock as a one-shot timer channel so tests can drive the loop without real time; pass nil for the real clock (time.After).

type ClusterCapabilities added in v0.6.0 

type ClusterCapabilities struct {
	Ingress      IngressCapability      `json:"ingress"`
	Storage      StorageCapability      `json:"storage"`
	LoadBalancer LoadBalancerCapability `json:"load_balancer"`
	CertManager  CertManagerCapability  `json:"cert_manager"`
	Provider     ProviderCapability     `json:"provider"`
	DNS          DNSCapability          `json:"dns"`
}

ClusterCapabilities mirrors the control plane's neutral, read-only report of what the cluster can do (ADR-0034): an ingress controller and its IngressClass, a default StorageClass, LoadBalancer support, cert-manager, the cloud provider, and whether a DNS provider is configured. It carries no secret value.

type DNSCapability added in v0.6.0 

type DNSCapability struct {
	Configured bool     `json:"configured"`
	Providers  []string `json:"providers,omitempty"`
}

DNSCapability reports whether a DNS provider is configured in the registry (ADR-0023).

type DeployRequest 

type DeployRequest struct {
	Image       string   `json:"image"`
	Command     []string `json:"command,omitempty"`
	MetricsPort int32    `json:"metrics_port,omitempty"`
	Replicas    int32    `json:"replicas"`
	Confirm     bool     `json:"confirm,omitempty"`
}

DeployRequest carries a deploy's code-free metadata. Env is deliberately absent: an app's non-secret config is an independently-managed store, set with SetEnv and sourced at apply time rather than passed per deploy (ADR-0028).

type DeployResult 

type DeployResult struct {
	Release             Release `json:"release"`
	SupersededReleaseID string  `json:"superseded_release_id,omitempty"`
}

type DomainResult added in v0.2.0 

type DomainResult struct {
	Host     string `json:"host"`
	Provider string `json:"provider"`
	Type     string `json:"type,omitempty"`
	Address  string `json:"address,omitempty"`
}

DomainResult mirrors the control plane's DNS-record outcome (ADR-0018).

type ExposeResult added in v0.2.0 

type ExposeResult struct {
	App  string `json:"app"`
	Host string `json:"host"`
	Port int32  `json:"port"`
	URL  string `json:"url"`
}

type Guardrail added in v0.2.0 

type Guardrail struct {
	Code        string `json:"code"`
	Disposition string `json:"disposition"`
	Description string `json:"description"`
}

type IngressCapability added in v0.6.0 

type IngressCapability struct {
	Present bool     `json:"present"`
	Classes []string `json:"classes,omitempty"`
}

IngressCapability reports the ingress-controller situation: present, and which IngressClass(es).

type LoadBalancerCapability added in v0.6.0 

type LoadBalancerCapability struct {
	Supported bool `json:"supported"`
	Inferred  bool `json:"inferred"`
}

LoadBalancerCapability reports whether Service type=LoadBalancer is likely supported (inferred from the detected provider).

type LogEntry added in v0.4.0 

type LogEntry struct {
	Time    string `json:"time,omitempty"`
	Message string `json:"message"`
	Pod     string `json:"pod,omitempty"`
}

LogEntry is one record from a logs query.

type LogLine 

type LogLine struct {
	Pod       string    `json:"pod"`
	Timestamp time.Time `json:"timestamp"`
	Message   string    `json:"message"`
}

type MetricSample added in v0.4.0 

type MetricSample struct {
	Labels map[string]string `json:"labels,omitempty"`
	Value  string            `json:"value"`
	Time   string            `json:"time,omitempty"`
}

MetricSample is one sample from a metrics query. Value is the metric's value as a string so PromQL's exact numeric formatting is preserved.

type Provider added in v0.2.0 

type Provider struct {
	Name         string    `json:"name"`
	Type         string    `json:"type"`
	Capabilities []string  `json:"capabilities"`
	SecretKey    string    `json:"secret_key"`
	CreatedAt    time.Time `json:"created_at"`
}

Provider mirrors a control-plane provider registry entry (ADR-0023). It carries no token — only the non-secret registry: the vendor type, the capabilities it serves, and the key under which its token lives in the burrow-credentials Secret.

type ProviderCapability added in v0.6.0 

type ProviderCapability struct {
	Cloud string `json:"cloud,omitempty"`
	Name  string `json:"name,omitempty"`
}

ProviderCapability reports the detected cloud provider.

type ReachabilityResult added in v0.2.0 

type ReachabilityResult struct {
	App                string   `json:"app"`
	Deployed           bool     `json:"deployed"`
	Ready              bool     `json:"ready"`
	Exposed            bool     `json:"exposed"`
	Host               string   `json:"host,omitempty"`
	Address            string   `json:"address,omitempty"`
	TLS                bool     `json:"tls"`
	CertReady          bool     `json:"cert_ready"`
	DNSPointsAtCluster bool     `json:"dns_points_at_cluster"`
	DNSAddresses       []string `json:"dns_addresses,omitempty"`
	Reachable          bool     `json:"reachable"`
	URL                string   `json:"url,omitempty"`
	BlockedOn          string   `json:"blocked_on,omitempty"`
	Summary            string   `json:"summary"`
}

type Release 

type Release struct {
	ID         string            `json:"id"`
	App        string            `json:"app"`
	Image      string            `json:"image"`
	Digest     string            `json:"digest,omitempty"`
	Env        map[string]string `json:"env,omitempty"`
	Command    []string          `json:"command,omitempty"`
	Replicas   int32             `json:"replicas"`
	Status     string            `json:"status"`
	Supersedes string            `json:"supersedes,omitempty"`
	CreatedAt  time.Time         `json:"created_at"`
}

type RollbackResult 

type RollbackResult struct {
	Release               Release `json:"release"`
	RolledBackToReleaseID string  `json:"rolled_back_to_release_id"`
	SupersededReleaseID   string  `json:"superseded_release_id"`
}

type ScaleResult 

type ScaleResult struct {
	App              string `json:"app"`
	PreviousReplicas int32  `json:"previous_replicas"`
	Replicas         int32  `json:"replicas"`
}

type StatusResult 

type StatusResult struct {
	App        string         `json:"app"`
	HasRelease bool           `json:"has_release"`
	Release    Release        `json:"release,omitempty"`
	Running    bool           `json:"running"`
	Workload   WorkloadStatus `json:"workload,omitempty"`
}

type StorageCapability added in v0.6.0 

type StorageCapability struct {
	DefaultPresent bool     `json:"default_present"`
	DefaultClass   string   `json:"default_class,omitempty"`
	Classes        []string `json:"classes,omitempty"`
}

StorageCapability reports the default-StorageClass situation.

type WorkloadStatus 

type WorkloadStatus struct {
	App             string `json:"app"`
	Kind            string `json:"kind"`
	Image           string `json:"image"`
	DesiredReplicas int32  `json:"desired_replicas"`
	ReadyReplicas   int32  `json:"ready_replicas"`
	UpdatedReplicas int32  `json:"updated_replicas"`
	Available       bool   `json:"available"`
}

Source Files

View all Source files

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.