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
- func Agent() ([]byte, error)
- func NewID() string
- type AdminHandler
- type Breadcrumb
- type Exchange
- type Frame
- type Handler
- type Query
- type Report
- type Store
- func (s *Store) Add(e *Exchange)
- func (s *Store) Attach(id string, in ingested) bool
- func (s *Store) Complete(id string, status int, took time.Duration, bytes int64, warnings []string)
- func (s *Store) List(q Query) []Exchange
- func (s *Store) NoteRouteWarning(host, msg string)
- func (s *Store) RouteWarnings() map[string][]string
- func (s *Store) Snapshot(id string) []byte
- func (s *Store) Started() time.Time
Constants ¶
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" )
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 ¶
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 ¶
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 ¶
NewHandler returns a hop recording into store and serving agent as the injected script.
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 ¶
NewStore returns a Store bounded to budget bytes. A budget of zero or less uses DefaultBudget.
func (*Store) Add ¶
Add records the server half of an Exchange, evicting the oldest entries until the Store is back inside its budget.
func (*Store) Attach ¶
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 ¶
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) NoteRouteWarning ¶
NoteRouteWarning records a warning against a host, ignoring one already held.
func (*Store) RouteWarnings ¶
RouteWarnings returns the per-host warnings, for `proximo status`.