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:
{
"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.xhtmlfiles (falseif left out).base: the directory that relative URLs resolve against; files are read from there (and fromroot, if given, which must contain it). URLs that start with/resolve againstroot(orbase), as on a web server. Withoutbasethe 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.cssforstyle.cssinsub/page.html).stylesheets: style sheets added after those of the document;nameis the source that diagnostics name.ask: whether the worker asks for resources it does not have (falseif left out). A resource is looked for as adata:URL, inresources, by asking the caller, then as a file, in that order.conformance:2b,2u,2a,3b,3uor3afor PDF/A.tagged: whether the PDF is tagged, with the logical structure of the document (trueif 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 isE.attachments:nameandmimeare required.relationshipissource,data,alternative,supplementorunspecified(unspecifiedif left out).descriptionmay be left out (or benullor empty): PDF/A-3 and PDF/UA require one, so the worker then describes the file by itsname, asfagus render --attachdoes.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 (en16931if the XML declares none).created: the creation date, as2026-11-02T12:00:00Zor 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:
{
"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.