transmogrify

Microservice for converting file formats.

API

/convert

Endpoint: POST /convert
Arguments:
- input: Method in which the input media is accessed
  - Supported Values: download
- inputFormat: Input media format - see Supported Conversions
- file (optional): The input media. Dpeneds on input
  - input: download: File is a URL to the resource
- converterOptions: Specific to each conversion. See Supported Conversions
- outputFormat: Output media format
- download (optional): Stream output media in response
  - Supported Values: true, false, undefined
- storage (optional): Storage driver congiruation. Can be defined as a single object or an array of configurations. See Storage Drivers
  - wait: Wait for storage driver to complete upload before returning response
    - Supported Values: true, false, undefined

Supported Conversions

HTML to PDF

{
    input: 'download',
    inputFormat: 'html',
    file: 'http://example.com',
    outputFormat: 'pdf',
}

PDF to Image

{
    input: 'download',
    inputFormat: 'pdf',
    file: 'http://example.com/file.pdf',
    converterOptions: {
        // ImageMagick Input Commands
        command: '-resize 600 -crop 600x400+0+0 +repage'
    },
    outputFormat: 'png'
}

Image to Image

{
    input: 'download',
    inputFormat: 'png',
    file: 'http://example.com/file.png',
    converterOptions: {
        // ImageMagick Input and Output Commands
        command: '-units PixelsPerInch -density 203 {INPUT_FILE} -colorspace GRAY -ordered-dither 8x8 {OUTPUT_FILE}'
    },
    outputFormat; 'png',
}

Storage Drivers

{
    type: 's3',
    region: 'us-east-1',
    bucket: 'com.example.bucket',
    key: 'folder/file.pdf'
    metadata: { /*Optinal metadata to be attached to object*/ }

    // Authentication handled by transmogrify-client
    accessKeyId: ''
    secretAccessKey: ''
    sessionToken: ''
}

Development

Transmogrify is designed to be run as a microservice running inside a docker container. The repository is setup to leverage VS Code's Remote Development extensions to develop inside a docker container. Use the instructions below to start the development environment.

Prerequisites

Docker
Visual Studio Code
Remote Development Extension Pack
AWS Credentials - devcontainer.json assumes a .aws/ directory is in your home directory on your local machine.

Start Development Environment

Navigate to the repository root and launch vs code
```
cd ./transmogrify
code .
```
Open the VS Code Command Palette (⇧⌘P) and select Remote-Containers: Rebuild and Reopen in Container
In the new VS Code Instance, open a new terminal (⌃`)
Start the server in development mode with the following command:
```
su pptruser # Run as pptruser (see note)
npm run dev
```
Note: The devcontainer.json overrides USER pptruser in the Dockerfile. This is necessary to install extensions. The app must be run as pptruser to allow puppeteer to run without --no-sandbox flag

To reubuild and relaunch the container, open the VS Code Command Palette (⇧⌘P) and select Remote-Containers: Rebuild Container
To exit the container, open the VS Code Command Palette (⇧⌘P) and select Remote-Containers: Close Remote Connection

Format / Lint

This repository uses lint-staged and husky to lint and format code with a pre-commit hook
- If the code being committed contains errors, the commit will be rejected until errors are resolved
- This is done automatically, no further configuration is required
To further improve the development experience, it is reccomended to install the the following VS Code extensions:
- ESLint
- Prettier
To enable Prettier to Format on Save in VS Code:
- Note: These settings are not necessary when developing inside the docker container as they are included in the devcontainer.js
1. Create a .vscode directory in the repository root
2. Create a settings.json file inside .vscode
3. Add these settings:
```
{
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
}
```

Debugging

The VS Code debugger configuration is located in ./.vscode/launch.json
The debugger can be started by pressing F5 or by opening the Run tab (⇧⌘D) and pressing the green play button

aelitneg / transmogrify