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 ¶
This section is empty.
Variables ¶
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 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. A path it
// does not know is answered 404, which is what the document would see
// from a real server.
Files func(path string) (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
}
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.
Source Files