98 lines
2.6 KiB
Markdown
98 lines
2.6 KiB
Markdown
# PostConvert – Robust Image & PDF → JPEG Conversion Service
|
||
|
||
PostConvert is a small, production-oriented HTTP service for converting **images and PDFs into JPEGs**, with strong emphasis on **robustness, predictable resource usage, and operational safety**.
|
||
|
||
It supports:
|
||
- JPEG → JPEG (resize + recompress)
|
||
- PNG / WebP / TIFF → JPEG
|
||
- HEIC / HEIF → JPEG (via WASM fallback)
|
||
- PDF → JPEG (first page or all pages as a ZIP)
|
||
|
||
The service is designed to run well in **containers, serverless-ish environments, and small VMs** where disk, memory, and runaway workloads matter.
|
||
|
||
---
|
||
|
||
## Primary Use Cases
|
||
|
||
- Normalize user uploads (receipts, photos, scans) into JPEG
|
||
- Resize and recompress images server-side for storage or ML pipelines
|
||
- Convert PDFs (receipts, invoices, statements) into images
|
||
- Handle HEIC uploads from iOS devices without native libheif dependencies
|
||
- Safely process untrusted user uploads with bounded resource usage
|
||
|
||
---
|
||
|
||
## Key Design Goals
|
||
|
||
- **Always JPEG out**
|
||
- **Bounded `/tmp` usage** (PDFs rendered page-by-page)
|
||
- **No stack traces leaked to clients**
|
||
- **Fast path for common formats**
|
||
- **Graceful abort on client disconnect**
|
||
- **Predictable limits** (size, pages, DPI, timeouts)
|
||
|
||
---
|
||
|
||
## Endpoints
|
||
|
||
### `POST /convert`
|
||
|
||
Converts a single image **or the first page of a PDF** to a JPEG.
|
||
|
||
#### Supported inputs
|
||
- JPEG, PNG, WebP, TIFF, etc. (anything Sharp can decode)
|
||
- HEIC / HEIF
|
||
- PDF (first page only)
|
||
|
||
#### Response
|
||
- `200 image/jpeg` on success
|
||
- JSON error on failure
|
||
|
||
---
|
||
|
||
### `POST /convert/pdf`
|
||
|
||
Converts **all pages of a PDF** into JPEGs and returns a ZIP archive.
|
||
|
||
Pages are rendered **one at a time** to keep disk usage bounded.
|
||
|
||
---
|
||
|
||
## Authentication
|
||
|
||
All endpoints require a bearer token.
|
||
|
||
```
|
||
Authorization: Bearer <CONVERTER_TOKEN>
|
||
```
|
||
|
||
---
|
||
|
||
## Image Resize & JPEG Options (Headers)
|
||
|
||
| Header | Type | Default | Description |
|
||
|------|-----|--------|-------------|
|
||
| `x-jpeg-quality` | `0–100` | `100` | JPEG compression quality |
|
||
| `x-max-dimension` | px | none | Max width/height, aspect preserved |
|
||
| `x-width` | px | none | Explicit output width |
|
||
| `x-height` | px | none | Explicit output height |
|
||
| `x-fit` | enum | `inside` | `inside`, `cover`, `contain`, `fill`, `outside` |
|
||
| `x-without-enlargement` | bool | `true` | Prevent upscaling smaller images |
|
||
|
||
---
|
||
|
||
## Environment Variables
|
||
|
||
| Variable | Default | Description |
|
||
|-------|--------|------------|
|
||
| `PORT` | `8080` | Server port |
|
||
| `CONVERTER_TOKEN` | (required) | Bearer auth token |
|
||
|
||
---
|
||
|
||
## Runtime Dependencies
|
||
|
||
- Node.js 18+
|
||
- `pdftoppm` (Poppler utils) **required for PDFs**
|
||
- Sharp native dependencies (per Sharp docs)
|