PommaLabs.Thumbnailer.Client 4.1.0

Prefix Reserved
.NET 6.0 This package targets .NET 6.0. The package is compatible with this framework or higher. .NET Core 3.1 This package targets .NET Core 3.1. The package is compatible with this framework or higher. .NET Framework 4.6.1 This package targets .NET Framework 4.6.1. The package is compatible with this framework or higher.
This package has a SemVer 2.0.0 package version: 4.1.0+dbd3c8e.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package PommaLabs.Thumbnailer.Client --version 4.1.0                

                    
                

            
NuGet\Install-Package PommaLabs.Thumbnailer.Client -Version 4.1.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="PommaLabs.Thumbnailer.Client" Version="4.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add PommaLabs.Thumbnailer.Client --version 4.1.0                

                    
                

            
#r "nuget: PommaLabs.Thumbnailer.Client, 4.1.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
// Install PommaLabs.Thumbnailer.Client as a Cake Addin
#addin nuget:?package=PommaLabs.Thumbnailer.Client&version=4.1.0

// Install PommaLabs.Thumbnailer.Client as a Cake Tool
#tool nuget:?package=PommaLabs.Thumbnailer.Client&version=4.1.0

Thumbnailer

License: MIT Donate Docker Stars Docker Pulls Docs NuGet version NuGet downloads

standard-readme compliant GitLab pipeline status Quality gate Code coverage Renovate enabled

Web service which exposes endpoints to generate file thumbnails and to optimize media files.

Thumbnailer heavily relies on many open source command line tools. Just to name a few:

  • ffmpeg, used to generate video thumbnails and to optimize MP4 files.
  • GraphicsMagick, used to generate image thumbnails.
  • LibreOffice, used to convert Office files to images.
  • PhantomJS, used to convert HTML files to images.
  • pngquant, used to optimize PNG images and file thumbnails.

Web service runs on ASP.NET Core and this repository contains a .NET Standard client which can be used to interact with it.

Table of Contents

Install

Thumbnailer web service is provided as a Docker image hosted on Docker Hub.

You can quickly start a local test instance with following command:

docker run -it -e Security__AllowAnonymousAccess=true -p 8080:8080 pommalabs/thumbnailer:latest

Local test instance will be listening on port 8080 and it will accept unauthenticated requests. Please check the Configuration section to find further information about how the web service can be properly configured.

A .NET client, PommaLabs.Thumbnailer.Client, is available as a NuGet package:

dotnet add package PommaLabs.Thumbnailer.Client

Tags

Following tags are available:

  • latest, based on pommalabs/dotnet:5-aspnet, contains the code found in main branch.
  • azure-appsvc, based on pommalabs/dotnet:5-azure-appsvc, contains the code found in main branch. This tag is customized in order to support SSH connection exposed through Azure App Service.
  • preview, based on pommalabs/dotnet:5-aspnet, contains the code found in preview branch.

Each tag is rebuilt every week.

Configuration

Docker image can be configured using the following environment variables:

Environment variable Notes Default value
Database__CacheLifetime How long each cache entry will live. 20 minutes
Database__ConnectionString Connection string of a SQL database.
Database__Provider Provider (None, PostgreSql, SqlServer). None
Database__SchemaName SQL schema name.
Security__AcceptApiKeysViaHeaderParameter Accept API keys via header parameter. true
Security__AcceptApiKeysViaQueryStringParameter Accept API keys via query string parameter. false
Security__AllowAnonymousAccess Allow anonymous users to consume services. false
Security__ApiKeys__X__ExpiresAt If not specified, API key will not expire.
Security__ApiKeys__X__Name Descriptive name of API key at index X.
Security__ApiKeys__X__Value Value of API key at index X.
Security__AsyncProcessTimeout Timeout for low level processes (in async jobs). 10 minutes
Security__EnableCaseSensitiveApiKeyValidation Enable case sensitive API key validation. false
Security__FileDownloadTimeout Timeout for file download. 30 seconds
Security__MaxFileDownloadSizeInBytes How many bytes are allowed for remote downloads. 64 MB
Security__MaxFileUploadSizeInBytes How many bytes are allowed for uploads. 32 MB
Security__ProcessTimeout Timeout for low level processes (in sync calls). 30 seconds
Website__Enabled Expose the public website. false

Logging

Web service writes log messages to the console and to the file system. Log files are stored in the following directory, which is not configurable:

/opt/app/Data/Logs

Log files are rotated daily and a maximum number of 31 files is kept.

If an Azure Application Insights Instrumentation Key is specified using the APPINSIGHTS_INSTRUMENTATIONKEY configuration, logs are also sent to that service.

Database

Setup scripts for supported systems are available:

You can customize those scripts according to your needs, but please remember that if you change schema name, you should update Database__SchemaName configuration property accordingly.

Persistence

When an external database is configured, it is also used by the web service to store cache entries using the KVLite library.

Cache entries store the SHA384 of input files and the parameters used; that data is linked to the location of the output file in Thumbnailer temporary directory (/tmp/thumbnailer).

Moreover, distributed cache is also used to track job information for API v2. Job IDs are encrypted using local keys (/opt/app/Data/DataProtectionKeys).

