adminapi

package
v1.6.0 Latest Latest
Warning

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

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

Documentation

Overview

Package adminapi provides the authenticated AgentSQL management REST API.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrInvalidAdminCredentials = errors.New("invalid administrator credentials")
	ErrInvalidAdminToken       = errors.New("invalid administrator token")
)
View Source
var ErrB5OperationsUnavailable = errors.New("b5 operations runtime is unavailable")

Functions

func AdminCredentialsFromEnv

func AdminCredentialsFromEnv() (username, password string, err error)

AdminCredentialsFromEnv loads the administrator username/password without persisting either value.

func DeriveTokenKey

func DeriveTokenKey(secret []byte) []byte

DeriveTokenKey derives the admin-token signing key from AGENTSQL_SECRET.

func NewHandler

func NewHandler(deps Deps, logger zerolog.Logger) (http.Handler, error)

Types

type B5AdminBackend

B5AdminBackend is the narrow S9 boundary. Read methods cannot obtain a raw business executor. Mutation methods are intentionally separate and are called only after the HTTP layer has durably recorded an administrator intent. A nil backend keeps the explicit rollback/feature-off surface.

type B5BackendIdentityView

type B5BackendIdentityView struct {
	ServerID       string     `json:"server_id"`
	Database       string     `json:"database"`
	PID            int32      `json:"pid"`
	BackendStarted *time.Time `json:"backend_started_at,omitempty"`
	DialPermitID   string     `json:"dial_permit_id"`
}

type B5DurationMetric

type B5DurationMetric struct {
	Phase string  `json:"phase"`
	P50MS float64 `json:"p50_ms"`
	P95MS float64 `json:"p95_ms"`
	P99MS float64 `json:"p99_ms"`
}

type B5EventView

type B5EventView struct {
	Sequence       uint64    `json:"sequence"`
	Type           string    `json:"type"`
	SchemaID       string    `json:"schema_id"`
	SchemaVersion  uint16    `json:"schema_version"`
	PreviousDigest string    `json:"previous_digest"`
	Digest         string    `json:"digest"`
	CreatedAt      time.Time `json:"created_at"`
}

type B5InventoryChildView

type B5InventoryChildView struct {
	LeaseID       string                `json:"lease_id"`
	ClaimID       string                `json:"claim_id"`
	DatasourceID  string                `json:"datasource_id"`
	State         string                `json:"state"`
	Charged       bool                  `json:"charged"`
	DialAttempted bool                  `json:"dial_attempted"`
	Backend       B5BackendIdentityView `json:"backend"`
}

type B5InventoryView

type B5InventoryView struct {
	DialPermits int                    `json:"dial_permits"`
	Children    []B5InventoryChildView `json:"children"`
}

type B5ListFilter

type B5ListFilter struct {
	Page, PageSize int
	Status         string
	Phase          string
	DatasourceID   string
	Owner          string
	Query          string
}

type B5MetricsView

type B5MetricsView struct {
	Sessions               int64              `json:"sessions"`
	Transactions           int64              `json:"transactions"`
	Unknown                int64              `json:"unknown"`
	DiscardUnconfirmed     int64              `json:"discard_unconfirmed"`
	QuarantineCount        int64              `json:"quarantine_count"`
	QuarantineChargedSlots int64              `json:"quarantine_charged_slots"`
	HardBudget             int64              `json:"hard_budget"`
	QuarantineBudgetRatio  float64            `json:"quarantine_budget_ratio"`
	SessionStates          []B5StateCount     `json:"session_states"`
	TransactionStates      []B5StateCount     `json:"transaction_states"`
	PhaseDurations         []B5DurationMetric `json:"phase_durations"`
}

type B5QuarantinePage

type B5QuarantinePage struct {
	Total int64              `json:"total"`
	List  []B5QuarantineView `json:"list"`
}

type B5QuarantineView

type B5QuarantineView struct {
	LeaseID        string                `json:"lease_id"`
	ClaimID        string                `json:"claim_id"`
	DatasourceID   string                `json:"datasource_id"`
	Reason         string                `json:"reason"`
	AgeSeconds     int64                 `json:"age_seconds"`
	ChargedSlots   int                   `json:"charged_slots"`
	Generation     uint64                `json:"generation"`
	InventoryEpoch uint64                `json:"inventory_epoch"`
	Backend        B5BackendIdentityView `json:"backend"`
}

type B5ReconcileInput

type B5ReconcileInput struct {
	TransactionID string `json:"transaction_id,omitempty"`
	DatasourceID  string `json:"datasource_id,omitempty"`
	Confirm       bool   `json:"confirm"`
}

type B5ReconciliationPage

type B5ReconciliationPage struct {
	Total int64                  `json:"total"`
	List  []B5ReconciliationView `json:"list"`
}

