inspect

package
v0.11.0 Latest Latest
Warning

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

Go to latest
Published: Aug 30, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package inspect implements the proximo hop that sits in front of routes under Inspection: it proxies to the backend, injects the reporting agent into HTML responses, ingests what the agent sends back, and keeps the resulting Exchanges in memory. See docs/adr/0001-inspection-injects-into-the-response-path.md.

Index

Constants

View Source
const (
	// ReservedPath is the prefix proximo answers for on a project's own origin,
	// so an inspected page can report same-origin. It is unavailable to the
	// project for as long as the route carries the label.
	ReservedPath = "/.proximo/"

	// BackendHeader carries the address of the container this request is really
	// for. Traefik always overwrites it, so it cannot be forged from outside.
	BackendHeader = "X-Proximo-Backend"
)
View Source
const DefaultBudget = 64 << 20

DefaultBudget is how much memory the Store is allowed before it starts evicting the oldest Exchanges.

Variables

This section is empty.

Functions

func Agent

func Agent() ([]byte, error)

Agent returns the script the hop injects. It is proximo's own — there is no vendored bundle to build, pin or regenerate — so this is a plain read.

func NewID

func NewID() string

NewID mints the correlation id that joins the two halves of an Exchange.

Types

type AdminHandler

type AdminHandler struct{ Store *Store }

AdminHandler is the read side of the hop. It is deliberately a separate handler so it can be bound to a loopback-only listener: served on the request path it would let any inspected page read every Exchange recorded for its host.

func (AdminHandler) ServeHTTP

func (a AdminHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
type Breadcrumb struct {
	At       time.Time `json:"at"`
	Category string    `json:"category"`
	Level    string    `json:"level"`
	Message  string    `json:"message"`
}

Breadcrumb is one thing the page did before a Client report: a console call, a request it made, a click, a navigation.

type Exchange

type Exchange struct {
	ID       string        `json:"id"`
	At       time.Time     `json:"at"`
	Host     string        `json:"host"`
	Method   string        `json:"method"`
	Path     string        `json:"path"`
	Status   int           `json:"status"`
	Duration time.Duration `json:"duration_ns"`
	Bytes    int64         `json:"bytes"`
	Warnings []string      `json:"warnings,omitempty"`
	Reports  []Report      `json:"reports,omitempty"`

	// Suppressed counts the reports this Exchange saw beyond maxReports. They are
	// bounded, not discarded quietly: a page in a render loop must not be able to
	// evict every other Exchange, and a developer must still be told it happened.
	Suppressed int `json:"suppressed,omitempty"`

	// HasSnapshot tells a consumer of the JSON that `proximo errors dom` would
	// return something for this Exchange. Set by List.
	HasSnapshot bool `json:"has_snapshot"`

	// Snapshot is the page's DOM as it stood when the first Client report was
	// raised. It is never rendered inline, and never serialized with the rest:
	// the CLI asks for it separately and writes it to a file.
	Snapshot []byte `json:"-"`
}

Exchange is one request through an inspected route — the Access record — joined to the Client reports raised while the page it served was live.

type Frame

type Frame struct {
	File string `json:"file"`
	Line int    `json:"line"`
	Col  int    `json:"col,omitempty"`
	Func string `json:"func,omitempty"`
}

Frame is one entry of a Client report's stack trace.

type Handler

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

Handler is the hop itself: it proxies an inspected route to its backend, injects the reporting agent into HTML on the way back, and serves the reserved path. It is reachable from the browser, so it exposes nothing but the agent and the ingest endpoint — reading Exchanges back is AdminHandler's job, on a loopback-only listener.

func NewHandler

func NewHandler(store *Store, agent []byte) *Handler

NewHandler returns a hop recording into store and serving agent as the injected script.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Query

type Query struct {
	Host  string        // exact host match; empty matches any
	Since time.Duration // only Exchanges newer than this; zero means no bound
	Limit int           // most recent N; zero or less means no bound

	// OnlyProblems drops the Exchanges with nothing to say. It exists because
	// the alternative buries the one page that broke under every clean request
	// that did not, and the limit then cuts the interesting one first.
	OnlyProblems bool
}

Query narrows what List returns. The zero value holds nothing back.

type Report

type Report struct {
	At          time.Time    `json:"at"`
	Type        string       `json:"type"`
	Message     string       `json:"message"`
	Level       string       `json:"level"`
	Frames      []Frame      `json:"frames,omitempty"`
	Stack       string       `json:"stack,omitempty"` // as the browser formatted it
	Breadcrumbs []Breadcrumb `json:"breadcrumbs,omitempty"`
}

Report is one Client report: what the browser observed, with the Breadcrumbs that led up to it.

type Store

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

Store holds recent Exchanges in memory, bounded by total bytes rather than by count: one Exchange carrying a DOM Snapshot can outweigh a thousand without one. Nothing is written to disk — a Client report carries whatever the page held, and in development that is routinely real data.

func NewStore

func NewStore(budget int64) *Store

NewStore returns a Store bounded to budget bytes. A budget of zero or less uses DefaultBudget.

func (*Store) Add

func (s *Store) Add(e *Exchange)

Add records the server half of an Exchange, evicting the oldest entries until the Store is back inside its budget.

func (*Store) Attach

func (s *Store) Attach(id string, in ingested) bool

Attach adds a Client report — and, the first time one carries it, the DOM Snapshot — to the Exchange that served the page. It reports whether the id was known: an unknown id means the Exchange has already been evicted.

func (*Store) Complete

func (s *Store) Complete(id string, status int, took time.Duration, bytes int64, warnings []string)

Complete fills in the half of an Access record that is only known once the response has gone out. The Exchange was registered before that, so the page it served could already have reported against it.

func (*Store) List

func (s *Store) List(q Query) []Exchange

List returns the Exchanges matching q, most recently active first.

func (*Store) NoteRouteWarning

func (s *Store) NoteRouteWarning(host, msg string)

NoteRouteWarning records a warning against a host, ignoring one already held.

func (*Store) RouteWarnings

func (s *Store) RouteWarnings() map[string][]string

RouteWarnings returns the per-host warnings, for `proximo status`.

func (*Store) Snapshot

func (s *Store) Snapshot(id string) []byte

Snapshot returns the DOM captured for one Exchange, or nil when there is none.

func (*Store) Started

func (s *Store) Started() time.Time

Started reports when the Store came up, so an empty listing can say whether a restart is the reason.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL