Crate truss 

Shared library entry points for the truss project.

The public API

What this page lists is the API. Nothing else in the crate is, and the sections below say what that means for a version number.

While the version is 0.x, a minor release may change any of it. From 1.0 on, the shape here is what semantic versioning covers: adding an export or a field to a #[non_exhaustive] type is a minor release, removing or renaming an export is a major one, and the minimum supported Rust version in Cargo.toml is raised only in a minor release. This page is the Rust crate’s half of the promise. The other surfaces state their own half beside what they specify: the CLI’s subcommands, flags, and exit codes in docs/problems.md, the HTTP server’s routes, query vocabulary, and headers in docs/api-reference.md, and each npm package’s exports and option keys in its own README. The signed URL format is older than all of them and carries a stronger promise, in docs/signed-url-spec.md, which holds even before 1.0.

Everything the crate exports is re-exported here, at the root. The module tree is private, so a path through it is not part of the API and does not compile:

use truss::core::TransformOptions;

The types that grow as truss grows are #[non_exhaustive], so a field a later version adds is a minor change rather than a breaking one. A caller starts from default(), or from a constructor, and assigns:

use truss::TransformOptions;

let options = TransformOptions { width: Some(800), ..TransformOptions::default() };

use truss::TransformOptions;

let mut options = TransformOptions::default();
options.width = Some(800);
assert_eq!(options.width, Some(800));

The value types are exhaustive on purpose, because none of them can gain a field without becoming a different idea: a rectangle is four numbers, a colour is four channels, a size is two, and a quality target is a metric and a threshold. Their literals and their patterns keep working.

use truss::{CropRegion, Dimensions, Rgba8};

let region = CropRegion { x: 0, y: 0, width: 10, height: 10 };
let colour = Rgba8 { r: 1, g: 2, b: 3, a: 255 };
let size = Dimensions::new(10, 10);
assert_eq!((region.width, colour.a, size.height), (10, 255, 10));

Structs

Artifact

A decoded or otherwise classified artifact handled by the Core layer.

ArtifactMetadata

Metadata that the Core layer can carry between decode and encode steps.

CropRegion

An explicit crop region applied before resize.

Dimensions

A (width, height) pair that prevents accidental transposition of dimensions.

RawArtifact

Raw input bytes before media-type detection has completed.

Rgba8

A simple 8-bit RGBA color.

Rotation

Clockwise rotation in whole degrees, applied after auto-orientation.

ServerConfig

SignedWatermarkParams

Builds a signed public transform URL for the server adapter.

TargetQuality

A perceptual quality target used when binary-searching a lossy encode quality.

TransformOptions

Raw transform options before defaulting and validation has completed.

TransformOptionsPayload

TransformRequest

A complete transform request for the Core layer.

TransformResult

The result of a successful transform, containing the output artifact and any warnings.

WatermarkInput

A watermark image to composite onto the output.

Enums

Fit

Resize behavior for bounded transforms.

LogLevel

Log verbosity level for the server.

MediaType

Supported media types for the current implementation phase.

MetadataKind

Categories of image metadata that may be present in an artifact.

OptimizeMode

Optimization policy applied near the final encoding stage.

Position

Positioning behavior for bounded transforms.

QualityMetric

Perceptual metric used for lossy optimization quality targeting.

SignedUrlSource

Source selector used when generating a signed public transform URL.

TransformError

Errors returned by Core validation or backend execution.

TransformWarning

A non-fatal warning emitted during a transform operation.

TrustedProxy

A trusted proxy specification: either a single IP address or a CIDR block.

Constants

MAX_OUTPUT_PIXELS

Maximum number of pixels in the output image (width × height).

Functions

bind_addr

Returns the bind address for the HTTP server adapter.

run_cli

Runs the command-line adapter and returns a process exit code.

serve_once_with_config

Serves exactly one request with an explicit server configuration.

serve_with_config

Serves requests with an explicit server configuration.

sign_public_url

sign_public_url_with_method

Like sign_public_url but allows the caller to specify the HTTP method included in the canonical string (e.g. "GET" or "HEAD").

sniff_artifact

Inspects raw bytes, detects the media type, and extracts best-effort metadata.

transform

Dispatches a transform request to the appropriate codec based on the input media type.

Type Aliases

LogHandler

Runtime configuration for the HTTP server adapter.