Documentation
¶
Overview ¶
Package snapshot records a capture so a graph can be rebuilt without a browser, a network, or the site.
Why this matters more than it looks ¶
The problem space has an endless tail of browser quirks and animation-library behaviours, each one discovered by a site breaking. Two recent examples -- secondary tabs never compositing and therefore starving requestAnimationFrame, and --in-process-gpu with SwiftShader killing frame production outright -- appear in no documentation anywhere.
Without snapshots, every bug report is "this site extracts wrong", and reproducing it means the maintainer needs the site to still be up, serving the same content, to the same Chromium build, on the same platform. Half of those conditions expire within a week.
With snapshots, a user attaches one file and the maintainer reproduces the entire graph stage offline and deterministically. It is also what makes golden-file tests possible at all: extraction quality regressions are silent, and a diff against a stored artifact is the only cheap way to catch them.
The snapshot deliberately stores the *capture*, not the artifact. Storing the artifact would only prove what the graph produced last time; storing the capture lets the whole graph stage be re-run against new code.
Index ¶
Constants ¶
const Ext = ".sieve"
Ext is the conventional file extension.
const FormatVersion = 1
FormatVersion is bumped when the snapshot layout changes incompatibly.
Variables ¶
var ErrPrivateSession = fmt.Errorf(
"refusing to record a snapshot of an authenticated session: " +
"the resulting file would contain content from behind a login and is " +
"intended to be attached to bug reports. Re-run without --profile, or " +
"pass --allow-private-snapshot if you have checked the contents yourself")
ErrPrivateSession is returned when a snapshot is requested for a session that was authenticated. Refusing is the correct default: a trace file is something a user attaches to a public issue, and a page from behind a login has no business in one.
Functions ¶
func DefaultPath ¶
DefaultPath derives a snapshot filename from a URL.
Types ¶
type Snapshot ¶
type Snapshot struct {
FormatVersion int `json:"format_version"`
RecordedAt time.Time `json:"recorded_at"`
RequestedURL string `json:"requested_url"`
FinalURL string `json:"final_url,omitempty"`
Status int64 `json:"status,omitempty"`
// Trace is the complete set of inputs that determined the render. A
// snapshot without it is not replayable, only inspectable.
Trace any `json:"trace"`
// Merged is the deduplicated capture: the input to the graph stage.
Merged *capture.Merged `json:"merged"`
// Scene and Libraries are the page-level probes.
Scene *capture.SceneIntrospection `json:"scene,omitempty"`
Libraries []string `json:"libraries,omitempty"`
// StaticHTML is the served document, retained so tier-0 extraction can be
// replayed too and so the escalation decision can be re-scored.
StaticHTML string `json:"static_html,omitempty"`
// Tier is the escalation tier the original run settled on.
//
// It is not derivable from anything else in the snapshot -- the capture
// looks the same whether it was reached by rendering or by sweeping -- and
// without it a replayed artifact reports an empty tier, which is the one
// field a reader consults to know how hard the page was to read. Optional,
// so snapshots written before this still load.
Tier string `json:"tier,omitempty"`
Notes []string `json:"notes,omitempty"`
// Redacted records that content was removed before writing. A snapshot from
// an authenticated session must never be attachable to a public bug report
// with the session's contents intact.
Redacted bool `json:"redacted,omitempty"`
RedactionReason string `json:"redaction_reason,omitempty"`
}
Snapshot is a recorded capture plus everything needed to interpret it.
type WriteOptions ¶
type WriteOptions struct {
// Private marks the session as authenticated.
Private bool
// AllowPrivate overrides the refusal, for a user who has decided the
// contents are safe to share.
AllowPrivate bool
// IncludeHTML retains the served document. It is the largest part of a
// snapshot and the most likely to carry something personal, so it is opt-in
// for private sessions even when they are allowed.
IncludeHTML bool
}
WriteOptions controls recording.
Source Files