xc-print v1.0.6

Server for XML to PDF converter

Provides REST API for converting XML to PDF.

Usage

Before initial start or after any update, run npm install to update dependencies

To start HTTP server, run

npm start

This command will compile TypeScript sources and start HTTP server at http://localhost:9000.

The server provides following endpoints:

POST /convert/pdf

Converts given XML file to PDF, applying stylesheet transforms. A request must be sent as form-data with the following fields:

• xmlFile: XML file to convert. Must be sent a string (file contents) or Buffer (file binary).
• cssFile (optional): list of file paths or file binaries with CSS styles that must be applied to XML file. If sent as string, it will be treated as file path relative to ./css folder of current repo, if sent as file binary, will be stored into temp dir first. In order to pass multiple CSS files, add [] at the end of each field entry, e.g. cssFile[]=...&cssFile[]=....
• cssText (optional): Inline CSS stylesheet to apply to XML.
• xsltFile (optional): an XSLT file to apply to XML, either relative path to repo’s ./xslt dir for file binary.
• engine (optional): engine to use to generate PDF. Supported values are prince (default) and puppeteer.

Endpoint will return PDF file binary on success or error if failed.

Usage example with curl:

curl -F 'xmlFile=@./116hr6201ih-116hr6201enr-compare.xml' \
   -F 'cssFile[]=uslm.css' \
   -F 'cssFile[]=uslm-reports.css' \
   -F 'cssFile[]=comparison-print.css' \
   --output result.pdf http://localhost:9000/convert/pdf

Restricting access to third-parties

By default, xc-print service handles all incoming requests. In order to restrict access to unauthorized third-parties, you must provide service a list of secret keys.

Secret key is just a random string, long enough to complicate brute forcing. If secrets are provided, all incoming HTTP requests must contain Authentication HTTP header with one of the secret keys.

A workflow with secret keys is following:

• Create secrets.json file somewhere outside of this repo. The file should contain an array for keys, for example ["secret1", "secret2"]. Use online services like https://www.uuidgenerator.net to generate random strings.
• Start xc-print service with -s command-line option which points to secrets.json file:

npm start -- -s path/to/secrets.json

When service starts, you should see log “Server started at http://localhost:9000 with secrets”.

• Give third-party one of the secret keys.
• All incoming requests should have Authentication HTTP header to pass validation:

curl -F 'xmlFile=@./116hr6201ih-116hr6201enr-compare.xml' \
   -F 'cssFile[]=uslm.css' \
   -F 'cssFile[]=uslm-reports.css' \
   -F 'cssFile[]=comparison-print.css' \
   -H 'Authentication: secret1' \
   --output result.pdf http://localhost:9000/convert/pdf

To add or revoke keys, simply edit secrets.json file and and restart service.

CLI options

Service supports the following CLI options:

• -p, --port – HTTP port for server, default is 9000.
• -s, --secrets – path to JSON file with secret keys. If specified, all incoming HTTP requests should contain Authentication HTTP header with one of the secret keys.

Example:

npm start -- -p 8901 -s path/to/secrets.json
# Server started at http://localhost:8901 with secrets

Fonts: Linux does not have MS Fonts by default

Linux servers have a limited set of fonts by default. In order to use any MS Fonts they must be installed on the server

• http://mscorefonts2.sourceforge.net/

$sudo yum install curl cabextract xorg-x11-font-utils fontconfig

Then: $sudo rpm -i https://downloads.sourceforge.net/project/mscorefonts2/rpms/msttcore-fonts-installer-2.6-1.noarch.rpm

Debugging

In order to debug errors, start server with DEBUG=* env variable: it will provide log from different server sub-systems:

DEBUG=* npm start

Docker

The local Dockerfile can be used to build the image (docker build ./). To run:

podman run -d -t -i -p 9000:9000 -v "xcprintlicense:/app/vendor/prince/license" docker.io/xcential/xcprint:latest&