Initial Commit
This commit is contained in:
101
packages/media/image/caddy-imgproxy/README.md
Normal file
101
packages/media/image/caddy-imgproxy/README.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# @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`.
|
||||
|
||||
Reference in New Issue
Block a user