admin

Documentation

Overview

Package admin serves the private operator dashboard. Network metrics stay read-only; the isolated sample-worker control plane issues and revokes narrowly scoped capabilities for refresh and private draft submission.

It deliberately consumes only bounded aggregate reads. In particular it does not infer users, active MCP sessions, downloads, or factory activity from unrelated counters.

Index

• func Register(mux *http.ServeMux, d Deps) bool
• func WorkerUnixCMD(base string) string
• func WorkerUnixRunCMD() string
• type AccessActivityGroup
• type AccessGroupCounts
• type AccessLogDay
• type AccessLogMetrics
• type AccessLogReader
  • func NewAccessLogReader(path string) *AccessLogReader
  • func (r *AccessLogReader) Metrics(ctx context.Context, now time.Time) (AccessLogMetrics, error)
• type AccessMetricsReader
• type AccessRouteClass
• type AccessRouteCounts
• type AccessStatusCounts
• type ActivityReader
• type Deps
• type Instance
• type PoolStatsReader
• type Store

Functions

func Register

func Register(mux *http.ServeMux, d Deps) bool

Register mounts the exact /admin path only when TokenSHA256 is a valid digest. Returning false and registering nothing is intentional: absent or malformed configuration makes the private route indistinguishable from an unknown path (404), instead of accidentally falling back to another token.

func WorkerUnixCMD

func WorkerUnixCMD(base string) string

The Linux verification worker install command lives here rather than on a public page.

They were the call to action on /contribute, which is gone: a contributor turned out to do exactly what any user does -- installing csx is what emits observations -- except for running samples to verify them, and the project runs those on its own machines. So this is an operator tool, and it belongs beside the internal sample workers it pairs with.

The Windows variants are gone with the Windows verification farm. Only golang and pypi publish a Windows base image at all, so that axis could never have been more than two ecosystems wide -- which makes a Windows cell observation-only by design rather than a backlog anyone can work off.

func WorkerUnixRunCMD

func WorkerUnixRunCMD() string

workerUnixRunCMD reports what is installed and running, then starts the worker. The status lines come first because `csx worker start` runs in the foreground and never returns while it is working — after it, nothing else in the paste would ever print.

Types

type AccessActivityGroup

type AccessActivityGroup string

AccessActivityGroup is a fixed decision-oriented grouping of API routes. It describes request activity, never people or sessions.

const (
	AccessGroupConsumption  AccessActivityGroup = "consumption"
	AccessGroupContribution AccessActivityGroup = "contribution"
	AccessGroupCoordination AccessActivityGroup = "coordination"
)

type AccessGroupCounts

type AccessGroupCounts struct {
	Group AccessActivityGroup
	Label string
	AccessStatusCounts
}

AccessGroupCounts is one of the three fixed activity groups.

type AccessLogDay

type AccessLogDay struct {
	Date        string
	HasRequests bool
	AccessStatusCounts
	Routes []AccessRouteCounts
	Groups []AccessGroupCounts
}

AccessLogDay is one UTC calendar day. HasRequests distinguishes a retained day with observed calls from a zero-filled chart position; it does not claim that a zero position had complete log coverage.

type AccessLogMetrics

type AccessLogMetrics struct {
	Days   []AccessLogDay
	Routes []AccessRouteCounts
	Groups []AccessGroupCounts
	Totals AccessStatusCounts

	CollectionStartedAt time.Time
	OldestEventAt       time.Time
	NewestEventAt       time.Time
	DaysWithRequests    int
	SourceFiles         int
	TruncatedFiles      int
	MalformedLines      int64
	OversizeLines       int64
}

AccessLogMetrics is a bounded 31-day view over the privacy-safe Caddy log. CollectionStartedAt comes from a one-time deployment marker when present. OldestEventAt and NewestEventAt describe only the retained files actually read, so the dashboard can disclose partial coverage honestly.

type AccessLogReader

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

AccessLogReader streams access-safe.log and at most forty Caddy rolls. It caches the completed aggregate for five minutes and reuses unchanged rolled file aggregates after that, so /admin does not repeatedly parse the full retained log set.

func NewAccessLogReader

func NewAccessLogReader(path string) *AccessLogReader

NewAccessLogReader constructs the bounded reader. Metrics rejects every basename except access-safe.log, preventing an accidental fallback to the older logs which can contain query strings.

func (*AccessLogReader) Metrics

func (r *AccessLogReader) Metrics(ctx context.Context, now time.Time) (AccessLogMetrics, error)

Metrics returns the last 31 UTC calendar days, including the day containing now. A missing safe log is a normal empty state while Caddy starts; real permission, gzip and read failures are returned as generic errors which do not contain a raw line or URI.

type AccessMetricsReader

type AccessMetricsReader interface {
	Metrics(ctx context.Context, now time.Time) (AccessLogMetrics, error)
}

AccessMetricsReader is the narrow read-only seam around privacy-safe, query-stripped HTTP access logs. It exposes request volume, never users.

