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

adminapi

package
v0.5.1 Latest Latest
Warning

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

 Go to latest Published: Oct 13, 2026 License: Apache-2.0 Imports: 55 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 

type B5AdminBackend interface {
	Status(context.Context) (B5StatusView, error)
	ListSessions(context.Context, B5ListFilter) (B5SessionPage, error)
	GetSession(context.Context, string) (*B5SessionView, error)
	ListTransactions(context.Context, B5ListFilter) (B5TransactionPage, error)
	GetTransaction(context.Context, string) (*B5TransactionView, error)
	ListQuarantine(context.Context, B5ListFilter) (B5QuarantinePage, error)
	Inventory(context.Context, string) (B5InventoryView, error)
	Metrics(context.Context, string) (B5MetricsView, error)
	ListReconciliation(context.Context, B5ListFilter) (B5ReconciliationPage, error)
	ConfirmDiscard(context.Context, string) (B5QuarantineView, error)
	Reconcile(context.Context, B5ReconcileInput) ([]B5ReconciliationView, error)
}

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 

type B5RuntimePlane interface {
	Status(context.Context) (B5StatusView, error)
	ListQuarantine(context.Context, B5ListFilter) (B5QuarantinePage, error)
	Inventory(context.Context, string) (B5InventoryView, error)
	Metrics(context.Context, string) (B5MetricsView, error)
	ListReconciliation(context.Context, B5ListFilter) (B5ReconciliationPage, error)
	ConfirmDiscard(context.Context, string) (B5QuarantineView, error)
	Reconcile(context.Context, B5ReconcileInput) ([]B5ReconciliationView, error)
}

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 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)

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.