type B5ReconciliationView

type B5ReconciliationView struct {
	EventUUID          string    `json:"event_uuid"`
	TransactionID      string    `json:"transaction_id"`
	Sequence           uint64    `json:"sequence"`
	Classification     string    `json:"classification"`
	ReportedDurability string    `json:"reported_durability"`
	AppendConfirmation string    `json:"append_confirmation"`
	Reconciliation     string    `json:"reconciliation"`
	Replayed           bool      `json:"replayed"`
	UpdatedAt          time.Time `json:"updated_at"`
}

type B5RuntimePlane

B5RuntimePlane supplies the live S3/S7 observations and controlled actions which cannot be inferred safely from session metadata. Implementations own backend inventory and WAL scanners; StoreB5Admin never receives a business connection or guesses backend absence from local socket state.

type B5SessionPage

type B5SessionPage struct {
	Total int64           `json:"total"`
	List  []B5SessionView `json:"list"`
}

type B5SessionView

type B5SessionView struct {
	ID                string    `json:"id"`
	AgentID           string    `json:"agent_id"`
	TenantID          string    `json:"tenant_id"`
	PrincipalID       string    `json:"principal_id"`
	Status            string    `json:"status"`
	OwnerInstanceID   string    `json:"owner_instance_id"`
	OwnerEpoch        uint64    `json:"owner_epoch"`
	StickyRoute       string    `json:"sticky_route"`
	IdleExpiresAt     time.Time `json:"idle_expires_at"`
	AbsoluteExpiresAt time.Time `json:"absolute_expires_at"`
	CreatedAt         time.Time `json:"created_at"`
	UpdatedAt         time.Time `json:"updated_at"`
}

type B5StateCount

type B5StateCount struct {
	State string `json:"state"`
	Count int64  `json:"count"`
}

type B5StatusView

type B5StatusView struct {
	Enabled bool   `json:"enabled"`
	State   string `json:"state"`
	Reason  string `json:"reason"`
	Ready   bool   `json:"ready"`
}

type B5TransactionPage

type B5TransactionPage struct {
	Total int64               `json:"total"`
	List  []B5TransactionView `json:"list"`
}

type B5TransactionView

type B5TransactionView struct {
	ID                   string        `json:"id"`
	SessionID            string        `json:"session_id"`
	DatasourceID         string        `json:"datasource_id"`
	Status               string        `json:"status"`
	Phase                string        `json:"phase"`
	PlanDigest           string        `json:"plan_digest"`
	ApprovalID           *string       `json:"approval_id,omitempty"`
	OwnerEpoch           uint64        `json:"owner_epoch"`
	IdleDeadline         time.Time     `json:"idle_deadline"`
	WallDeadline         time.Time     `json:"wall_deadline"`
	StatementDeadline    *time.Time    `json:"statement_deadline,omitempty"`
	BackendPID           *int          `json:"backend_pid,omitempty"`
	BackendStartedAt     *time.Time    `json:"backend_started_at,omitempty"`
	ConnectionGeneration uint64        `json:"connection_generation"`
	LeaseGeneration      uint64        `json:"lease_generation"`
	StatementCount       int           `json:"statement_count"`
	Sequence             uint64        `json:"sequence"`
	PreviousEventDigest  string        `json:"previous_event_digest"`
	CreatedAt            time.Time     `json:"created_at"`
	UpdatedAt            time.Time     `json:"updated_at"`
	Events               []B5EventView `json:"events"`
}

type ChainManifestProvider

type ChainManifestProvider = store.ChainManifestProvider

ChainManifestProvider resolves trusted, database-external chain authority.

func NewKeylessChainManifestProvider

func NewKeylessChainManifestProvider() ChainManifestProvider

NewKeylessChainManifestProvider returns the explicit version-zero manifest used by installations that have not configured an HMAC chain key.

type DatasourcePinger

type DatasourcePinger interface {
	Ping(ctx context.Context, datasource model.Datasource) (PingResult, error)
}

type DemoRunner

type DemoRunner interface {
	ProcessDemo(context.Context, pipeline.Request) (pipeline.Response, error)
}

DemoRunner is the only live-pipeline capability exposed to the demo HTTP endpoint. Production startup injects it only after demo credentials pass fail-fast validation.

type Deps

type Deps struct {
	Runtime          *bootstrap.Runtime
	Config           config.Config
	AdminUsername    string
	AdminPassword    string
	TokenKey         []byte
	RBAC             *rbac.Service
	DatasourcePinger DatasourcePinger
	Native           NativeBackend
	Discovery        DiscoveryRunner
	ChainManifests   ChainManifestProvider
	// B5Admin is nil only for an explicit feature-off assembly. S9 routes remain
	// registered so clients receive stable empty capability responses, while an
	// activated assembly must explicitly provide the
	// read/operation boundary.
	B5Admin B5AdminBackend
	// EventStreamHeartbeatInterval is injectable for deterministic stream tests.
	// Zero uses the production interval.
	EventStreamHeartbeatInterval time.Duration
	// contains filtered or unexported fields
}