type AccessRouteClass

type AccessRouteClass string

AccessRouteClass is a fixed, privacy-safe API route label. Raw paths and path parameters never leave the parser.

const (
	AccessRouteSearch           AccessRouteClass = "search"
	AccessRouteEvidence         AccessRouteClass = "evidence"
	AccessRouteRegistry         AccessRouteClass = "registry"
	AccessRouteShards           AccessRouteClass = "shards"
	AccessRouteSamples          AccessRouteClass = "samples"
	AccessRouteWanted           AccessRouteClass = "wanted"
	AccessRouteAdoption         AccessRouteClass = "adoption"
	AccessRouteVerifications    AccessRouteClass = "verifications"
	AccessRouteVerificationJobs AccessRouteClass = "verification_jobs"
	AccessRoutePeers            AccessRouteClass = "peers"
	AccessRouteStats            AccessRouteClass = "stats"
	AccessRouteAdapters         AccessRouteClass = "adapters"
	AccessRouteAuth             AccessRouteClass = "auth"
)

type AccessRouteCounts

type AccessRouteCounts struct {
	Class      AccessRouteClass
	Label      string
	Group      AccessActivityGroup
	GroupLabel string
	AccessStatusCounts
}

AccessRouteCounts is one fixed route-class row.

type AccessStatusCounts

type AccessStatusCounts struct {
	Requests            int64
	GetHeadRequests     int64
	PostRequests        int64
	OtherMethodRequests int64
	Status2xx           int64
	Status3xx           int64
	Status4xx           int64
	Status429           int64
	Status5xx           int64
	StatusOther         int64
}

AccessStatusCounts contains only coarse counters. Status429 is deliberately also included in Status4xx: it is a highlighted subset, not a disjoint band.

type ActivityReader

type ActivityReader interface {
	MarkOwner(ctx context.Context, r *http.Request, now time.Time) error
	Metrics(ctx context.Context, now time.Time) (activity.Metrics, error)
	Telemetry() activity.Telemetry
}

ActivityReader can mark the authenticated operator network and return only privacy-bounded, owner-excluded network estimates and collection telemetry.

type Deps

type Deps struct {
	Store         Store
	TokenSHA256   string
	PublicURL     string
	Version       string
	StartedAt     time.Time
	Now           func() time.Time
	AccessMetrics AccessMetricsReader
	Activity      ActivityReader
	Authoring     serverstore.AuthoringSessionStore
	// AdminTokens backs the operator API credential. Nil leaves the admin
	// surface reachable only through the browser's Basic prompt.
	AdminTokens serverstore.AdminTokenStore
	// Farm backs the operations panel. Nil hides it rather than showing zeros.
	Farm serverstore.FarmStatsStore
	// Anomalies backs the consumption-feedback panel. Nil hides it: a store
	// that cannot answer has nothing honest to show, and a panel of zeros
	// reads as "nobody reported anything" rather than "not measured here".
	Anomalies serverstore.AnomalyStore
	// CSXIssues backs the product-defect panel. Nil hides it, for the same
	// reason: a panel of zeros reads as "nobody reported anything" rather
	// than "not measured here".
	CSXIssues serverstore.CSXIssueStore
	// PoolStats backs the database pool panel. Nil hides it: a store
	// without a pool has nothing honest to report there.
	PoolStats PoolStatsReader
	// Instances are the machines being paid for, with their monthly price.
	Instances []Instance
}

Deps wires the private dashboard. TokenSHA256 must be the 64-character hexadecimal SHA-256 digest of the HTTP Basic password; a raw token is never accepted. The username is always "recuerdame".

type Instance

type Instance struct {
	Name       string
	MonthlyUSD float64
}

Instance is one machine the operator pays for.

The cost is configured rather than fetched. Reading it from AWS would mean putting a credential on the server that an operator token already opens, and the number it would return is a fixed bundle price the operator already knows. A figure typed once is worth less than an API call and costs a great deal less to be wrong about.

type PoolStatsReader

type PoolStatsReader interface {
	PoolStats() serverstore.PoolStats
}

PoolStatsReader is the narrow seam onto the store's own connection pool. A store that cannot answer (the fake, a store without a pool) leaves the panel out rather than showing zeros.

type Store

type Store interface {
	GetLatestStats(ctx context.Context) (statsJSON string, ok bool, err error)
	NetworkCounts(ctx context.Context, now time.Time) (serverstore.NetworkCounts, error)
	ListWanted(ctx context.Context, query string, offset, limit int) (rows []serverstore.WantedRow, total int, err error)
	AdoptionSummary(ctx context.Context) (serverstore.AdoptionCounts, error)
	AdminInsights(ctx context.Context, now time.Time) (insights serverstore.AdminInsights, available bool, err error)
}

Store is the deliberately small read-only view needed by the dashboard. Every method returns a bounded aggregate or a bounded page.