orator-conversion 1.0.0

package/.dockerignore

@@ -0,0 +1,15 @@
+node_modules
+npm-debug.log*
+.nyc_output
+coverage
+*.lcov
+.git
+.gitignore
+.dockerignore
+docs
+test
+debug/Post*.sh
+*.md
+LICENSE
+.env
+.env.*

package/.vscode/launch.json

@@ -0,0 +1,47 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Launch Debug Harness",
+            "type": "node",
+            "request": "launch",
+            "outputCapture": "std",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "cwd": "${workspaceFolder}/debug/",
+            "program": "${workspaceFolder}/debug/Harness.js",
+            "presentation": {
+                "hidden": false,
+                "group": "",
+                "order": 1
+            }
+        },
+        {
+            "name": "Mocha Tests",
+            "args": [
+                "-u",
+                "tdd",
+                "--timeout",
+                "999999",
+                "--colors",
+                "${workspaceFolder}/test"
+            ],
+            "internalConsoleOptions": "openOnSessionStart",
+            "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
+            "request": "launch",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "type": "pwa-node",
+            "presentation": {
+                "hidden": false,
+                "group": "",
+                "order": 2
+            }
+        }
+    ]
+}

package/Dockerfile

@@ -0,0 +1,60 @@
+# Orator File Translation
+# Production image for file format conversion (image + PDF page extraction)
+#
+# Ubuntu is preferred over Alpine for PDF rendering because:
+#   - poppler-utils has better font rendering with glibc
+#   - More complete font packages for accurate PDF rasterization
+#   - sharp (libvips) builds more reliably on Debian-based images
+#   - pdftk-java is readily available
+#
+# Build:
+#   docker build -t orator-conversion .
+#
+# Run:
+#   docker run -p 8765:8765 orator-conversion
+#
+# Test:
+#   curl -X POST --data-binary @photo.jpg \
+#     -H "Content-Type: application/octet-stream" \
+#     http://localhost:8765/conversion/1.0/image/jpg-to-png -o photo.png
+
+FROM node:22-bookworm-slim
+
+LABEL maintainer="steven velozo <steven@velozo.com>"
+LABEL description="Orator File Translation - file format conversion service"
+
+# Install system dependencies for PDF rendering and image processing
+#   poppler-utils  - provides pdftoppm for PDF page rasterization
+#   pdftk-java     - provides pdftk for PDF page extraction
+#   fonts-dejavu   - base fonts for PDF rendering
+#   fontconfig     - font configuration for consistent rendering
+RUN apt-get update \
+	&& apt-get install -y --no-install-recommends \
+		poppler-utils \
+		pdftk-java \
+		fonts-dejavu-core \
+		fontconfig \
+	&& rm -rf /var/lib/apt/lists/*
+
+# Rebuild the font cache so pdftoppm can find system fonts
+RUN fc-cache -f -v
+
+WORKDIR /usr/src/app
+
+# Copy package files first for better layer caching
+COPY package.json ./
+
+# Install all dependencies (including devDependencies needed for the harness)
+RUN npm install --production=false
+
+# Copy application source
+COPY source/ ./source/
+COPY debug/Harness.js ./debug/Harness.js
+
+EXPOSE 8765
+
+# Health check against one of the conversion endpoints
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+	CMD node -e "const h=require('http');const r=h.request({hostname:'127.0.0.1',port:8765,path:'/conversion/1.0/image/jpg-to-png',method:'POST',timeout:3000},(s)=>{process.exit(s.statusCode===400?0:1)});r.on('error',()=>process.exit(1));r.end();"
+
+CMD ["node", "debug/Harness.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Steven Velozo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# Orator File Translation
+
+> File format conversion endpoints for Orator service servers
+
+Orator File Translation provides a simple way to add file format conversion endpoints to an Orator web server. It ships with built-in image converters (JPG to PNG, PNG to JPG), PDF page extraction (PDF to PNG/JPG via pdftoppm), and supports registering custom converters for any file format. All routes are versioned.
+
+## Features
+
+- **Image Conversion** - Convert between JPG and PNG formats via HTTP POST endpoints
+- **PDF Page Extraction** - Extract individual pages from PDFs as PNG or JPEG images
+- **Versioned Routes** - All endpoints include a configurable version segment
+- **Extensible** - Register custom converters for any file format via `addConverter()`
+- **Configurable** - Settings via constructor options or Fable settings
+- **Size Limits** - Configurable maximum file size to prevent abuse
+- **Fable Service Provider** - Registers as a standard Fable service
+
+## Quick Start
+
+```javascript
+const libFable = require('fable');
+const libOrator = require('orator');
+const libOratorServiceServerRestify = require('orator-serviceserver-restify');
+const libOratorFileTranslation = require('orator-conversion');
+
+const _Fable = new libFable({
+	Product: 'MyConversionServer',
+	APIServerPort: 8080
+});
+
+// Set up Orator with Restify
+_Fable.serviceManager.addServiceType('Orator', libOrator);
+_Fable.serviceManager.addServiceType('OratorServiceServer', libOratorServiceServerRestify);
+_Fable.serviceManager.instantiateServiceProvider('Orator');
+_Fable.serviceManager.instantiateServiceProvider('OratorServiceServer');
+
+// Set up file translation
+_Fable.serviceManager.addServiceType('OratorFileTranslation', libOratorFileTranslation);
+_Fable.serviceManager.instantiateServiceProvider('OratorFileTranslation');
+
+// Initialize and start
+_Fable.Orator.startService(
+	() =>
+	{
+		_Fable.OratorFileTranslation.connectRoutes();
+		// POST http://localhost:8080/conversion/1.0/image/jpg-to-png
+		// POST http://localhost:8080/conversion/1.0/image/png-to-jpg
+		// POST http://localhost:8080/conversion/1.0/pdf-to-page-png/:Page
+		// POST http://localhost:8080/conversion/1.0/pdf-to-page-jpg/:Page
+	});
+```
+
+## Installation
+
+```bash
+npm install orator-conversion
+```
+
+### System Dependencies
+
+PDF page extraction requires `pdftoppm` (part of the poppler-utils package):
+
+```bash
+# macOS
+brew install poppler
+
+# Debian/Ubuntu
+apt-get install poppler-utils
+```
+
+## Configuration
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `RoutePrefix` | string | `"/conversion"` | URL prefix for conversion endpoints |
+| `Version` | string | `"1.0"` | Version segment in route URLs |
+| `LogLevel` | number | `0` | Logging verbosity (higher = more output) |
+| `MaxFileSize` | number | `10485760` | Maximum upload size in bytes (default 10MB) |
+| `PdftkPath` | string | `"pdftk"` | Path to the pdftk binary |
+| `PdftoppmPath` | string | `"pdftoppm"` | Path to the pdftoppm binary |
+
+Settings can also be provided via Fable settings:
+
+| Fable Setting | Maps To |
+|---------------|---------|
+| `OratorFileTranslationRoutePrefix` | `RoutePrefix` |
+| `OratorFileTranslationVersion` | `Version` |
+| `OratorFileTranslationLogLevel` | `LogLevel` |
+| `OratorFileTranslationMaxFileSize` | `MaxFileSize` |
+| `OratorFileTranslationPdftkPath` | `PdftkPath` |
+| `OratorFileTranslationPdftoppmPath` | `PdftoppmPath` |
+
+## API
+
+### connectRoutes()
+
+Register POST endpoints on the Orator service server for each registered converter. Routes are versioned: `{RoutePrefix}/{Version}/{converterPath}`. Call this after Orator has been started.
+
+```javascript
+_Fable.OratorFileTranslation.connectRoutes();
+```
+
+### addConverter(pPath, fConverter)
+
+Register a custom converter. The path becomes part of the endpoint URL (`{RoutePrefix}/{Version}/{pPath}`). The converter function receives the input buffer, the request object, and a callback.
+
+```javascript
+_Fable.OratorFileTranslation.addConverter('document/csv-to-json',
+	(pInputBuffer, pRequest, fCallback) =>
+	{
+		let tmpCSV = pInputBuffer.toString('utf8');
+		let tmpJSON = convertCSVToJSON(tmpCSV);
+		return fCallback(null, Buffer.from(JSON.stringify(tmpJSON)), 'application/json');
+	});
+```
+
+### extractPdfPage(pPdfBuffer, pPageNumber, fCallback)
+
+Extract a single page from a PDF buffer using pdftk, returning the single-page PDF as a buffer.
+
+### renderPdfPageToImage(pPdfBuffer, pPageNumber, pFormat, fCallback)
+
+Render a specific page of a PDF to an image buffer using pdftoppm. The `pFormat` parameter can be `'png'` or `'jpeg'`.
+
+## Endpoints
+
+All endpoints are versioned. Conversion endpoints accept raw binary data via POST and return the converted file:
+
+```bash
+# Convert JPG to PNG
+curl -X POST --data-binary @photo.jpg \
+	-H "Content-Type: application/octet-stream" \
+	http://localhost:8080/conversion/1.0/image/jpg-to-png \
+	-o photo.png
+
+# Convert PNG to JPG
+curl -X POST --data-binary @image.png \
+	-H "Content-Type: application/octet-stream" \
+	http://localhost:8080/conversion/1.0/image/png-to-jpg \
+	-o image.jpg
+
+# Extract page 1 from a PDF as PNG
+curl -X POST --data-binary @document.pdf \
+	-H "Content-Type: application/octet-stream" \
+	http://localhost:8080/conversion/1.0/pdf-to-page-png/1 \
+	-o page1.png
+
+# Extract page 3 from a PDF as JPEG
+curl -X POST --data-binary @document.pdf \
+	-H "Content-Type: application/octet-stream" \
+	http://localhost:8080/conversion/1.0/pdf-to-page-jpg/3 \
+	-o page3.jpg
+```
+
+## Documentation
+
+Full documentation is available in the [`docs`](./docs) folder, or served locally:
+
+```bash
+npx docsify-cli serve docs
+```
+
+## Related Packages
+
+- [orator](https://github.com/stevenvelozo/orator) - Main Orator service abstraction
+- [orator-serviceserver-restify](https://github.com/stevenvelozo/orator-serviceserver-restify) - Restify service server
+- [fable](https://github.com/stevenvelozo/fable) - Service provider framework

package/debug/Harness.js

@@ -0,0 +1,48 @@
+const libFable = require('fable');
+
+const defaultFableSettings = (
+	{
+		Product: 'Orator-FileTranslation',
+		ProductVersion: '1.0.0',
+		APIServerPort: 8765
+	});
+
+let _Fable = new libFable(defaultFableSettings);
+
+_Fable.serviceManager.addServiceType('OratorServiceServer', require('orator-serviceserver-restify'));
+_Fable.serviceManager.instantiateServiceProvider('OratorServiceServer', {});
+
+_Fable.serviceManager.addServiceType('Orator', require('orator'));
+let _Orator = _Fable.serviceManager.instantiateServiceProvider('Orator', {});
+
+const libOratorFileTranslation = require('../source/Orator-File-Translation.js');
+_Fable.serviceManager.addServiceType('OratorFileTranslation', libOratorFileTranslation);
+_Fable.serviceManager.instantiateServiceProvider('OratorFileTranslation', { LogLevel: 2 });
+
+let tmpAnticipate = _Fable.newAnticipate();
+
+tmpAnticipate.anticipate(_Orator.initialize.bind(_Orator));
+
+tmpAnticipate.anticipate(
+	(fNext) =>
+	{
+		_Fable.OratorFileTranslation.connectRoutes();
+		return fNext();
+	});
+
+tmpAnticipate.anticipate(_Orator.startService.bind(_Orator));
+
+tmpAnticipate.wait(
+	(pError) =>
+	{
+		if (pError)
+		{
+			_Fable.log.error('Error initializing Orator Service Server: ' + pError.message, pError);
+		}
+		_Fable.log.info('Orator File Translation Service Server Initialized.');
+		_Fable.log.info('Available endpoints:');
+		_Fable.log.info('  POST http://127.0.0.1:8765/conversion/1.0/image/jpg-to-png');
+		_Fable.log.info('  POST http://127.0.0.1:8765/conversion/1.0/image/png-to-jpg');
+		_Fable.log.info('  POST http://127.0.0.1:8765/conversion/1.0/pdf-to-page-png/:Page');
+		_Fable.log.info('  POST http://127.0.0.1:8765/conversion/1.0/pdf-to-page-jpg/:Page');
+	});

package/debug/PostJPGToDebugServer.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# Post a JPG file to the debug conversion server and save the PNG result
+# Usage: bash PostJPGToDebugServer.sh <input.jpg>
+
+if [ -z "$1" ]; then
+	echo "Usage: $0 <input_jpg_file>"
+	echo "  Posts a JPG file to the debug server for conversion to PNG."
+	echo "  The debug server (Harness.js) must be running on port 8765."
+	exit 1
+fi
+
+INPUT_FILE="$1"
+
+if [ ! -f "$INPUT_FILE" ]; then
+	echo "Error: File not found: $INPUT_FILE"
+	exit 1
+fi
+
+# Extract the base filename without extension
+BASENAME=$(basename "$INPUT_FILE")
+NAME_NO_EXT="${BASENAME%.*}"
+
+# Generate timestamp: YYYY_MM_DD_HH_MM_SS_MS
+TIMESTAMP=$(date +%Y_%m_%d_%H_%M_%S)
+# Append milliseconds (cross-platform via python3)
+MS=$(python3 -c "import datetime; print(f'{datetime.datetime.now().microsecond // 1000:03d}')")
+TIMESTAMP="${TIMESTAMP}_${MS}"
+
+OUTPUT_FILE="${NAME_NO_EXT}_${TIMESTAMP}.png"
+
+echo "Converting ${INPUT_FILE} (JPG) -> ${OUTPUT_FILE} (PNG) ..."
+
+curl -s -X POST \
+	--data-binary @"${INPUT_FILE}" \
+	-H "Content-Type: application/octet-stream" \
+	http://127.0.0.1:8765/conversion/1.0/image/jpg-to-png \
+	-o "${OUTPUT_FILE}"
+
+if [ $? -eq 0 ] && [ -f "$OUTPUT_FILE" ] && [ -s "$OUTPUT_FILE" ]; then
+	echo "Success: ${OUTPUT_FILE}"
+else
+	echo "Error: Conversion failed."
+	exit 1
+fi

package/debug/PostPDFToDebugServer.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# Post a PDF file to the debug conversion server and save a page as PNG
+# Usage: bash PostPDFToDebugServer.sh <input.pdf> [page_number] [format]
+
+if [ -z "$1" ]; then
+	echo "Usage: $0 <input_pdf_file> [page_number] [format]"
+	echo "  Posts a PDF file to the debug server for page extraction."
+	echo "  page_number: The page to extract (default: 1)"
+	echo "  format: png or jpg (default: png)"
+	echo "  The debug server (Harness.js) must be running on port 8765."
+	exit 1
+fi
+
+INPUT_FILE="$1"
+PAGE="${2:-1}"
+FORMAT="${3:-png}"
+
+if [ ! -f "$INPUT_FILE" ]; then
+	echo "Error: File not found: $INPUT_FILE"
+	exit 1
+fi
+
+# Validate format
+if [ "$FORMAT" != "png" ] && [ "$FORMAT" != "jpg" ]; then
+	echo "Error: Format must be 'png' or 'jpg'"
+	exit 1
+fi
+
+# Extract the base filename without extension
+BASENAME=$(basename "$INPUT_FILE")
+NAME_NO_EXT="${BASENAME%.*}"
+
+# Generate timestamp: YYYY_MM_DD_HH_MM_SS_MS
+TIMESTAMP=$(date +%Y_%m_%d_%H_%M_%S)
+# Append milliseconds (cross-platform via python3)
+MS=$(python3 -c "import datetime; print(f'{datetime.datetime.now().microsecond // 1000:03d}')")
+TIMESTAMP="${TIMESTAMP}_${MS}"
+
+OUTPUT_FILE="${NAME_NO_EXT}_page${PAGE}_${TIMESTAMP}.${FORMAT}"
+
+echo "Extracting page ${PAGE} from ${INPUT_FILE} (PDF) -> ${OUTPUT_FILE} (${FORMAT}) ..."
+
+curl -s -X POST \
+	--data-binary @"${INPUT_FILE}" \
+	-H "Content-Type: application/octet-stream" \
+	http://127.0.0.1:8765/conversion/1.0/pdf-to-page-${FORMAT}/${PAGE} \
+	-o "${OUTPUT_FILE}"
+
+if [ $? -eq 0 ] && [ -f "$OUTPUT_FILE" ] && [ -s "$OUTPUT_FILE" ]; then
+	echo "Success: ${OUTPUT_FILE}"
+else
+	echo "Error: Conversion failed."
+	exit 1
+fi

package/debug/PostPNGToDebugServer.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# Post a PNG file to the debug conversion server and save the JPG result
+# Usage: bash PostPNGToDebugServer.sh <input.png>
+
+if [ -z "$1" ]; then
+	echo "Usage: $0 <input_png_file>"
+	echo "  Posts a PNG file to the debug server for conversion to JPG."
+	echo "  The debug server (Harness.js) must be running on port 8765."
+	exit 1
+fi
+
+INPUT_FILE="$1"
+
+if [ ! -f "$INPUT_FILE" ]; then
+	echo "Error: File not found: $INPUT_FILE"
+	exit 1
+fi
+
+# Extract the base filename without extension
+BASENAME=$(basename "$INPUT_FILE")
+NAME_NO_EXT="${BASENAME%.*}"
+
+# Generate timestamp: YYYY_MM_DD_HH_MM_SS_MS
+TIMESTAMP=$(date +%Y_%m_%d_%H_%M_%S)
+# Append milliseconds (cross-platform via python3)
+MS=$(python3 -c "import datetime; print(f'{datetime.datetime.now().microsecond // 1000:03d}')")
+TIMESTAMP="${TIMESTAMP}_${MS}"
+
+OUTPUT_FILE="${NAME_NO_EXT}_${TIMESTAMP}.jpg"
+
+echo "Converting ${INPUT_FILE} (PNG) -> ${OUTPUT_FILE} (JPG) ..."
+
+curl -s -X POST \
+	--data-binary @"${INPUT_FILE}" \
+	-H "Content-Type: application/octet-stream" \
+	http://127.0.0.1:8765/conversion/1.0/image/png-to-jpg \
+	-o "${OUTPUT_FILE}"
+
+if [ $? -eq 0 ] && [ -f "$OUTPUT_FILE" ] && [ -s "$OUTPUT_FILE" ]; then
+	echo "Success: ${OUTPUT_FILE}"
+else
+	echo "Error: Conversion failed."
+	exit 1
+fi

package/docs/README.md

@@ -0,0 +1,68 @@
+# Orator File Translation
+
+> File format conversion endpoints for Orator service servers
+
+Orator File Translation adds file format conversion endpoints to an Orator web server. Upload a file via HTTP POST and receive the converted file in the response. All routes are versioned.
+
+## Features
+
+- **Image Conversion** - Convert between JPG and PNG formats
+- **PDF Page Extraction** - Extract individual pages from PDFs as PNG or JPEG
+- **Versioned Routes** - All endpoints include a configurable version segment
+- **Extensible** - Add custom converters for any file format
+- **Configurable** - Route prefix, version, logging, and file size limits
+- **Fable Service** - Standard Fable service provider pattern
+
+## How It Works
+
+```
+Client                     Orator Server                  pdftoppm/Sharp
+  |                             |                            |
+  |  POST /conversion/1.0/     |                            |
+  |  image/jpg-to-png           |                            |
+  |  [binary JPEG data]        |                            |
+  | --------------------------> |                            |
+  |                             |  sharp(buffer).png()       |
+  |                             | -------------------------> |
+  |                             |                            |
+  |                             |  [PNG buffer]              |
+  |                             | <------------------------- |
+  |  200 OK                    |                            |
+  |  Content-Type: image/png   |                            |
+  |  [binary PNG data]         |                            |
+  | <-------------------------- |                            |
+```
+
+## Quick Start
+
+```javascript
+const libFable = require('fable');
+const libOrator = require('orator');
+const libOratorServiceServerRestify = require('orator-serviceserver-restify');
+const libOratorFileTranslation = require('orator-conversion');
+
+const _Fable = new libFable({
+	Product: 'MyConversionServer',
+	APIServerPort: 8080
+});
+
+_Fable.serviceManager.addServiceType('Orator', libOrator);
+_Fable.serviceManager.addServiceType('OratorServiceServer', libOratorServiceServerRestify);
+_Fable.serviceManager.instantiateServiceProvider('Orator');
+_Fable.serviceManager.instantiateServiceProvider('OratorServiceServer');
+
+_Fable.serviceManager.addServiceType('OratorFileTranslation', libOratorFileTranslation);
+_Fable.serviceManager.instantiateServiceProvider('OratorFileTranslation');
+
+_Fable.Orator.startService(
+	() =>
+	{
+		_Fable.OratorFileTranslation.connectRoutes();
+	});
+```
+
+## Related Packages
+
+- [orator](https://github.com/stevenvelozo/orator) - Main Orator service abstraction
+- [orator-serviceserver-restify](https://github.com/stevenvelozo/orator-serviceserver-restify) - Restify service server
+- [fable](https://github.com/stevenvelozo/fable) - Service provider framework

package/docs/_sidebar.md

@@ -0,0 +1,16 @@
+- Getting Started
+
+  - [Introduction](/)
+  - [Getting Started](getting-started.md)
+
+- Reference
+
+  - [Configuration](configuration.md)
+  - [API Reference](api-reference.md)
+
+- Endpoints
+
+  - [JPG to PNG](endpoints/001-jpg-to-png.md)
+  - [PNG to JPG](endpoints/002-png-to-jpg.md)
+  - [PDF to Page PNG](endpoints/003-pdf-to-page-png.md)
+  - [PDF to Page JPG](endpoints/004-pdf-to-page-jpg.md)