Documentation
¶
Overview ¶
Package inspect implements Starling's local web inspector as a reusable library. The standalone binary cmd/starling-inspect is a thin shim around inspect.New; downstream users who want full functionality (including replay-from-UI) wire inspect.New into their own agent binary so the server can construct the user's Agent on demand.
inspect.New is read-mostly: it serves an HTTP UI backed by an eventlog.EventLog (which must also satisfy eventlog.RunLister). It never calls Append. To enforce that at the storage layer too, pass an EventLog opened with eventlog.WithReadOnly().
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Authenticator ¶
Authenticator reports whether r is allowed to proceed. It runs before every request reaches the mux — page routes, the HTMX fragment, the live-tail SSE, static assets, replay endpoints, all of it. Returning false causes the server to emit 401 and short-circuit.
The signature takes the raw *http.Request so callers can inspect headers, cookies, the client cert (r.TLS), or r.RemoteAddr; write whatever policy makes sense (bearer, JWT, mTLS, IP allowlist, a reverse-proxy-set header, etc.). BearerAuth is the one built-in.
func BearerAuth ¶
func BearerAuth(token string) Authenticator
BearerAuth is an Authenticator matching a constant bearer token in the Authorization header ("Bearer <token>"). The comparison uses subtle.ConstantTimeCompare so a timing side-channel can't distinguish a correct prefix from an incorrect one. An empty token panics — the caller is asking for "no auth" and should pass nil to WithAuth instead.
type Option ¶
type Option func(*Server)
Option customises a Server at construction time. None are exported yet; the type exists so the API can grow (WithReplayer, WithLogger, …) without a breaking change.
func WithAuth ¶
func WithAuth(fn Authenticator) Option
WithAuth installs an authentication middleware that runs before every request reaches the mux. Passing nil is a no-op — the server stays public, matching the default localhost-developer posture. See Authenticator and BearerAuth for the shape and the one built-in helper.
The middleware gates page routes, the HTMX event-detail fragment, the live-tail SSE, static assets, and the replay endpoints alike. Unauthenticated requests receive 401 with WWW-Authenticate: Bearer realm="starling-inspect".
func WithDBPath ¶
WithDBPath sets the human-readable database path label rendered in the inspector's topbar context chip. Use the file path; the UI shows just the basename and exposes the full path on hover.
Empty (the default) hides the chip — useful when the inspector is mounted behind a reverse proxy and the local file path wouldn't be meaningful to the operator.
func WithReplayer ¶
WithReplayer wires a replay.Factory into the Server so the /run/{id}/replay endpoints (and the "Replay" button in the UI) are active. Without this option the inspector is view-only: the replay routes return 404 and the button is hidden.
The factory is invoked once per replay session — typically on a POST to /run/{id}/replay — to construct the *starling.Agent that will re-execute the run. Downstream binaries that ship their own agent pass a closure capturing their provider config / tool registry / namespace; the inspector itself has no opinion on how the agent is built.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is the inspector HTTP handler. Construct via New and either pass it to http.Server.Handler directly or mount it under a reverse proxy. Server is safe for concurrent use.
func New ¶
New builds a Server backed by store. store must also implement eventlog.RunLister (both built-in backends do); New returns an error otherwise so a future write-only backend doesn't silently produce an inspector that can't list runs.
func (*Server) ReplayEnabled ¶
ReplayEnabled reports whether a Replayer was wired in via WithReplayer. UI templates use this to hide the Replay button on view-only deployments.
func (*Server) ServeHTTP ¶
func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP implements http.Handler. Runs auth (if configured) and double-submit CSRF (always-on for the two replay POSTs) before the mux. Rationale for the single chokepoint: a half-auth posture (static public, pages private) invites reflected-file tricks and buys no meaningful UX — unauthenticated users should see a bare 401, not a broken-CSS page.
Source Files