102 lines
6.6 KiB
Markdown
102 lines
6.6 KiB
Markdown
# @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.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [config](./src/config/config.md) — The `config` module exposes the Zod schema and the validating `parseConfig` function for the package's public `Imgproxy…
|
|
- [config](./src/config/config.md) — The `config` module exposes the Zod schema and the validating `parseConfig` function for the package's public `Imgproxy…
|
|
- [dimensions](./src/dimensions/calculate-dimensions.md) — `calculateDimensions` resolves a `ParsedImgproxyUrl` plus the configured `defaultWidth` into a concrete `{ width, heigh…
|
|
- [calculate-dimensions](./src/dimensions/calculate-dimensions.md) — `calculateDimensions` resolves a `ParsedImgproxyUrl` plus the configured `defaultWidth` into a concrete `{ width, heigh…
|
|
- [domain](./src/domain/extract-domain.md) — `extractDomain` translates an incoming HTTP `Host` header into the S3 sub-path segment that the URL builder interpolate…
|
|
- [extract-domain](./src/domain/extract-domain.md) — `extractDomain` translates an incoming HTTP `Host` header into the S3 sub-path segment that the URL builder interpolate…
|
|
- [error-codes](./src/error-codes/error-codes.md) — The `error-codes` module is the canonical home of the package's stable error-code registry and the typed `CaddyImgproxy…
|
|
- [error-codes](./src/error-codes/error-codes.md) — The `error-codes` module is the canonical home of the package's stable error-code registry and the typed `CaddyImgproxy…
|
|
- [gravity](./src/gravity/gravity.md) — The `gravity` module exposes the bidirectional translation between the compact one- or two-character grammar codes (`t`…
|
|
- [gravity](./src/gravity/gravity.md) — The `gravity` module exposes the bidirectional translation between the compact one- or two-character grammar codes (`t`…
|
|
- [handler](./src/handler/handler.md) — `ImgproxyHandler` is the high-level orchestrator that wraps `parseImgproxyUrl`, `extractDomain`, and `buildImgproxyUrl`…
|
|
- [handler](./src/handler/handler.md) — `ImgproxyHandler` is the high-level orchestrator that wraps `parseImgproxyUrl`, `extractDomain`, and `buildImgproxyUrl`…
|
|
- [operation](./src/operation/operation.md) — `operationToImgproxy` converts a resolved operation + concrete pixel dimensions + gravity into the imgproxy processing-…
|
|
- [operation](./src/operation/operation.md) — `operationToImgproxy` converts a resolved operation + concrete pixel dimensions + gravity into the imgproxy processing-…
|
|
- [parse](./src/parse/parse-url.md) — `parseImgproxyUrl` parses the compact imgproxy URL grammar used by the Caddy module — `/[s|u]<op><gravity><dims><modifi…
|
|
- [parse-url](./src/parse/parse-url.md) — `parseImgproxyUrl` parses the compact imgproxy URL grammar used by the Caddy module — `/[s|u]<op><gravity><dims><modifi…
|
|
- [signing](./src/signing/sign-path.md) — `signImgproxyPath` computes the HMAC-SHA256 URL signature that imgproxy requires when it is configured with a key + sal…
|
|
- [sign-path](./src/signing/sign-path.md) — `signImgproxyPath` computes the HMAC-SHA256 URL signature that imgproxy requires when it is configured with a key + sal…
|
|
- [telemetry](./src/telemetry/telemetry.md) — The `telemetry` module owns the OTel instruments emitted by every public entry point in `@suaveplan/caddy-imgproxy`. It…
|
|
- [telemetry](./src/telemetry/telemetry.md) — The `telemetry` module owns the OTel instruments emitted by every public entry point in `@suaveplan/caddy-imgproxy`. It…
|
|
- [types](./src/types/types.md) — The `types` module declares every cross-feature type that flows between the package's runtime modules: `ParsedImgproxyU…
|
|
- [types](./src/types/types.md) — The `types` module declares every cross-feature type that flows between the package's runtime modules: `ParsedImgproxyU…
|
|
- [url-builder](./src/url-builder/url-builder.md) — `buildImgproxyUrl` composes the final imgproxy URL path from a parsed grammar representation. It is the orchestrator th…
|
|
- [url-builder](./src/url-builder/url-builder.md) — `buildImgproxyUrl` composes the final imgproxy URL path from a parsed grammar representation. It is the orchestrator th…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Install
|
|
|
|
```bash
|
|
bun add @suaveplan/caddy-imgproxy
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```ts
|
|
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](./src/parse/parse-url.md) — compact-grammar parser.
|
|
- [dimensions](./src/dimensions/calculate-dimensions.md) — aspect /
|
|
hint → pixel resolution.
|
|
- [gravity](./src/gravity/gravity.md) — grammar gravity → imgproxy
|
|
compass tokens.
|
|
- [operation](./src/operation/operation.md) — operation +
|
|
dimensions → imgproxy processing string.
|
|
- [signing](./src/signing/sign-path.md) — HMAC-SHA256 URL signing.
|
|
- [url-builder](./src/url-builder/url-builder.md) — composes the
|
|
final imgproxy path.
|
|
- [domain](./src/domain/extract-domain.md) — Host header → S3
|
|
sub-path.
|
|
- [handler](./src/handler/handler.md) — `ImgproxyHandler`
|
|
orchestrator.
|
|
- [config](./src/config/config.md) — Zod-validated `ImgproxyConfig`.
|
|
- [error-codes](./src/error-codes/error-codes.md) —
|
|
`CADDY_IMGPROXY_CODES` + `CaddyImgproxyError`.
|
|
- [telemetry](./src/telemetry/telemetry.md) — 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`.
|
|
|