httpapi

Documentation

Overview

Package httpapi implements the csx-server /v1 HTTP API (plan contract C5). All responses are JSON; errors are {"error": string}; handlers never panic outward. Registry and web reads only ever touch materialized snapshots — raw evidence is aggregated by internal/compatibility, never in-request (goal.md §14.5). The server never stores raw error text, paths, or user agents (§2.2).

Index

• func NewMux(d Deps) *http.ServeMux
• func RecomputeStatus(rows []serverstore.ReceiptRow, now time.Time) string
• type Deps
• type PublicnessChecker

Functions

func NewMux

func NewMux(d Deps) *http.ServeMux

NewMux builds the /v1 API mux with every C5 route registered.

func RecomputeStatus

func RecomputeStatus(rows []serverstore.ReceiptRow, now time.Time) string

RecomputeStatus re-derives a sample's status from its receipts under the CURRENT rules, starting from PUBLISHED rather than from whatever the row already says.

The live path only ever upgrades, which is right while the rules hold still. When a rule is corrected — as the environment-diversity gate was, after receipts that misstated where they ran had already granted MATRIX_PASS — a status earned under the old rule is simply wrong, and leaving it in place would advertise verification the evidence no longer supports. Downgrading is therefore an honesty operation, deliberately kept out of the request path and run by an operator.

Types

type Deps

type Deps struct {
	Store serverstore.Store
	Blobs blob.Store
	Cfg   serverstore.ServerConfig
	// PublicnessChecker is an interface so the outbound-lookup behaviour is
	// testable: this dependency is the one that reaches a third-party
	// registry with a name the caller chose, and a test has to be able to
	// count that.
	Checker PublicnessChecker

	// GitHub device-flow endpoints; empty fields use the github.com
	// defaults. Tests point these at httptest servers.
	GitHubDeviceURL string
	GitHubTokenURL  string
	GitHubUserURL   string

	// HTTPClient performs outbound GitHub calls; nil means a 10s-timeout
	// client.
	HTTPClient *http.Client

	// PeerProbe dials an announcing peer back to confirm other peers could
	// actually reach it. nil uses a real HTTP ping; tests supply a stub so
	// no test ever opens a socket to the outside.
	PeerProbe func(ctx context.Context, addr string, port int) bool

	// Limits holds the per-class rate limiters; nil builds the defaults.
	// Tests that hammer an endpoint on purpose install their own.
	Limits *limiters

	// Now is a test seam; nil means time.Now.
	Now func() time.Time
}

Deps carries everything the API handlers need. Checker is nil in trust mode (CSX_PUBLIC_CHECK=trust): every syntactically valid public-ecosystem batch is accepted without a registry probe (dev/e2e only).

type PublicnessChecker

type PublicnessChecker interface {
	Check(ctx context.Context, p domain.PURL) string
}

PublicnessChecker answers whether a package exists on its public registry. *registry.Checker satisfies it.