hivesolutions/headless

By hivesolutions

•Updated about 10 hours ago

Simple headless browser API.

Image

50K+

Overview Tags

hivesolutions/headless repository overview

⁠Headless⁠

Simple headless browser API to render images (PNG, JPEG, WebP, TIFF, BMP, etc.) and PDFs from plain HTML.

⁠Features

Capture of webpages as PNG and PDFs
Multiple back-end engines: Phantom.js⁠ and Puppeteer⁠

⁠Configuration

Name	Type	Default	Description
`HEADLESS_KEY`	`str`	`None`	Secret key that should be passed in protected calls so that the server-side "trusts" the client side (authentication).
`HOST`	`str`	`127.0.0.1`	Address the server listens on (`0.0.0.0` in the Docker images).
`PORT`	`int`	`3000`	Port the server listens on (`8080` in the Docker images).
`LEVEL`	`str`	`DEBUG`	Logging level (`INFO` in the Docker images).

⁠Usage

⁠Routes

Route	Method	Description
`/`	`GET`	Renders the page of `url` into the `format` requested and returns it (eg: `application/pdf`, `image/png`).
`/`	`POST`	Same as `GET`, the body of the request (any content type, up to 1 GB) is rendered as the HTML of the page when there's no `url`, otherwise it's sent as the payload of the request to `url` (see `method`).
`/info`	`GET`	Returns a JSON with the name and the version of Headless, the version of Node.js and the version of each engine.

The key (HEADLESS_KEY) is required by both / routes when configured, either as the key query parameter or in the X-Headless-Key header (preferred, as URLs end up in logs).

⁠Parameters

The query parameters of /, for the default engine (Puppeteer):

Name	Type	Default	Description
`url`	`str`	`https://www.google.com/`	URL of the page to render (URL encoded). When missing, a request with a body renders its body as HTML instead.
`format`	`str`	`png`	Format of the result: `pdf`, or an image format, `png`, `jpeg` and `webp` natively, `bmp`, `tiff` and `gif` re-encoded from PNG.
`page_format`	`str`	`A4`	Paper format of PDFs (eg: `A3`, `A4`, `A5`, `Letter`, `Legal`).
`prefer_css_page_size`	`str`	-	`1` sizes PDFs by the `@page` rule of the document (eg: `@page { size: A3; }`), using `page_format` for the pages without one. Otherwise `page_format` wins, scaling the pages of other sizes into it.
`print_background`	`str`	-	`0` leaves the backgrounds out of PDFs, which include them by default.
`wait_until`	`str`	`load`	Event the capture waits for: `load`, `domcontentloaded`, `networkidle0` (no network connections for 500 ms) or `networkidle2` (at most 2 connections for 500 ms).
`full_page`	`str`	-	`0` captures only the viewport in images, which capture the whole page by default.
`trim`	`str`	-	`1` crops the uniform borders of images.
`width`	`int`	`800`	Width of the viewport in pixels.
`height`	`int`	`600`	Not applied: the height of the viewport is the `width` (600 without `width`), see #20⁠.
`scale_factor`	`int`	`1`	Device scale factor (eg: `2` for images with twice the resolution).
`timeout`	`int`	`500`	Not applied: the navigation times out after the 30 seconds of Puppeteer, see #20⁠.
`cookie`	`str`	-	Cookie set for `url` as `name,value`, repeatable (eg: `cookie=a,1&cookie=b,2`). Each request renders in its own browser context, so its cookies never reach the other requests.
`method`	`str`	Method of the request	Method of the request to `url`. With `POST` or `PUT` the body of the request is sent as its payload, with its `Content-Type` and `Cache-Control` headers.
`reload`	`str`	-	`1` relaunches the browser before rendering, interrupting the renders of the other requests in progress.
`engine`	`str`	`puppeteer`	Engine of the render, `puppeteer` or `phantom` (when Phantom.js is installed).
`key`	`str`	-	Key of the server, when it has one (`HEADLESS_KEY`).

The Phantom engine (engine=phantom) reads url, format (png, gif, jpeg and jpg, or any format Phantom.js renders into a file, eg: pdf), page_format (A2 by default), zoom (1.0), viewport_width (1024) and viewport_height (768).

The HTML of a body has no URL of its own (about:blank), so its resources (stylesheets, fonts and images) must have absolute URLs, a <base href> or be inlined (eg: as data: URIs), and no cookies are sent with them.

The errors are returned as a JSON with the message and the status code of the error, eg: {"error": "Invalid key", "code": 500} for a missing or invalid key (500 is also the code of most failed renders) and {"error": "Route not found", "code": 404} for the other routes, with the stack of the error outside production (NODE_ENV).

⁠Examples

# renders a page into a PNG image of the whole page
curl -G "http://localhost:3000/" --data-urlencode "url=https://example.com/" -o page.png

# renders a page into an A4 PDF, waiting for the network to be idle
curl -G "http://localhost:3000/" --data-urlencode "url=https://example.com/" \
    -d format=pdf -d wait_until=networkidle0 -o page.pdf

# renders an HTML document into a PDF with the page size of its @page
# rule (eg: A3), sending the key in the header
curl -X POST "http://localhost:3000/?format=pdf&prefer_css_page_size=1" \
    -H "Content-Type: text/html" -H "X-Headless-Key: $HEADLESS_KEY" \
    --data-binary @page.html -o page.pdf

⁠Docker Images

Headless is available on Docker Hub⁠ with the following tags:

Tag	Description	Supported Architectures
`latest`	The most up-to-date stable version.	`amd64`
`debian`	Debian-based container for stability and security.	`amd64`
`chromium`	Container using chromium instead of chrome.	`amd64`, `arm/v7`, `arm64/v8`