Renders a structured Document — or an incrementally accumulating Document.Page stream — into a PDF and serves it live over HTTP and WebSocket, optionally POSTing every rendered document to a destination of its own. Each block is drawn inside the box it occupies on its source page, so the rendered PDF keeps the page's layout.
Typical backends
A PDF parsed by input_pdf_file into a Document is re-served as a downloadable PDF a browser or client GETs on the egress endpoint.
A scanned document's page layout is detected, and the recognised blocks are served as a PDF whose text sits where the layout put it.
Caveats
- I/O contractInput is a oneof of
Document and Document.Page. The Document arm renders all pages at once; the Document.Page arm accumulates arriving pages and re-renders the served PDF after each page. - Hard constraint
transports is fixed at startup and accepts only the http and websocket modes, run together. GET / (and GET /document.pdf) return the current PDF as application/pdf; websocket clients receive the full PDF as a binary frame on every update. - Parameter interaction
render selects what a page carries. "image" embeds the page raster alone. "text" draws the page's blocks alone on a blank sheet, each inside its own box. "replace" embeds the raster, repaints every text box with the background colour sampled around it and draws the block text back into that box, which changes the wording while rules, tables, logos and photographs stay in place. "both" draws the block text over the untouched raster, showing the page's own glyphs and the block text together. - Parameter interactionDrawn text is real PDF text: it is shaped, embedded as a font subset with a ToUnicode mapping, and stays selectable and searchable. Every typographic property is taken from the document rather than inferred: a run is set at the size, face, weight, slope and colour it states, a paragraph is leaded and aligned as it states, and a run that states none of these is set in the component's own face at the paragraph's measure. Wording that runs longer than the text it replaces takes the lines it needs and the blocks below it move down by one line per extra line, which keeps a translated page readable instead of trading type size for the footprint the source wording had.
- Parameter interactionEach served document carries an ETag over its bytes, and a request holding that ETag is answered 304. A reader that has been told a new document exists can therefore wait for it without re-reading the one it already has.
- Parameter interaction
url POSTs each rendered document as application/pdf as well as serving it, so a destination that cannot poll the port — a recorder, say — receives every version of the document as it is published, the last of them the finished one. Posting is independent of transports: both happen. An empty url posts nothing. Sending runs on its own thread and never delays rendering; a destination that falls behind loses the oldest held documents rather than growing the queue, and a refused POST is logged without a retry. headers travels verbatim with each POST, which is where a destination's credentials go — a recording tap refuses a POST that arrives without the token it issued. - FallbackEach page's image_url raster is embedded as a full-bleed JPEG at
jpeg_quality; a page with no raster is a blank sheet sized from its declared width and height. GET / answers 503 until the first page renders. - LimitationA codepoint is drawn with a face that can spell it: script chooses the face, and where that face has no glyph the first bundled face that does is used instead, so a word can be set across two faces. Mathematics, arrows and set notation read as Latin and are only partly covered by the body face; the bundled Noto Sans, Noto Sans Math and Noto Sans Symbols cover the rest, and between them every character a Symbol run can respell to has a face that can set it. A codepoint no bundled face carries is drawn as a missing glyph rather than silently dropped.
- Limitation
max_pages bounds the served PDF; a Document.Page stream drops the oldest page past the bound and a whole Document is truncated to that many pages. - LimitationBundled faces cover Latin, Greek, Cyrillic, CJK, Arabic, Hebrew, Devanagari and Thai. Latin is set in Liberation Sans, which carries Helvetica's and Arial's metrics, so text drawn over a page set in either keeps its letterforms and its line breaks. Bidirectional reordering across a mixed left-to-right and right-to-left line is not applied: a run is shaped in its own direction.
