Skip to content
You are reading the documentation of the unreleased development version.Go to the latest release

Worker protocol

fagus worker renders documents for a caller over standard input and output. One process serves any number of documents one after another, with fonts loaded and caches warm, so a document costs the time it takes to render it and nothing more. The PHP package uses this protocol; any other language can too.

Frames#

Every message is a frame:

Bytes Content
4 length of the rest of the frame, unsigned, little-endian
1 message type
4 length of the JSON header, unsigned, little-endian
n JSON header (UTF-8)
… data blocks, one after another

The header's blobs array lists the lengths of the data blocks that follow it; frames without data have no blobs. Data travels as raw bytes, never base64. Frames are at most 1 GiB. A frame the worker cannot read (too long, a header that is not JSON, data blocks longer than the frame) ends the worker with exit code 1 and the reason on its error output.

Messages#

Type Direction Header Data
H hello worker → caller protocol, version –
R render caller → worker the document, see below HTML, stylesheets, resources, attachments, invoice XML
? ask worker → caller id, url –
r resource caller → worker found the resource, if found
P PDF worker → caller id, pages, diagnostics, timings the PDF
E error worker → caller id (if known), message, diagnostics –
F font caller → worker – a font file (TTF, OTF, TTC, WOFF, WOFF2)
K done worker → caller faces –

The worker sends H when it starts; its protocol is 1 and its version that of the binary. A caller that does not know the protocol version stops there. The worker ends with exit code 0 when its input closes. A message of an unknown type gets an E without id.

Rendering#

The caller sends R and reads frames until it gets P or E. Meanwhile the worker may ask for resources it needs with ?, if the request allows it (ask); the caller answers each one with r, with the data or found: false. Nothing else may come in between.

The header of R; fields other than id and html may be left out:

json
{
  "id": 1,
  "html": 0,
  "xhtml": false,
  "base": "/app/resources/pdf",
  "root": "/app/resources",
  "stylesheets": [{ "name": "app.css", "blob": 1 }],
  "resources": [{ "url": "logo.png", "blob": 2 }],
  "ask": true,
  "conformance": "3b",
  "tagged": true,
  "accessible": false,
  "attachments": [{ "name": "data.csv", "mime": "text/csv", "relationship": "supplement", "description": "Rohdaten", "blob": 3 }],
  "facturX": { "blob": 4, "profile": "en16931" },
  "created": "2026-11-02T12:00:00Z",
  "blobs": [5120, 812, 20431, 96, 4187]
}
  • html, blob: the index of a data block. The HTML and style sheets must be UTF-8.
  • xhtml: whether the markup is XHTML, parsed as XML as browsers parse .xhtml files (false if left out).
  • base: the directory that relative URLs resolve against; files are read from there (and from root, if given, which must contain it). URLs that start with / resolve against root (or base), as on a web server. Without base the worker reads no files.
  • resources: data the document may use, by URL as written in the document. The documents of frames (<iframe src>, <object data>) ask for their resources by their URLs resolved against the frame's URL, relative to the document (sub/style.css for style.css in sub/page.html).
  • stylesheets: style sheets added after those of the document; name is the source that diagnostics name.
  • ask: whether the worker asks for resources it does not have (false if left out). A resource is looked for as a data: URL, in resources, by asking the caller, then as a file, in that order.
  • conformance: 2b, 2u, 2a, 3b, 3u or 3a for PDF/A.
  • tagged: whether the PDF is tagged, with the logical structure of the document (true if left out).
  • accessible: whether the PDF conforms to PDF/UA-1 (and is tagged). The document needs a title, a language and alternative text for every image; otherwise the answer is E.
  • attachments: name and mime are required. relationship is source, data, alternative, supplement or unspecified (unspecified if left out). description may be left out (or be null or empty): PDF/A-3 and PDF/UA require one, so the worker then describes the file by its name, as fagus render --attach does.
  • facturX: the invoice XML of a ZUGFeRD or Factur-X invoice; profile (minimum, basicwl, basic, en16931, extended, xrechnung) is read from the XML if left out (en16931 if the XML declares none).
  • created: the creation date, as 2026-11-02T12:00:00Z or with an offset from UTC (2026-11-02T13:00:00+01:00), which the worker applies; the current time if left out. A date without an offset is taken as UTC.

A request the worker cannot use (a missing data block, an unknown PDF/A level, relationship or profile, an invalid date) is answered with E and its reason, as is a document that does not meet PDF/A or PDF/UA.

The header of P:

json
{
  "id": 1,
  "pages": 3,
  "diagnostics": [
    { "severity": "warning", "code": "css.unknown-property", "message": "unknown property `colr`; the declaration is ignored", "source": "<style> 1", "line": 12, "column": 3 }
  ],
  "timings": { "parse": 0.12, "style": 0.31, "layout": 0.44, "paint": 0.02, "pdf": 0.71 },
  "blobs": [48213]
}

Times are in milliseconds. severity is info, warning or error; line and column are 0 when unknown.

The header of E has the message and a diagnostics array of the same form. For a document that could not be rendered (it does not meet PDF/A or PDF/UA, or the PDF could not be written), it holds the diagnostics found until then, which often explain the failure; for a request the worker cannot use, an F it cannot read and a message of an unknown type, it is empty.

Fonts#

F adds a font to the worker for all later documents; the worker answers with K and the number of faces it found, or E (without id). Fonts can also be given on the command line (fagus worker --font-dir fonts, and --system-fonts for the fonts installed on the machine) or come with a document through @font-face. --sans-serif, --serif and --monospace name the families of the generic families.

Language of form controls#

fagus worker --locale de-DE sets the language of the texts form controls show of their own (button labels, the placeholders and formats of date fields) in documents that give a control no lang; without it they are American English, as in Chrome by default. Text without lang is shaped in that language as well, as Chrome shapes it in the language of its user interface.