R&D documentation

RQ8 — Media path: presigned URLs vs streaming through the BFF

Source: ddx-documentation/research/rq8-media-path.md

Previous: RQ7 — Which data uses the server cache, which uses TanStack Query, how is each invalidated?Next: Template triage — create-nextjs code in ddx-web Inventory gallery

**Question** (task 024, WS4 G4.1-G4.3): should the browser move image bytes straight to MinIO with presigned URLs minted by ddx-api, or should the bytes stream through the ddx-web BFF and ddx-api? Decision record: [ADR 0010](/en/docs/adr/0010-media-path). ## Spike (2026-10-23, task 024) - Setup: one 2 MiB random payload, 10 runs per path, Node v26.12.0, all on one dev host. MinIO container `ddx-web-boot-minio` (S3 API `127.0.0.1:16350`), private bucket `ddx-images`, keys `org/rq8-spike/image/<uuid>` (all 20 deleted after the run). - **Direct** = ddx-api presigns (`@aws-sdk/s3-request-presigner`, TTL 300 s); the client PUTs / GETs MinIO itself. - **Relay** = two loopback HTTP hops: a BFF hop that pipes the stream, then an API hop that reads the body and calls `PutObject` / streams `GetObject`. This is the shape of "upload through `api/v1`". - Script: kept outside the repo (scratch). It reads the MinIO credentials from `ddx-docker-minio/.env` and never prints them. | Path | Median | Min | Max | |---|---|---|---| | presign (sign only, no network) | 0.6 ms | 0.5 ms | 7.3 ms | | PUT direct (presigned) | 12.1 ms | 10.8 ms | 35.3 ms | | PUT via 2 relay hops | 18.8 ms | 16.5 ms | 24.4 ms | | GET direct (presigned) | 9.3 ms | 8.1 ms | 10.3 ms | | GET via 2 relay hops | 10.3 ms | 9.3 ms | 129.3 ms | Extra check: an unsigned GET of a spike object on the private bucket answered **403**. ## Findings | # | Finding | |---|---| | F1 | Direct PUT is about 1.55× faster than the relay (12.1 vs 18.8 ms median) on loopback. Over a real network each relay hop adds one more full copy of the bytes, so the gap grows with distance and file size. | | F2 | The relay holds the whole body in ddx-api memory (the SDK `PutObject` needs a length) and counts against the API body limit. ddx-api's two-tier body limit (`ddx-api/CLAUDE.md`) would need a raised per-route limit for every upload route. Direct upload needs no raised limit. | | F3 | Signing costs under 1 ms and needs no network call. The org check (slug resolve + one tenant query) is the only real work ddx-api does per URL. | | F4 | A private bucket refuses an unsigned read (403), so access control stays in ddx-api: no URL without the org check, and every URL ends at its TTL. | | F5 | The SigV4 signature includes the host. ddx-api must sign for the host the browser uses (`S3_PUBLIC_ENDPOINT`), not a Docker-internal name. In dev both are `127.0.0.1:16350`. | | F6 | Not measured here: a browser PUT needs MinIO CORS for the ddx-web origin (16300). MinIO's API allows all origins by default; the first ddx-web upload (task 030 side) confirms it. | ## Answer Presigned URLs, minted by ddx-api **after** the org check, short TTL (300 s default, 900 s cap), private buckets. The BFF only forwards the small JSON calls (`presign`, `complete`, `url`); the bytes never cross the BFF or ddx-api.

All pages (45)

