Documentation
¶
Overview ¶
Package api implements the wire-compatible control-plane REST surface: Anthropic Managed Agents resource CRUD (agents / environments / sessions) with the reference paths, JSON shapes, ID prefixes, pagination envelope, error envelope, and x-api-key management auth. The `?beta=true` query and anthropic-version / anthropic-beta headers are accepted and ignored.
Index ¶
- Constants
- func EnsureAPIKey(ctx context.Context, pool *pgxpool.Pool, name, key string) error
- func EnsureEnvironmentKey(ctx context.Context, pool *pgxpool.Pool, environmentID, key string) error
- func NewHandler(pool *pgxpool.Pool, blobs blob.Store, cipher secrets.Cipher) http.Handler
- type ImportSummary
Constants ¶
const ( MetricFileUploads = "files.uploads" MetricFileUploadBytes = "files.upload.bytes" MetricFileDownloadBytes = "files.download.bytes" )
Files registry instruments (docs/plan/08_files.md observability table), mirroring the skills registry names. Attribute cardinality is bounded: outcome only — file ids belong in logs and span attributes, never in metric labels. Exported so filesmetric_test.go can assert the exact names and labels.
const ( MetricSkillUploads = "skills.uploads" MetricSkillUploadBytes = "skills.upload.bytes" MetricSkillDownloadBytes = "skills.download.bytes" )
Skill registry instruments (docs/plan/06_skills.md observability table). Attribute cardinality is bounded: outcome only — skill ids belong in logs and span attributes, never in metric labels. Exported so skillsmetric_test.go can assert the exact names and labels.
const MetricSessionResources = "session.resources"
MetricSessionResources counts session resource mutations (create-attach, add, delete, token rotation) by outcome. Outcome-only labels: session/resource/file ids ride the structured logs, never the metric (plan decision 9). Exported so the integration test can assert the name and labels.
Variables ¶
This section is empty.
Functions ¶
func EnsureAPIKey ¶
EnsureAPIKey makes key the one live credential for the named logical key: it inserts (or un-revokes) the hash and revokes every other unrevoked key under the same name. That gives rotation-by-restart semantics — changing CONTROLPLANE_API_KEY and restarting cmd/controlplane revokes the previous key instead of leaving it valid forever. All replicas must therefore share one key value per name; replicas booting with *different* values for one name race, and api_keys_one_live resolves that by failing the loser's transaction rather than leaving the name with two live credentials.
func EnsureEnvironmentKey ¶
EnsureEnvironmentKey makes key the one live worker credential for an environment: in one transaction it revokes every other unrevoked key for the same environment_id, then inserts (or un-revokes) the hash. That gives one live Authorization: Bearer credential per environment's work queue, with rotation-by-re-mint semantics (registering a fresh value revokes the prior one). Concurrent mints for one environment race, and environment_keys_one_live resolves that by failing the loser's transaction rather than leaving the queue with two live credentials. Only the hash is stored.
Issuance is a deliberate divergence: the reference mints environment keys in its console with no public wire endpoint, so a self-hostable platform owns this provisioning primitive. The consuming side — resolving a Bearer token to its environment — stays wire-locked by the real `ant beta:worker` client.
func NewHandler ¶
NewHandler assembles the control-plane HTTP surface over the given pool. blobs is the object store backing skill archives; nil deploys without object storage — everything serves except the storage-backed skill routes, which answer with a configuration error. cipher seals vault credential secrets; nil deploys without one — vault metadata CRUD serves, while the secret-bearing paths (credential create/update with secret fields, the validate probe) answer with a configuration error (fails closed, plan 12 D1).
Types ¶
type ImportSummary ¶ added in v0.2.0
type ImportSummary struct {
Imported []string // "name version" pairs landed this run
Skipped []string // already present at this version
Failed map[string]error // directory → why it did not import
}
ImportSummary reports one operator-import run.
func ImportAnthropicSkills ¶ added in v0.2.0
func ImportAnthropicSkills(ctx context.Context, pool *pgxpool.Pool, blobs blob.Store, dirs []string, version string) (*ImportSummary, error)
ImportAnthropicSkills is the controlplane's run-once operator import (docs/plan/06_skills.md slice 3): each dir is a skill directory from a local checkout of github.com/anthropics/skills, validated exactly like an upload and landed as a source='anthropic' skill whose id is the SKILL.md name (the reference catalog's short-name ids) at the given date-based version. Idempotent per (skill, version): an existing version is skipped without touching storage. A directory that fails to validate is logged and skipped; the returned error reports that some directories failed.
The checkout's content is read at the operator's machine and never enters this repository — the reference document skills are source-available, not open source (the plan's license red lines).
Source Files