unstablevortex
/
caff-previewer-wrapper
3
0
Fork 0
Code Pull Requests Releases Activity

Create README.md

This commit is contained in:
Marcsello 2020-11-27 19:02:44 +01:00 committed by GitHub
parent df29e05b6c
commit 75ed68a948
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 38 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
README.md Normal file
View File

@ -0,0 +1,38 @@
# CAFF Previewer Wrapper
This is a simple wrapper written in Python/Flask that places a very simple HTTP interface in front of the CAFF Previewer with PNG conversion capabilites provided by ImageMagick.
## Endpoint
CAFF Previewer Wrapper exposes a single endpoint only:
**POST** `/preview`
This endpoint expects a single CAFF file to be posted, and in response it returns a single png file. The raw CAFF file contents is expected in `application/octet-stream` style without any extra encapsulation.
Possible response codes:
- **200**: Conversion went fine. The response body should be `image/png` and the integrity headers are set.
- **400**: CAFF Format violation
- **413**: Request body length is larger than the configured maximum.
- **500**: Something went terribly wrong during the creation of the preview. You should check server logs.
## Configure
CAFF Previewer Wrapper can be configured using environmental variables. Currently the following set of envvars are supported:
- CAFF_PREVIEWER_BINARY: The location of the `caff_previewer` binary (default: /usr/local/bin/caff_previewer)
- IMAGEMAGICK_CONVERT_BINARY: The location of ImageMagick's convert binary (default: /usr/bin/convert)
- CONVERSION_TIMEOUT: Timeout for running each converter binary in seconds (If they do not finish in this timeframe they will be killed and an internal server error will be reported) (default: 30)
- RECIEVE_CHUNKSIZE: Chunk size for writing file to disk and calculating md5 sum. There is really no point tuning this value in most cases. (default: 4096)
- MAX_RECIEVE_SIZE: Maximum body length to be accepted in bytes. Exceeding results in 413 error. Check is based on the actual size recieved, the `Content-length` header is currently ignored (default: 536870912 = 512 MB)
- SENTRY_DSN: Sentry DSN. Not setting it disables sentry integration (default not set)
- RELEASE_ID: Sentry release (default: test)
- RELEASEMODE: Sentry environment (default: dev)
## Integrity checking
CAFF Previewer Wrapper provides two headers in the response that can be used to check the integrity of transfered files:
`X-request-checksum` and `X-response-checksum`. The former provides an md5 checksum of the recieved file. The later is the md5 checksum of the converted file.
## Building docker image
In order for this image to be built with the `caff_previewer` binary included, it extracts the binary of the prebuilt `caff_previewer` image. ImageMagick is installed during build time.
## ImageMagick and upside-down images
For some reason different versions/builds of ImageMagick does not properly recognize the origin point of the TGA file saved by `caff_previewer` (See.: http://www.imagemagick.org/discourse-server/viewtopic.php?t=34757).
To work around this issue the argument `-auto-orient` altrough in some versions this might cause the image to appear upside-down instead, it works with the image-magick version bundled in the docker image.