suaveplan/packages/media/image/caddy-imgproxy/README.md

@suaveplan/caddy-imgproxy - Universal TypeScript port of the Caddy imgproxy URL rewriter — compact-grammar parser, aspect / pixel dimension resolver, gravity + operation translator, HMAC-SHA256 URL signer, full handler with Zod-validated config and OTel telemetry

Universal TypeScript port of the Caddy imgproxy URL rewriter. Parses the compact /u<op><gravity><dims><modifiers>/<path>.<format> grammar, resolves aspect-ratio + hint dimensions, translates gravity + operations into imgproxy's URL DSL, signs the result with HMAC-SHA256, and exposes a high-level ImgproxyHandler orchestrator with injectable Clock, LoggerLike, and signing hash, plus Zod-validated configuration and OTel telemetry.

Documentation tree

• config — The config module exposes the Zod schema and the validating parseConfig function for the package's public `Imgproxy…
  • config — The config module exposes the Zod schema and the validating parseConfig function for the package's public `Imgproxy…
• dimensions — calculateDimensions resolves a ParsedImgproxyUrl plus the configured defaultWidth into a concrete `{ width, heigh…
  • calculate-dimensions — calculateDimensions resolves a ParsedImgproxyUrl plus the configured defaultWidth into a concrete `{ width, heigh…
• domain — extractDomain translates an incoming HTTP Host header into the S3 sub-path segment that the URL builder interpolate…
  • extract-domain — extractDomain translates an incoming HTTP Host header into the S3 sub-path segment that the URL builder interpolate…
• error-codes — The error-codes module is the canonical home of the package's stable error-code registry and the typed `CaddyImgproxy…
  • error-codes — The error-codes module is the canonical home of the package's stable error-code registry and the typed `CaddyImgproxy…
• gravity — The gravity module exposes the bidirectional translation between the compact one- or two-character grammar codes (t…
  • gravity — The gravity module exposes the bidirectional translation between the compact one- or two-character grammar codes (t…
• handler — ImgproxyHandler is the high-level orchestrator that wraps parseImgproxyUrl, extractDomain, and buildImgproxyUrl…
  • handler — ImgproxyHandler is the high-level orchestrator that wraps parseImgproxyUrl, extractDomain, and buildImgproxyUrl…
• operation — operationToImgproxy converts a resolved operation + concrete pixel dimensions + gravity into the imgproxy processing-…
  • operation — operationToImgproxy converts a resolved operation + concrete pixel dimensions + gravity into the imgproxy processing-…
• parse — parseImgproxyUrl parses the compact imgproxy URL grammar used by the Caddy module — `/[s|u]<modifi…
  • parse-url — parseImgproxyUrl parses the compact imgproxy URL grammar used by the Caddy module — `/[s|u]<modifi…
• signing — signImgproxyPath computes the HMAC-SHA256 URL signature that imgproxy requires when it is configured with a key + sal…
  • sign-path — signImgproxyPath computes the HMAC-SHA256 URL signature that imgproxy requires when it is configured with a key + sal…
• telemetry — The telemetry module owns the OTel instruments emitted by every public entry point in @suaveplan/caddy-imgproxy. It…
  • telemetry — The telemetry module owns the OTel instruments emitted by every public entry point in @suaveplan/caddy-imgproxy. It…
• types — The types module declares every cross-feature type that flows between the package's runtime modules: `ParsedImgproxyU…
  • types — The types module declares every cross-feature type that flows between the package's runtime modules: `ParsedImgproxyU…
• url-builder — buildImgproxyUrl composes the final imgproxy URL path from a parsed grammar representation. It is the orchestrator th…
  • url-builder — buildImgproxyUrl composes the final imgproxy URL path from a parsed grammar representation. It is the orchestrator th…

Install

bun add @suaveplan/caddy-imgproxy

Quick start

import { ImgproxyHandler, parseConfig } from "@suaveplan/caddy-imgproxy";

const handler = new ImgproxyHandler({
    config: parseConfig({
        upstream: "imgproxy:8080",
        s3Bucket: "media",
        defaultWidth: 1200,
        key: "aa11bbcc",
        salt: "deadbeef",
    }),
});

const result = handler.rewrite({
    path: "/uvt9:16h1080/photos/hero.webp",
    host: "images.example.com",
});

if (result.rewritten) {
    forwardToImgproxy(result.targetPath);
} else if (result.reason === "passthrough") {
    forwardToImgproxy(originalPath);
}

Modules

• parse — compact-grammar parser.
• dimensions — aspect / hint → pixel resolution.
• gravity — grammar gravity → imgproxy compass tokens.
• operation — operation + dimensions → imgproxy processing string.
• signing — HMAC-SHA256 URL signing.
• url-builder — composes the final imgproxy path.
• domain — Host header → S3 sub-path.
• handler — ImgproxyHandler orchestrator.
• config — Zod-validated ImgproxyConfig.
• error-codes — CADDY_IMGPROXY_CODES + CaddyImgproxyError.
• telemetry — OTel counters + histogram.

Tier & dependencies

Universal — no DOM or Node-only APIs at the package boundary. sideEffects: false. Internal deps: @suaveplan/crypto-hash, @suaveplan/error, @suaveplan/types. External deps: @opentelemetry/api, tslib, zod.