- [ddx-documentation — dudoxx-web-boot](/en/docs) **adr/** - [ADR 0001 — Scaffold route: dudoxx-sandbox-creator with 163XX overrides](/en/docs/adr/0001-scaffold-route) - [ADR 0002 — Auth: better-auth 1.7 in ddx-api](/en/docs/adr/0002-auth-better-auth) - [ADR 0003 — Route shape: org slug, role, `[entity]/[id]`, `?view=`](/en/docs/adr/0003-route-shape) - [ADR 0004 — Database split: one Postgres 18 instance, six databases](/en/docs/adr/0004-database-split) - [ADR 0005 — Frameworks and the approved dependency table](/en/docs/adr/0005-frameworks) - [ADR 0006 — API clients come from one factory](/en/docs/adr/0006-factory) - [ADR 0007 — Typed service container (DI / IoC)](/en/docs/adr/0007-di-container) - [ADR 0008 — Singleton scope: what may live at module level](/en/docs/adr/0008-singleton-scope) - [ADR 0009 — One variant API for every inventory component](/en/docs/adr/0009-variant-api) - [ADR 0010 — Media path: presigned URLs from ddx-api after the org check](/en/docs/adr/0010-media-path) - [ADR 0011 — Media proxy: MinIO only through ddx-api](/en/docs/adr/0011-media-proxy) - [ADR 0012 — Density names: compact | cosy | large](/en/docs/adr/0012-density-names) - [ADR 0013 — Platform super-admin acts as org-admin of the target org](/en/docs/adr/0013-super-admin-platform-role) - [ADR 0014 — Unified settings: one registry, three tiers, one resolve in ddx-api](/en/docs/adr/0014-unified-settings) - [ADR 0015 — Entity kernel: one descriptor, one access seam, one projection, one proof chain](/en/docs/adr/0015-entity-kernel) - [ADR 0016 — SSE Bus: Redis Streams log, Redis pub/sub fan-out, BullMQ outbound queue](/en/docs/adr/0016-sse-bus) - [ADR 0017 — Layered BFF: one route table, route classes, read models](/en/docs/adr/0017-bff-layered) - [ADR 0018 — Cluster node registry, node identity, hot plug](/en/docs/adr/0018-cluster-node-registry) - [ADR 0019 — Tenant branding: settings keys, vendored palettes, public platform read](/en/docs/adr/0019-tenant-branding) - [Debug overlay](/en/docs/debug-overlay) **deploy/** - [Deploy runbook — dudoxx-web-boot](/en/docs/deploy/README) - [Entity kernel — guide](/en/docs/entity-kernel) - [Feature map — what each role can do](/en/docs/features) - [Component inventory](/en/docs/inventory) - [Naming constitution — dudoxx-web-boot](/en/docs/naming-constitution) - [Observability — one log layout, one key set](/en/docs/observability) - [Pattern reference — P1-P23 and groups A-K](/en/docs/patterns) - [Port map — dudoxx-web-boot](/en/docs/ports) **research/** - [RQ1 — Which release is "latest", and does it differ from the canon?](/en/docs/research/rq1-versions) - [RQ10 — SSE through the Next.js BFF route handler (desk half)](/en/docs/research/rq10-sse-through-bff) - [RQ11 — Dev latency baseline: cold compile per route + next-server RSS](/en/docs/research/rq11-dev-latency) - [RQ2 — Route group or dynamic org slug?](/en/docs/research/rq2-route-shape) - [RQ3 — better-auth 1.7 vs Auth.js v5: feature matrix](/en/docs/research/rq3-auth-matrix) - [RQ4 — Separate databases or separate schemas?](/en/docs/research/rq4-db-split) - [RQ5 — Which frameworks beyond shadcn earn a place?](/en/docs/research/rq5-frameworks) - [RQ6 — How do DI, IoC and Singleton behave across RSC, client bundles and NestJS?](/en/docs/research/rq6-di-scope) - [RQ7 — Which data uses the server cache, which uses TanStack Query, how is each invalidated?](/en/docs/research/rq7-cache-classes) - [**RQ8 — Media path: presigned URLs vs streaming through the BFF**](/en/docs/research/rq8-media-path) - [Template triage — create-nextjs code in ddx-web](/en/docs/research/template-triage) - [Settings — guide](/en/docs/settings) - [Local setup — dudoxx-web-boot](/en/docs/setup) - [Shell tree — SiteShell and PortalShell](/en/docs/shell-tree) - [SSE event catalog](/en/docs/sse-events) - [Version pins — dudoxx-web-boot](/en/docs/versions)

RQ8 — Media path: presigned URLs vs streaming through the BFF · R&D documentation | Dudoxx Web Boot

R&D documentation

RQ8 — Media path: presigned URLs vs streaming through the BFF

Source: ddx-documentation/research/rq8-media-path.md

Previous: RQ7 — Which data uses the server cache, which uses TanStack Query, how is each invalidated?Next: Template triage — create-nextjs code in ddx-web Inventory gallery

Question (task 024, WS4 G4.1-G4.3): should the browser move image bytes straight to MinIO with presigned URLs minted by ddx-api, or should the bytes stream through the ddx-web BFF and ddx-api?

Decision record: .

Spike (2026-10-23, task 024)

Setup: one 2 MiB random payload, 10 runs per path, Node v26.12.0, all on one dev host. MinIO container ddx-web-boot-minio (S3 API 127.0.0.1:16350), private bucket ddx-images, keys org/rq8-spike/image/<uuid> (all 20 deleted after the run).
Direct = ddx-api presigns (@aws-sdk/s3-request-presigner, TTL 300 s); the client PUTs / GETs MinIO itself.
Relay = two loopback HTTP hops: a BFF hop that pipes the stream, then an API hop that reads the body and calls PutObject / streams GetObject. This is the shape of "upload through api/v1".
Script: kept outside the repo (scratch). It reads the MinIO credentials from ddx-docker-minio/.env and never prints them.

Path	Median	Min	Max
presign (sign only, no network)	0.6 ms	0.5 ms	7.3 ms
PUT direct (presigned)	12.1 ms	10.8 ms	35.3 ms
PUT via 2 relay hops	18.8 ms	16.5 ms	24.4 ms
GET direct (presigned)	9.3 ms	8.1 ms	10.3 ms
GET via 2 relay hops	10.3 ms	9.3 ms	129.3 ms

Extra check: an unsigned GET of a spike object on the private bucket answered 403.

Findings

#	Finding
F1	Direct PUT is about 1.55× faster than the relay (12.1 vs 18.8 ms median) on loopback. Over a real network each relay hop adds one more full copy of the bytes, so the gap grows with distance and file size.
F2	The relay holds the whole body in ddx-api memory (the SDK `PutObject` needs a length) and counts against the API body limit. ddx-api's two-tier body limit (`ddx-api/CLAUDE.md`) would need a raised per-route limit for every upload route. Direct upload needs no raised limit.
F3	Signing costs under 1 ms and needs no network call. The org check (slug resolve + one tenant query) is the only real work ddx-api does per URL.
F4	A private bucket refuses an unsigned read (403), so access control stays in ddx-api: no URL without the org check, and every URL ends at its TTL.
F5	The SigV4 signature includes the host. ddx-api must sign for the host the browser uses (`S3_PUBLIC_ENDPOINT`), not a Docker-internal name. In dev both are `127.0.0.1:16350`.
F6	Not measured here: a browser PUT needs MinIO CORS for the ddx-web origin (16300). MinIO's API allows all origins by default; the first ddx-web upload (task 030 side) confirms it.

Answer

Presigned URLs, minted by ddx-api after the org check, short TTL (300 s default, 900 s cap), private buckets. The BFF only forwards the small JSON calls (presign, complete, url); the bytes never cross the BFF or ddx-api.