Introduction

PreviewProxy is an open-source, self-hosted image proxy and on-the-fly image transformer written in Rust. It sits between your application and upstream image sources, fetching, transforming, and caching images at request time - so you never need to pre-generate image variants or store multiple sizes.

flowchart TD
    subgraph Clients["Clients"]
        direction TB
        C1["Mobile"]
        C2["Web"]
        C3["Desktop"]
    end

    PP[("PreviewProxy")]

    subgraph Sources["Sources"]
        S1["HTTP URL"]
        S2["S3-compatible"]
        S3["Local Filesystem"]
    end

    Clients -->|image request| PP
    PP -->|fetch| S1
    PP -->|fetch| S2
    PP -->|fetch| S3

When your application requests an image at a specific size or format, PreviewProxy:

1. Fetches the source image from an upstream source (HTTP URL, S3-compatible, local filesystem)
2. Applies any requested transforms (resize, format conversion, rotate, blur, and more)
3. Returns the result to the caller and stores it in a two-level cache (memory + disk) for subsequent requests

Because transforms are applied on demand and results are cached, your application only needs to store original images and can request any derivative variant via a simple URL.

flowchart TD
    Client(["Client"])
    Router["Router"]
    Cache["Cache Module\nL1 Memory · L2 Transformed · L2 Origin"]
    Proxy["Proxy Module\nHTTP · S3 · Filesystem"]
    Transform["Transform Module"]

    Client -->|request| Router
    Router --> Cache
    Cache -->|hit| Client
    Cache -->|origin hit\nskip fetch| Transform
    Cache -->|miss| Proxy
    Proxy -->|source image| Cache
    Proxy -->|source image| Transform
    Transform -->|transformed image| Cache
    Transform -->|response| Client

• Multiple source backends - Proxy images from public or authenticated HTTP URLs, AWS S3 (or S3-compatible storage), the local filesystem.
• On-the-fly transformation - Resize, convert formats, rotate, flip, blur, adjust brightness and contrast, apply watermarks, and more - all via URL parameters
• Animated GIF pipeline - Output all frames of an animated GIF, optionally applying transforms to a selected frame range
• Video thumbnail extraction - Extract a frame from MP4, MKV, AVI and pass it through the normal transform pipeline
• Two-level cache - L1 in-memory cache for hot images, L2 disk cache for longer-term storage, both with configurable TTL and size limits
• Security - Domain allowlist, optional HMAC request signing, source URL encryption (AES-CBC), configurable CORS origins, SSRF protection (private IP blocking, per-hop re-validation on redirects), input/output/transform disallow lists

JPEG, PNG, GIF, WebP, AVIF, JXL, BMP, TIFF, ICO

PreviewProxy is open-source software released under the Apache License 2.0.