So, you might want to persist the following directories:

  • /tmp/thumbnailer, where temporary files stay for at least as long as it has been specified with Database__CacheLifetime configuration.
  • /opt/app/Data/DataProtectionKeys, where local encryption keys are stored.
  • /opt/app/Data/Logs, where log files are written.

Persisting those directories is not mandatory at all. The web service works fine without having them persisted.

However, persisting them might be useful for the following use cases:

  • Web service receives a lot of requests and temporary files directory can grow quite a lot. In that case, a separate volume with proper size can be configured.
  • Web service works in load balancing and it is configured to use an external DB. In that case, sharing the temporary files directory is required in order to let all instances be able to read cached outputs.
  • Easier log files access. Having log files stored externally might make them easier to access with other tools.

Usage

Please check OpenAPI docs on your instance (just visit the /swagger page) or head to the demo instance Swagger page. Each endpoint has been documented using the OpenAPI specification.

Media optimization supports following content types:

  • image/gif
  • image/jpeg
  • image/png
  • image/svg+xml
  • image/webp
  • video/mp4

Thumbnail generation supports quite a lot of content types. Anyway, you can use the test files as a quick reference to find out what the web service really supports. Inside each "format" folder you will find a copy of the latest thumbnails, that is, for each file you will find the most recent copy of its thumbnail.

However, not every content type for which a thumbnail could be "theoretically" generated is supported. Some notable formats which are not supported are the following:

Synchronous API (v1)

Synchronous API is exposed through v1 endpoints and, as its name suggests, it allows to send synchronous HTTP requests for thumbnail generation or media generation, where the output file is provided as a response for each request.

This approach is quite simple but it is not recommended, because each HTTP request should have a very short timeout and that fact does not work well with the processing of large or complex files. Anyway, this kind of API was the first one to be implemented by Thumbnailer and it will be maintained in the future. There are use cases where a simple API is enough and it is preferred over a more complex one.

Synchronous requests timeout is controlled by Security__ProcessTimeout setting, as described in the Configuration section.

With a Thumbnailer instance running, as described in the Install section, you can generate the thumbnail of a sample image with the following request:

GET /api/v1/thumbnail?fileUri=https://via.placeholder.com/2048&widthPx=256&heightPx=256&shavePx=0&fill=true&smartCrop=false&responseType=Binary HTTP/1.1
Host: localhost:8080

That endpoint will generate a response containing the requested thumbnail.

Please inspect Swagger documentation of v1 endpoints in order to find further information about exposed operations. For example, input files can also be POSTed using a multipart/form-data request or with a JSON payload.

Asynchronous API (v2)

Asynchronous API is exposed through v2 endpoints and it allows to start processing jobs which can be monitored with a dedicated API. When a job is finished, its output will be available for download.

Asynchronous API is more complex to work with, because it requires at least three HTTP calls in order to obtain the operation output. However, the asynchronous approach is required when potentially large or complex files need to be processed.

Asynchronous jobs timeout is controlled by Security__AsyncProcessTimeout setting, as described in the Configuration section.

With a Thumbnailer instance running, as described in the Install section, you can start the generation of the thumbnail of a sample image with the following request:

GET /api/v2/thumbnail?fileUri=https://via.placeholder.com/2048&widthPx=256&heightPx=256&shavePx=0&fill=true&smartCrop=false HTTP/1.1
Host: localhost:8080

That endpoint will respond with a JSON payload containing the job ID:

{
    "failureReason": null,
    "jobId": "NEW_JOB_ID",
    "status": "Queued"
}

That job ID can be used to query the job status:

GET /api/v2/jobs/NEW_JOB_ID HTTP/1.1
Host: localhost:8080

When job status becomes Processed, as in sample below:

{
    "failureReason": null,
    "jobId": "NEW_JOB_ID",
    "status": "Processed"
}

Then job result is ready to be downloaded from following endpoint:

GET /api/v2/jobs/NEW_JOB_ID/download?responseType=Binary HTTP/1.1
Host: localhost:8080

That endpoint will generate a response containing the requested thumbnail.

Please inspect Swagger documentation of v2 endpoints in order to find further information about exposed operations. For example, input files can also be POSTed using a multipart/form-data request or with a JSON payload.

Maintainers

@pomma89.

Contributing

PRs accepted.

Small note: If editing the README, please conform to the standard-readme specification.

License

MIT © 2019-2021 Alessio Parma

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp3.1 is compatible. 
.NET Framework net461 is compatible.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 is compatible.  net48 was computed.  net481 was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
6.1.3 426 3/15/2024
6.1.2 253 12/15/2023
6.1.1 64 12/14/2023
6.1.0 131 11/25/2023
6.0.0 158 6/5/2023
5.1.0 1,000 12/19/2022
5.0.0 87 11/27/2022
4.2.0 443 12/19/2021
4.1.0 451 11/21/2021
4.0.2 186 8/20/2021
3.1.0 1,096 2/7/2021
3.0.0 1,284 11/9/2020
2.1.0 1,061 9/10/2020
2.0.2 1,036 6/19/2020
2.0.1 983 6/11/2020
2.0.0 1,019 6/1/2020
1.7.1 1,062 4/13/2020
1.6.3 1,026 3/29/2020
1.6.0 1,078 3/8/2020

https://gitlab.com/pommalabs/thumbnailer/-/releases