PommaLabs.Thumbnailer.Client 4.0.2

Prefix Reserved

This package has a SemVer 2.0.0 package version: 4.0.2+3c5eaff.

There is a newer version of this package available.
See the version list below for details.

dotnet add package PommaLabs.Thumbnailer.Client --version 4.0.2

NuGet\Install-Package PommaLabs.Thumbnailer.Client -Version 4.0.2

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.0.2" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

paket add PommaLabs.Thumbnailer.Client --version 4.0.2

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: PommaLabs.Thumbnailer.Client, 4.0.2"

#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.0.2

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

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Thumbnailer

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.

Install
Usage
- Synchronous API (v1)
- Asynchronous API (v2)
Maintainers
Contributing
License

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

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`
`Website__GoogleAnalyticsPropertyId`	Google Analytics property ID.

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.

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 endpoint) or head to the demo instance Swagger endpoint. 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:

PSD files represent a security issue since GraphicsMagick support is not complete. As a matter of fact, their support in GraphicsMagick has been disabled.

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

Product	Compatible and additional computed target framework versions.
.NET	net5.0 was computed. net5.0-windows was computed. net6.0 was computed. 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	netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed.
.NET Standard	netstandard2.0 is compatible. netstandard2.1 was computed.
.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.
MonoAndroid	monoandroid was computed.
MonoMac	monomac was computed.
MonoTouch	monotouch was computed.
Tizen	tizen40 was computed. tizen60 was computed.
Xamarin.iOS	xamarinios was computed.
Xamarin.Mac	xamarinmac was computed.
Xamarin.TVOS	xamarintvos was computed.
Xamarin.WatchOS	xamarinwatchos was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

.NETFramework 4.6.1
- Flurl.Http (>= 3.2.0)
- Microsoft.CSharp (>= 4.7.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 2.0.0)
- Microsoft.Extensions.Diagnostics.HealthChecks.Abstractions (>= 2.2.0)
- Microsoft.Extensions.Logging.Abstractions (>= 2.0.0)
- Microsoft.Extensions.Options (>= 2.0.0)
- Newtonsoft.Json (>= 13.0.1)
- Polly (>= 7.2.2)
- PommaLabs.MimeTypes (>= 2.4.0)
- System.Diagnostics.DiagnosticSource (>= 5.0.1)
.NETFramework 4.7.2
- Flurl.Http (>= 3.2.0)
- Microsoft.CSharp (>= 4.7.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 2.0.0)
- Microsoft.Extensions.Diagnostics.HealthChecks.Abstractions (>= 2.2.0)
- Microsoft.Extensions.Logging.Abstractions (>= 2.0.0)
- Microsoft.Extensions.Options (>= 2.0.0)
- Newtonsoft.Json (>= 13.0.1)
- Polly (>= 7.2.2)
- PommaLabs.MimeTypes (>= 2.4.0)
- System.Diagnostics.DiagnosticSource (>= 5.0.1)
.NETStandard 2.0
- Flurl.Http (>= 3.2.0)
- Microsoft.CSharp (>= 4.7.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 2.0.0)
- Microsoft.Extensions.Diagnostics.HealthChecks.Abstractions (>= 2.2.0)
- Microsoft.Extensions.Logging.Abstractions (>= 2.0.0)
- Microsoft.Extensions.Options (>= 2.0.0)
- Newtonsoft.Json (>= 13.0.1)
- Polly (>= 7.2.2)
- PommaLabs.MimeTypes (>= 2.4.0)
- System.Diagnostics.DiagnosticSource (>= 5.0.1)

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.2.0	28	11/19/2024
6.1.3	441	3/15/2024
6.1.2	256	12/15/2023
6.1.1	67	12/14/2023
6.1.0	134	11/25/2023
6.0.0	161	6/5/2023
5.1.0	1,003	12/19/2022
5.0.0	92	11/27/2022
4.2.0	446	12/19/2021
4.1.0	454	11/21/2021
4.0.2	189	8/20/2021
3.1.0	1,101	2/7/2021
3.0.0	1,289	11/9/2020
2.1.0	1,064	9/10/2020
2.0.2	1,043	6/19/2020
2.0.1	988	6/11/2020
2.0.0	1,022	6/1/2020
1.7.1	1,065	4/13/2020
1.6.3	1,029	3/29/2020
1.6.0	1,081	3/8/2020