How far a supplied PDF is allowed to unpack

In plain words

Written for anybody. It says what this puts on a sheet of paper, and asks nothing of you beyond that.

When you send a PDF along — a letterhead to print onto, or a page to place — that file is compressed, the way a zipped folder is. A compressed file can be built so that a very small parcel unpacks into something enormous, and a program that unpacks it without looking fills the machine and stops. So there is a ceiling: no single piece of a file you send may unpack beyond it. A file that asks for more is turned away at once, before a single byte of room is taken. You can raise the ceiling if you knowingly send very large pages, or lower it if you accept files from people you do not know.

For a developer

Written for somebody who writes the calling program: the model, the units, and the settings that carry the weight.

Written at the top level of a request, under "supplied_pdfs"

supplied_pdfs settles how the PDFs supplied alongside the request are read: the templates the pages are stamped onto, and the pages the items place. Its one key is the ceiling one stream of such a file may decompress to. The check happens before the room is taken, not after: a file holding a stream that asks for more is refused outright, so a small parcel built to unpack into gigabytes never gets the chance. Absent, the ceiling is the one the library reads a file at.

Every key, with its default

The reference: which keys are required, which are optional, what each one defaults to and which combinations the server declines.

supplied_pdfs — object, optional.
supplied_pdfs.expansion_limit — integer, optional, a number of bytes. The most one stream of a supplied PDF may decompress to. Absent, the library's own ceiling holds.

Scope: every PDF the request supplies, whether it is stamped onto or placed. It settles nothing about the document being written, only about the files being read.

A whole request that draws it

Post this as it stands and a PDF comes back. Nothing has been left out of it.

{
  "supplied_pdfs": { "expansion_limit": 33554432 },
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "pdf_page",
      "pdf": "letterhead",
      "page": 1,
      "rect": { "llx": 0, "lly": 0, "urx": 595.276, "ury": 841.89 }
    },
    {
      "type": "text",
      "rect": { "llx": 72, "lly": 700, "urx": 523, "ury": 740 },
      "content": ["Written over the sheet that was supplied"],
      "font": "sans",
      "font_size": 12
    }
  ]
}

The line that sends it, in three languages

The sheet, and what is laid under it

The size of the pages A size of its own for certain pages The areas a page states Which way up a page is shown How a page arrives, and how long it stands The headed paper under the pages

Where to go next

Every key of a request, in one page The other thirty-two settings of a request

See the prices See the examples

Glossary

PDF library: A piece of software your own programs use to write PDF documents. It has no window and no buttons: your program tells it what to draw, and it hands the finished file back. This site also calls it the engine, which is the same thing under another name. The server is a second program that holds the engine and answers whoever asks it for a document over the network, and the rendering service is that server running on our machines rather than on yours.
byte: The unit a file's weight is counted in, the way a parcel is counted in grams. A thousand of them make a kilobyte, and a million make a megabyte — the size of one photograph taken with a telephone. A one-page PDF here weighs between six thousand and a hundred and twenty thousand, so a hundred of them fit in the space of five photographs.
request: One call to the service: you send what the document should say, and get the document back. Your bill counts these calls, one for each document. The number of pages inside a document is never counted.
template: A PDF file made once and reused as the background of new pages: your letterhead, a plain sheet for the pages that follow, the page of terms you always attach at the end. The file is laid down exactly as it stands, to the millimetre, and the new text is written on top.

Every word the site explains