https://github.com/starptech/fay

Stateless, Fast and Reliable PDF rendering service.
https://github.com/starptech/fay

go golang html-to-pdf pdf pdf-generation playwright

Last synced: 3 months ago
JSON representation

Stateless, Fast and Reliable PDF rendering service.

• Host: GitHub
• URL: https://github.com/starptech/fay
• Owner: StarpTech
• License: mit
• Created: 2020-12-22T14:41:37.000Z (over 4 years ago)
• Default Branch: main
• Last Pushed: 2020-12-27T14:58:13.000Z (over 4 years ago)
• Last Synced: 2025-01-10T07:46:44.670Z (4 months ago)
• Topics: go, golang, html-to-pdf, pdf, pdf-generation, playwright
• Language: Go
• Homepage:
• Size: 6.54 MB
• Stars: 13
• Watchers: 4
• Forks: 4
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Contributing: .github/CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

README

        


    



Fay

Stateless, Fast and Reliable PDF rendering service.

Dockerhub · Load tests · Contributing

 


## Features

- Fast and reliable due to [Playwright](https://github.com/microsoft/playwright).

- Use Chromium 89.0.4344.0.

- Render any URL or static HTML to PDF.

- Sandbox mode with network and javascript disabled.

- Healthcheck endpoint.

- Ready to use docker image.

- Swagger endpoint.

## Installation

```

docker run --rm -p 3000:3000 starptech/fay

```

_The image is relatively big due to the playwright base image. This might be improved in the future. Versioning will be added soon as well._

## Endpoints

- `/convert` - **Converts a website to PDF document.**

  - `filename` (form,query, **default:** `"result.pdf"`): Filename of the resulting pdf.

  - `url` (form,query, **default:** `""`): The url of the website to convert.

  - `html` (file, **default:** `""`): Convert the HTML to PDF instead `url`.

  - `locale` (form,query, **default:** `en-US`): Browser locale.

  - `format` (form,query, **default:** `A4`): Page format.

  - `offline` (form,query, **default:** `false`): Disable network connectivity.

  - `media` (form,query, **default:** `print`): Page media emulation.

  - `javascript` (form,query, **default:** `true`): Enable javascript on the website.

  - `marginTop,marginRight,marginBottom,marginLeft` (form,query, **default:** `0`): Set page margin.

  - `headerTemplate` (file, **default:** ``): Header template.

  - `footerTemplate` (file, **default:** ``): Footer template.

- `/ping` - **Check if the server is ready to accept requests.**

- `/metrics` - **Returns informations about the current load and health of the server.**

- `/swagger/index.html` - **Swagger introspection**

For detail description of the pdf options check the [playwright](https://playwright.dev/docs/api/class-page?_highlight=pdf#pagepdfoptions) documentation or the [swagger documentation](/docs/swagger.yaml).

## Environment variables

- `FAY_MAX_ACTIVE_PAGES` (**default:** `0`): Controls how many pages can be opened at the same time before responding with status code `429`.

## Scalability

Fay is staless and can be scaled infinitely. If you run fay on your infrastructure you should keep some things in mind.

Fay will open as many pages as possible depending on the available host resources. You can control the maximum active pages by the environment variable `FAY_MAX_ACTIVE_PAGES=20`. As a general thumb you can calculate the base memory consumption in the following way. The chrome instance takes around `~45MB`. Every additional page `~15MB`. In case of the limit is reached the server will respond with status code `429`. The client is responsible to implement a backoff strategy.

A single fay instance (static HTML mode) is capable to serve 20 parallel virtual users with an average request duration of `~0.5s`. The memory consumption was `~500MB`.

Load tests are part of our CI. For more informations check the [load-test](./loadtesting/README.md).

## Best practice

In order to produce reproducible results try to avoid downloading external resources you can't control and executing javascript. Use the options `offline=true` and `javascript=false` to enforce that. You can inline images / fonts / styles with base64 in the document. Fonts can also be embedded in the docker image to make them accesible to the chromium browser.

## Credits

- https://github.com/mxschmitt/playwright-go

- https://github.com/thecodingmachine/gotenberg

- Elf icon icon by Icons8