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 AdminAuth(tokenSHA256 string, tokens serverstore.AdminTokenStore) (mw func(http.Handler) http.Handler, ok bool)
• 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 DemandReader
• type Deps
• type Instance
• type PoolStatsReader
• type Store

Functions

func AdminAuth

func AdminAuth(tokenSHA256 string, tokens serverstore.AdminTokenStore) (mw func(http.Handler) http.Handler, ok bool)

AdminAuth builds the same operator authentication the /admin dashboard's own handler enforces -- HTTP Basic against the "recuerdame" username and TokenSHA256's digest, or a Bearer operator API token resolved through tokens -- as middleware another package's operator-only route can wrap itself in, instead of building a second, independently maintained auth mechanism (CSX-454: GET /v1/ops/pool-metrics is the first caller).

ok is false, and mw is nil, exactly when tokenSHA256 is not a valid 64-character hex SHA-256 digest -- the same gate Register applies before mounting /admin at all. A caller should not mount its route in that case either: an admin surface with no configured credential must be indistinguishable from an unknown path, not merely refuse every request that reaches it.

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 DemandReader

type DemandReader interface {
	Available() bool
	CountryEnabled() bool
	Report(ctx context.Context, now time.Time) (apidemand.Report, error)
	Telemetry() apidemand.Telemetry
}

DemandReader is the collector seam the dashboard reads: whether demand is being recorded at all, whether the edge supplies a country, the bounded report and the collector's own loss counters.

type Deps

type Deps struct {
	Store         Store
	TokenSHA256   string
	PublicURL     string
	Version       string
	StartedAt     time.Time
	Now           func() time.Time
	AccessMetrics AccessMetricsReader
	Activity      ActivityReader
	Anonymous     serverstore.AnonymousAnalyticsStore
	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
	// CLICoverage backs the CLI census on the same panel: the probes and
	// command gaps the authoring funnel offers, and what the farm cannot
	// reach. Nil hides the section.
	CLICoverage serverstore.CLIObservationStore
	// 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
	// Demand is the API demand telemetry collector (#394). Nil, or a
	// collector without a store, shows "not configured" rather than zeros.
	Demand DemandReader
	// DemandInsights backs the package-demand and search halves of the
	// same panel. Nil hides them for the usual reason.
	DemandInsights serverstore.AdminDemandReader
	// ReleaseVersion is the build's release stamp (v0.1.195), the yardstick
	// a client build is stale against. Version above is the commit shown
	// as "what is running"; this one is comparable.
	ReleaseVersion string
}

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.