Dominik Schmidt
eb6d1021a3
The repeated post-and-assert bodies collapse into tables, and the sources are built without gomega because they run while the spec tree is built.
Thumbnails
The thumbnails service is a stateless image resizer. It exposes an imagor-compatible push endpoint that accepts an original image as a multipart upload and returns the resized thumbnail encoded in the requested format.
Warning: This service performs no authentication or authorization. By default it binds to
127.0.0.1:9186so only local processes (the webdav service) can reach it. If you changeTHUMBNAILS_HTTP_ADDRto a non-loopback address, put it behind your reverse proxy's auth layer or an internal network boundary. Anyone who can reach the endpoint can upload and retrieve arbitrary images through it.
Push Endpoint
The webdav service (which owns the complete thumbnail workflow) POSTs the source file to this endpoint and receives the processed image back.
| Route | Description |
|---|---|
POST /unsafe/{width}x{height}/filters:{filters} |
Fill the exact width x height (center crop, may upscale), the default |
POST /unsafe/fit-in/{width}x{height}/filters:{filters} |
Scale to fit within width x height, preserving aspect ratio and never upscaling |
POST /unsafe/stretch/{width}x{height}/filters:{filters} |
Resize to the exact width x height without preserving aspect ratio (distorts) |
The filters segment is optional, like imagor's, and may also be empty
(filters:). Inside it, format and
no_upscale are the filters this executor acts on, every other filter is
ignored. format itself is optional: without it the input's own format is
preserved, the same way imagor does it. An input this service cannot write
(tiff, bmp) becomes a JPEG; imagor writes tiff back in its own format and only
falls back to JPEG for the ones it cannot write either.
Like real imagor, the default fill resize upscales small sources to fill
the box exactly (a 100x100 source requested at 320x320 returns a 320x320
image). Adding the no_upscale() filter caps the result at the source size
instead (the same request returns 100x100). The fit-in route never upscales,
imagor would with the upscale() filter, this service ignores it.
Which route a preview request ends up on, and the processor and a
parameters that decide it, are the webdav service's business and documented in
its README.
The request body is a multipart/form-data upload with a single file field
named image, typed image/*; an untyped part is refused the way imagor's
upload loader refuses it. Output formats are jpg, png, gif and, with
libvips, webp; the pure Go build answers 400 for format(webp) because it
has no webp encoder. An animated gif asked for a still format is flattened to
its first frame, and a still source asked for format(gif) is palettised.
Reading an ICO needs libvips with its magick loader; the pure Go build answers
406 for one.
The answers are imagor's: 400 for a malformed request, 406 for a source it
cannot read, 422 for an image above the configured maximum dimensions, 429
when the concurrency limit is reached.
Configuration
| Environment variable | Description |
|---|---|
THUMBNAILS_HTTP_ADDR |
Bind address of the HTTP service (default 127.0.0.1:9186) |
THUMBNAILS_LOG_LEVEL |
Log level (panic, fatal, error, warn, info, debug, trace) |
THUMBNAILS_MAX_CONCURRENT_REQUESTS |
Maximum number of thumbnail requests decoded and resized in parallel. Default is 0 (unlimited). Requests arriving while the limit is reached get HTTP 429 with a Retry-After header |
THUMBNAILS_MAX_INPUT_WIDTH |
Maximum width of a source image, 7680 by default. A wider one is refused with HTTP 422, which webdav turns into its legacy 403 |
THUMBNAILS_MAX_INPUT_HEIGHT |
Maximum height of a source image, 7680 by default |
Using libvips for Image Processing
To improve performance and to support a wider range of image formats, the thumbnails service is able to utilize the libvips library for image processing. Support for libvips needs to be enabled at buildtime and has a couple of implications:
- With libvips support enabled, it is not possible to create a statically linked OpenCloud binary.
- Therefore, the libvips shared libraries need to be available at runtime in the same release that was used to build the OpenCloud binary.
- When using the OpenCloud docker images, the libvips shared libraries are included in the image and are correctly embedded.
Support of libvips is disabled by default. To enable it, make sure libvips and its buildtime dependencies are installed in your build environment. For macOS users, add the build time dependencies via:
brew install vips pkg-config
export PKG_CONFIG_PATH="/usr/local/opt/libffi/lib/pkgconfig"
Then you just need to set the ENABLE_VIPS variable on the make command:
make -C opencloud build ENABLE_VIPS=1
Or include the enable_vips build tag in the go build command:
go build -tags enable_vips -o opencloud -o bin/opencloud ./cmd/opencloud
When building a docker image using the Dockerfile in the top-level directory of OpenCloud, libvips support is enabled and the libvips shared libraries are included in the resulting docker image.