func PrepareDemoDeps

func PrepareDemoDeps(ctx context.Context, deps Deps) (Deps, error)

PrepareDemoDeps validates the two server-owned demo credentials during HTTP startup. The plaintext values remain in private Deps fields and are never added to configuration, logs, errors, or response DTOs.

type DiscoveryRunner

type DiscoveryRunner interface {
	Discover(context.Context, string, string, discovery.ScanRequest) (discovery.ScanResult, error)
}

type Handler

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

type HumanDelegationVerifier added in v1.0.0

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

HumanDelegationVerifier validates a scoped, short-lived AgentSQL token on every MCP request. The token is bound to one Agent and one live human login.

func NewHumanDelegationVerifier added in v1.0.0

func NewHumanDelegationVerifier(adminTokenKey []byte, sessions *store.AdminSessionRepository, roles *rbac.Service) (*HumanDelegationVerifier, error)

func (*HumanDelegationVerifier) Verify added in v1.0.0

func (verifier *HumanDelegationVerifier) Verify(ctx context.Context, token, agentID string) (rbac.Principal, error)

Verify checks signature, expiry, Agent binding, parent session revocation, and live tenant/user/RBAC state. No secret or untrusted claim enters errors.

type NativeBackend added in v0.5.0

type NativeBackend interface {
	NativeQueryRead(context.Context, model.Datasource, executor.NativeQueryRequest) (executor.NativeQueryResult, error)
	NativeDiscover(context.Context, model.Datasource) (executor.NativeCatalog, error)
	NativeServerVersion(context.Context, model.Datasource) (string, error)
}

type PingResult

type PingResult struct {
	OK           bool    `json:"ok"`
	LatencyMS    int64   `json:"latency_ms"`
	ErrorCode    *string `json:"error_code,omitempty"`
	ErrorMessage *string `json:"error_message,omitempty"`
}

type StoreB5Admin

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

StoreB5Admin is the production S9 read model. Constructing it does not activate B5; bootstrap selects activation and the entrypoint places it in Deps.B5Admin.

func NewStoreB5Admin

func NewStoreB5Admin(metadata *store.Store, live B5RuntimePlane) (*StoreB5Admin, error)

func NewStoreB5AdminWithStatus

func NewStoreB5AdminWithStatus(metadata *store.Store, status func(context.Context) (B5StatusView, error)) (*StoreB5Admin, error)

NewStoreB5AdminWithStatus links the production bootstrap readiness provider without granting the admin read model a business executor.

func (*StoreB5Admin) ConfirmDiscard

func (admin *StoreB5Admin) ConfirmDiscard(ctx context.Context, id string) (B5QuarantineView, error)

func (*StoreB5Admin) GetSession

func (admin *StoreB5Admin) GetSession(ctx context.Context, id string) (*B5SessionView, error)

func (*StoreB5Admin) GetTransaction

func (admin *StoreB5Admin) GetTransaction(ctx context.Context, id string) (*B5TransactionView, error)

func (*StoreB5Admin) Inventory

func (admin *StoreB5Admin) Inventory(ctx context.Context, datasource string) (B5InventoryView, error)

func (*StoreB5Admin) ListQuarantine

func (admin *StoreB5Admin) ListQuarantine(ctx context.Context, filter B5ListFilter) (B5QuarantinePage, error)

func (*StoreB5Admin) ListReconciliation

func (admin *StoreB5Admin) ListReconciliation(ctx context.Context, filter B5ListFilter) (B5ReconciliationPage, error)

func (*StoreB5Admin) ListSessions

func (admin *StoreB5Admin) ListSessions(ctx context.Context, filter B5ListFilter) (B5SessionPage, error)

func (*StoreB5Admin) ListTransactions

func (admin *StoreB5Admin) ListTransactions(ctx context.Context, filter B5ListFilter) (B5TransactionPage, error)

func (*StoreB5Admin) Metrics

func (admin *StoreB5Admin) Metrics(ctx context.Context, datasource string) (B5MetricsView, error)

func (*StoreB5Admin) Reconcile

func (admin *StoreB5Admin) Reconcile(ctx context.Context, input B5ReconcileInput) ([]B5ReconciliationView, error)

func (*StoreB5Admin) Status

func (admin *StoreB5Admin) Status(ctx context.Context) (B5StatusView, error)

Jump to

Keyboard shortcuts

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