Documentation
¶
Overview ¶
Package headless draws a document in a headless Chrome the platform reaches over the DevTools protocol, with the browser cut off from the network: every request the document makes is answered by the platform itself.
A document saved to the platform is written by a person and runs inside the network perimeter when it is drawn here, so what it can reach is the whole question. Three layers stand between a document and the network, and each was shown to hold on its own against a renderer with the browser's own private-network protection switched off (see the integration tests):
- Every render runs in its own browser context whose proxy is a dead address. Traffic the platform does not answer -- a WebSocket, anything a worker the platform could not arm tries -- goes to that proxy and fails. Loopback is not exempt, so a document cannot reach the renderer's own DevTools port or the platform beside it.
- The page is armed before it navigates: every request it, its frames and its workers make is paused and answered here. Files the page needs are served from the platform's own copies; a public URL is fetched by the platform through a guarded client that refuses internal addresses; the rest are refused.
- The WebSocket, WebTransport and WebRTC constructors are removed from every page, frame and worker before its first instruction runs.
Network.setBlockedURLs is deliberately not used: it does not stop a WebSocket, and a block that does not block is worse than none.
Index ¶
Constants ¶
const ( // MaxPDFBytes bounds a printed document. A PDF is read from the renderer // in chunks rather than in one protocol message, so this, not the // message cap, is what limits it. MaxPDFBytes = 256 << 20 )
Variables ¶
var ErrIncomplete = errors.New("a file the document needs could not be fetched")
ErrIncomplete marks a render whose document named a public file it needs and the platform could not get it. The document is not at fault and the renderer is up, so a caller tries the document again later rather than recording it as not drawable.
var ErrPDFTooLarge = errors.New("headless: the printed document is larger than the platform returns")
ErrPDFTooLarge is a printed document past MaxPDFBytes.
ErrUnavailable marks a render that failed because the renderer could not be reached or went away mid-render, as opposed to a document that could not be drawn. A caller retries the first later and records the second.
Functions ¶
This section is empty.
Types ¶
type File ¶
File is one same-origin file a page loads. Status and Header are the response a route gave beyond its body: a 206 with its Content-Range for a ranged read, and the CORS headers a read from a sandboxed frame, whose origin is opaque, is checked against. A zero Status is 200.
type Page ¶
type Page struct {
// Document is served as the page itself.
Document []byte
// Files answers a request for a path on the page's own origin, given the
// request's headers. A path it does not know is answered 404, which is
// what the document would see from a real server.
Files func(path string, header http.Header) (File, bool)
// Ready is a JavaScript expression evaluating to a Promise that resolves
// to "" once the page is drawn, or to the reason it cannot be.
Ready string
// Width and Height are the page's viewport in CSS pixels.
Width, Height int
// Scale is image pixels per CSS pixel: 400x300 at 2 is an 800x600 PNG,
// 1280x960 at 0.625 is one too. Above 1 the page is painted at that pixel
// density; below 1 it is painted at full size and reduced with a
// resampling filter, because a browser painting a page at a fraction of
// its size draws text a few pixels tall and illegible (#1789). Zero is 1.
Scale float64
// Dark emulates a reader who prefers a dark color scheme.
Dark bool
// Transparent captures the page with no default background, so whatever
// the document leaves unpainted is transparent in the PNG (#1991).
Transparent bool
// RequireSubresources fails the render with ErrIncomplete when a public
// stylesheet or script the document named could not be fetched -- the
// network failed, or its server answered 429 or 5xx -- instead of
// capturing a page drawn without it (#2122). A file its server says does
// not exist is the document's own, and is drawn without. A file of the
// page's own origin that Files answers with a 5xx fails it the same way,
// whatever its type (#2218).
RequireSubresources bool
}
Page is one document to draw and everything it may load from its own origin.
type Renderer ¶
type Renderer struct {
// contains filtered or unexported fields
}
Renderer draws pages in the headless Chrome at endpoint.
func New ¶
New returns a renderer for the browser at endpoint, the renderer's DevTools address (http://127.0.0.1:9222 or ws://127.0.0.1:9222). public fetches the public URLs a document names and must refuse internal addresses; nil refuses every URL outside the page's own origin.
func (*Renderer) Ping ¶
Ping reports whether the renderer answers, without drawing anything: a caller holding work checks it once rather than claiming work it cannot do.
func (*Renderer) PrintPDF ¶ added in v1.139.0
PrintPDF loads p as Render does and prints it to PDF, with its backgrounds and at the page size its own @page rule declares (#1983). The page is printed as it stands once it reports itself ready, so a document that lays itself out for print -- a slide deck in its print view -- decides what each page holds.
func (*Renderer) Render ¶
Render draws p and returns the screenshot as a PNG.
It returns when the page reports itself ready or ctx ends. A page whose script never lets it settle is abandoned at ctx's deadline, and its browser context -- with every frame and worker in it -- is disposed either way. A renderer that does not confirm the disposal fails the render as unavailable, so a caller does not draw the next page in a browser still busy with this one (#1868).
Source Files