Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
feat(chat-media): archive verified media atomically
Yudhi Armyndharis9ee4db47f38c
diff --git a/.env.example b/.env.exampleindex 19b856b7a..928b53595 100644--- a/.env.example+++ b/.env.example@@ -655,6 +655,14 @@ WEBHOOK_SSRF_PROTECT=true# media columns; the message row itself is never deleted by this. A negative or malformed value# fails the boot.# CHAT_MEDIA_ARCHIVE_TTL_DAYS=0 # default 0 (keep forever)+# What happens to a message row's inline base64 once its media is archived. "inline" (default)+# keeps it, so archived media is stored twice. "archive" replaces it with the omitted marker+# ({ mimetype, filename?, omitted: true, sizeBytes, archived: true }) after the file is written and+# read back intact, so each file is stored once and served by the media route above. Anything that+# goes wrong keeps the inline copy. Needs CHAT_MEDIA_ARCHIVE_ENABLED=true (boot fails otherwise);+# media over CHAT_MEDIA_ARCHIVE_MAX_BYTES is not archived and stays inline; with a TTL above, an+# expired file takes the only copy with it. Rows stored before the switch keep their inline copy.+# MESSAGE_INLINE_MEDIA=inline # default inline# Orphaned chat-media reconciliation: how often the sweep re-lists chat-media files to find ones no# row references (crash leftovers), and how long a file must be seen unreferenced before deletion.# Unset takes the default; a value that is not a positive integer fails the boot, and so does adiff --git a/CHANGELOG.md b/CHANGELOG.mdindex d87c16358..9f9db9eb5 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Expose caller-supplied send idempotency keys in all five SDKs.- Add optional 24-hour idempotency keys to twelve single-recipient send routes.+- Add opt-in archive-only chat media with dashboard previews.+### Fixed- Preserve webhook outbox payloads until delivery or durable failure storage succeeds.diff --git a/dashboard/src/components/chats/ArchivedMediaPreview.test.ts b/dashboard/src/components/chats/ArchivedMediaPreview.test.tsnew file mode 100644index 000000000..509705b66--- /dev/null+++ b/dashboard/src/components/chats/ArchivedMediaPreview.test.ts@@ -0,0 +1,106 @@+// Render test for the archive-only media preview: an `{ omitted: true, archived: true }` marker must+// still show its image/video/audio inline (fetched from the media route), release the object URL it+// made, and fall back to the download button when the bytes cannot be fetched.+import '../../test-helpers/register-hooks.ts';+import { test, before, afterEach } from 'node:test';+import assert from 'node:assert/strict';+import { createElement } from 'react';++type RTL = typeof import('@testing-library/react');++let rtl: RTL;+let ArchivedMediaPreview: typeof import('./ArchivedMediaPreview.tsx').default;++const created: string[] = [];+const revoked: string[] = [];++before(async () => {+ const { installJsdomGlobals } = await import('../../test-helpers/jsdom.ts');+ await installJsdomGlobals();+ rtl = await import('@testing-library/react');+ ({ default: ArchivedMediaPreview } = await import('./ArchivedMediaPreview.tsx'));+ // jsdom implements neither.+ URL.createObjectURL = (): string => {+ const url = `blob:mock-${created.length}`;+ created.push(url);+ return url;+ };+ URL.revokeObjectURL = (url: string): void => void revoked.push(url);+});++afterEach(() => {+ rtl.cleanup();+ created.length = 0;+ revoked.length = 0;+});++const fallback = createElement('button', { type: 'button', className: 'message-media-omitted' }, 'Media');++test('an archived image loads once from the media route and renders from an object URL', async () => {+ let calls = 0;+ const { container, unmount } = rtl.render(+ createElement(ArchivedMediaPreview, {+ kind: 'image',+ alt: 'photo.jpg',+ fallback,+ load: async () => {+ calls += 1;+ return new Blob(['x'], { type: 'image/jpeg' });+ },+ }),+ );+ const img = await rtl.waitFor(() => {+ const found = container.querySelector('img.chat-image-media');+ assert.ok(found, 'the archived image did not render');+ return found as HTMLImageElement;+ });+ assert.equal(img.getAttribute('src'), 'blob:mock-0');+ assert.equal(calls, 1, 'the bytes are fetched exactly once');+ assert.deepEqual(revoked, [], 'the URL stays valid while the image is on screen');+ unmount();+ assert.deepEqual(revoked, ['blob:mock-0'], 'unmounting releases the object URL');+});++test('video and audio render their own elements', async () => {+ for (const [kind, selector] of [+ ['video', 'video.chat-video-media'],+ ['audio', 'audio.chat-audio-media'],+ ] as const) {+ const { container } = rtl.render(+ createElement(ArchivedMediaPreview, { kind, fallback, load: async () => new Blob(['x']) }),+ );+ await rtl.waitFor(() => assert.ok(container.querySelector(selector), `${kind} did not render`));+ rtl.cleanup();+ }+});++test('a failed fetch falls back to the download button instead of a broken preview', async () => {+ const { container } = rtl.render(+ createElement(ArchivedMediaPreview, {+ kind: 'image',+ fallback,+ load: async () => {+ throw new Error('404');+ },+ }),+ );+ await rtl.waitFor(() => assert.ok(container.querySelector('button.message-media-omitted')));+ assert.equal(container.querySelector('img'), null);+ assert.deepEqual(created, [], 'no object URL is made for a failed fetch');+});++test('a response landing after unmount makes no object URL', async () => {+ let resolve!: (blob: Blob) => void;+ const { unmount } = rtl.render(+ createElement(ArchivedMediaPreview, {+ kind: 'image',+ fallback,+ load: () => new Promise<Blob>(r => (resolve = r)),+ }),+ );+ await rtl.waitFor(() => assert.ok(resolve, 'the fetch did not start'));+ unmount();+ resolve(new Blob(['x']));+ await new Promise(r => setTimeout(r, 0));+ assert.deepEqual(created, [], 'a late response must not leak a URL nothing will revoke');+});diff --git a/dashboard/src/components/chats/ArchivedMediaPreview.tsx b/dashboard/src/components/chats/ArchivedMediaPreview.tsxnew file mode 100644index 000000000..3960bc609--- /dev/null+++ b/dashboard/src/components/chats/ArchivedMediaPreview.tsx@@ -0,0 +1,125 @@+import { useEffect, useRef, useState, type ReactNode } from 'react';+import { Loader2 } from 'lucide-react';++export type ArchivedMediaKind = 'image' | 'video' | 'audio';++interface ArchivedMediaPreviewProps {+ kind: ArchivedMediaKind;+ /** Fetches the archived bytes (the per-message media route). Called at most once per mount. */+ load: () => Promise<Blob>;+ alt?: string;+ /** Rendered instead of the preview when the fetch fails , the download button, so the bytes stay reachable. */+ fallback: ReactNode;+ measureMedia?: (el: Element | null) => void;+ onMediaLoad?: (event?: { currentTarget: Element | null }) => void;+}++type PreviewState = { phase: 'waiting' | 'loading' | 'failed' } | { phase: 'ready'; url: string };++// An inline preview for media whose list payload is the `{ omitted: true, archived: true }` marker ,+// what MESSAGE_INLINE_MEDIA=archive leaves once the bytes are verified on the archive store. The+// archive is the only copy then, so without this an image would read as a bare "Media" button where+// it used to render. A plain over-budget marker (no `archived`) keeps the click-to-download button:+// those bytes may be multi-megabyte inline payloads, and fetching each one as it scrolls past would+// turn browsing into bulk download.+//+// Fetched lazily, once the bubble nears the viewport, so opening a media-heavy chat does not fire one+// request per archived message at once. Where IntersectionObserver is unavailable (old browsers, the+// jsdom test runtime) it loads immediately rather than never. The object URL is revoked on unmount so+// scrolling through a long thread does not accumulate blobs.+function ArchivedMediaPreview({ kind, load, alt, fallback, measureMedia, onMediaLoad }: ArchivedMediaPreviewProps) {+ const [state, setState] = useState<PreviewState>({ phase: 'waiting' });+ const anchorRef = useRef<HTMLDivElement | null>(null);+ // `load` is usually an inline arrow, so a fresh identity every render; holding it in a ref keeps+ // the effects below from re-running (and re-fetching) on each parent render.+ const loadRef = useRef(load);+ useEffect(() => {+ loadRef.current = load;+ });+ // The object URL the ready render points at. Revoked on unmount only , the phase never leaves+ // `ready`, so the URL stays valid for as long as the element showing it exists.+ const urlRef = useRef<string | null>(null);+ useEffect(+ () => () => {+ if (urlRef.current) URL.revokeObjectURL(urlRef.current);+ urlRef.current = null;+ },+ [],+ );++ // Phase 1: wait until the bubble is near the viewport.+ useEffect(() => {+ if (state.phase !== 'waiting') return undefined;+ const el = anchorRef.current;+ if (!el || typeof IntersectionObserver === 'undefined') {+ setState({ phase: 'loading' });+ return undefined;+ }+ const observer = new IntersectionObserver(+ entries => {+ if (entries.some(entry => entry.isIntersecting)) {+ observer.disconnect();+ setState({ phase: 'loading' });+ }+ },+ // A screen's worth of lead so the bytes are usually there by the time the bubble scrolls in.+ { rootMargin: '600px 0px' },+ );+ observer.observe(el);+ return () => observer.disconnect();+ }, [state.phase]);++ // Phase 2: fetch once. A response landing after unmount is dropped rather than turned into a URL+ // nothing would ever revoke.+ useEffect(() => {+ if (state.phase !== 'loading') return undefined;+ let cancelled = false;+ loadRef+ .current()+ .then(blob => {+ if (cancelled) return;+ const url = URL.createObjectURL(blob);+ urlRef.current = url;+ setState({ phase: 'ready', url });+ })+ .catch(() => {+ if (!cancelled) setState({ phase: 'failed' });+ });+ return () => {+ cancelled = true;+ };+ }, [state.phase]);++ if (state.phase === 'failed') return <>{fallback}</>;++ if (state.phase !== 'ready') {+ return (+ <div ref={anchorRef} className="message-media-omitted message-media-archived-loading" aria-busy="true">+ <Loader2 size={14} className="animate-spin" />+ </div>+ );+ }++ switch (kind) {+ case 'image':+ return (+ <div className="message-media-image">+ <img src={state.url} alt={alt ?? ''} className="chat-image-media" ref={measureMedia} onLoad={onMediaLoad} />+ </div>+ );+ case 'video':+ return (+ <div className="message-media-video">+ <video ref={measureMedia} src={state.url} controls className="chat-video-media" onLoadedData={onMediaLoad} />+ </div>+ );+ case 'audio':+ return (+ <div className="message-media-audio">+ <audio src={state.url} controls className="chat-audio-media" />+ </div>+ );+ }+}++export default ArchivedMediaPreview;diff --git a/dashboard/src/components/chats/ChatThread.test.ts b/dashboard/src/components/chats/ChatThread.test.tsindex f224429d9..1f59f6b09 100644--- a/dashboard/src/components/chats/ChatThread.test.ts+++ b/dashboard/src/components/chats/ChatThread.test.ts@@ -172,3 +172,48 @@ test('a document sent by URL opens in a new tab instead of navigating the dashboassert.equal(inline.getAttribute('target'), null);assert.equal(inline.getAttribute('download'), 'inline.pdf');});++test('archive-only media previews inline from the media route; a plain omitted marker and a document keep the button', async () => {+ // MESSAGE_INLINE_MEDIA=archive leaves `{ omitted, archived }` on the row: the image rendered inline+ // before, so it must still. The over-budget marker (no `archived`) must not fetch on render, and a+ // document has nothing to preview.+ const media = (id: string, type: ChatMessageView['type'], archived: boolean): ChatMessageView => ({+ ...PROMPT,+ id,+ waMessageId: `wamid.${id}`,+ body: '',+ type,+ metadata: { media: { mimetype: 'image/jpeg', filename: `${id}.jpg`, omitted: true, sizeBytes: 10, archived } },+ });+ const fetched: string[] = [];+ const fetchOriginal = globalThis.fetch;+ const createOriginal = URL.createObjectURL;+ const revokeOriginal = URL.revokeObjectURL;+ globalThis.fetch = (async (input: RequestInfo | URL) => {+ fetched.push(String(input));+ return new Response(new Blob(['x'], { type: 'image/jpeg' }), { status: 200 });+ }) as typeof fetch;+ URL.createObjectURL = () => 'blob:archived';+ URL.revokeObjectURL = () => {};+ try {+ const { container } = renderThread('viewer', [+ media('arch', 'image', true),+ media('plain', 'image', false),+ media('doc', 'document', true),+ ]);+ const img = await rtl.waitFor(() => {+ const found = container.querySelector('[data-wa-message-id="wamid.arch"] img.chat-image-media');+ assert.ok(found, 'the archived image did not preview');+ return found;+ });+ assert.equal(img.getAttribute('src'), 'blob:archived');+ assert.equal(fetched.length, 1, 'only the archived image is fetched on render');+ assert.match(fetched[0], /\/messages\/.+\/wamid\.arch\/media$/);+ assert.ok(container.querySelector('[data-wa-message-id="wamid.plain"] button.message-media-omitted'));+ assert.ok(container.querySelector('[data-wa-message-id="wamid.doc"] button.message-media-omitted'));+ } finally {+ globalThis.fetch = fetchOriginal;+ URL.createObjectURL = createOriginal;+ URL.revokeObjectURL = revokeOriginal;+ }+});diff --git a/dashboard/src/components/chats/ChatThread.tsx b/dashboard/src/components/chats/ChatThread.tsxindex 498309b10..0aa9c0f0f 100644--- a/dashboard/src/components/chats/ChatThread.tsx+++ b/dashboard/src/components/chats/ChatThread.tsx@@ -11,6 +11,7 @@ import {type ChatMessageView,} from '../../utils/chatMessages';import { shouldFetchOlderMessages } from '../../utils/scrollDecision';+import ArchivedMediaPreview, { type ArchivedMediaKind } from './ArchivedMediaPreview';import MessageBody from './MessageBody';// Stable per-sender colour for group message labels, like WhatsApp gives each participant a colour.@@ -318,7 +319,7 @@ function ChatThread({// Not a plain label: the bytes exist behind the per-message media route, so this is the// only handle the viewer has on them.const fetchState = msg.waMessageId ? mediaFetch[msg.waMessageId] : undefined;- return (+ const downloadButton = (<buttontype="button"className="message-media-omitted"@@ -332,6 +333,32 @@ function ChatThread({)}</button>);+ // `archived` marks a copy MESSAGE_INLINE_MEDIA=archive moved off the row once the archive+ // store held it: the bubble rendered inline before, so it previews inline still, fetched+ // lazily from the same route. Documents keep the button (there is nothing to preview),+ // and so does a plain over-budget marker , see ArchivedMediaPreview for why.+ const previewKind: ArchivedMediaKind | null =+ msg.type === 'image' || msg.type === 'sticker'+ ? 'image'+ : msg.type === 'video'+ ? 'video'+ : msg.type === 'audio' || msg.type === 'voice'+ ? 'audio'+ : null;+ const waMessageId = msg.waMessageId;+ if (mediaInfo.archived && previewKind && sessionId && waMessageId) {+ return (+ <ArchivedMediaPreview+ kind={previewKind}+ load={() => sessionApi.getMessageMediaBlob(sessionId, activeChat.id, waMessageId)}+ alt={mediaInfo.filename || t('chats.media.image')}+ fallback={downloadButton}+ measureMedia={measureMedia}+ onMediaLoad={onMediaLoad}+ />+ );+ }+ return downloadButton;}const mediaSrc = getMediaSrc(mediaInfo);if (!mediaSrc) return null;diff --git a/dashboard/src/services/api.ts b/dashboard/src/services/api.tsindex 37362f55e..0de77199a 100644--- a/dashboard/src/services/api.ts+++ b/dashboard/src/services/api.ts@@ -316,7 +316,15 @@ export interface ChatMessage {timestamp?: number;createdAt: string;metadata?: {- media?: { mimetype: string; filename?: string; data?: string; omitted?: boolean; sizeBytes?: number };+ media?: {+ mimetype: string;+ filename?: string;+ data?: string;+ omitted?: boolean;+ sizeBytes?: number;+ /** With `omitted`: the inline copy was dropped because the chat-media archive holds the bytes. */+ archived?: boolean;+ };quotedMessage?: { id: string; body: string };reactions?: Record<string, string>;call?: { video: boolean; missed: boolean };@@ -378,6 +386,7 @@ export interface EngineHistoryMessage {data?: string;omitted?: boolean;sizeBytes?: number;+ archived?: boolean;};quotedMessage?: { id: string; body: string };location?: { latitude: number; longitude: number; description?: string; address?: string; url?: string };diff --git a/dashboard/src/utils/chatMessages.ts b/dashboard/src/utils/chatMessages.tsindex a818fbabb..588f1addf 100644--- a/dashboard/src/utils/chatMessages.ts+++ b/dashboard/src/utils/chatMessages.ts@@ -216,6 +216,11 @@ export type MessageMedia = {data?: string;omitted?: boolean;sizeBytes?: number;+ /**+ * Set alongside `omitted` when MESSAGE_INLINE_MEDIA=archive dropped the inline copy because the+ * chat-media archive holds the bytes , the media route serves them, so the thread previews inline.+ */+ archived?: boolean;};export const getMediaSrc = (media?: MessageMedia): string => {diff --git a/docker-compose.dev.yml b/docker-compose.dev.ymlindex f46cb97c1..7a25810a9 100644--- a/docker-compose.dev.yml+++ b/docker-compose.dev.yml@@ -128,6 +128,7 @@ services:- CHAT_MEDIA_ARCHIVE_OUTBOUND=${CHAT_MEDIA_ARCHIVE_OUTBOUND:-}- CHAT_MEDIA_ARCHIVE_MAX_BYTES=${CHAT_MEDIA_ARCHIVE_MAX_BYTES:-}- CHAT_MEDIA_ARCHIVE_TTL_DAYS=${CHAT_MEDIA_ARCHIVE_TTL_DAYS:-}+ - MESSAGE_INLINE_MEDIA=${MESSAGE_INLINE_MEDIA:-}- CHAT_MEDIA_ORPHAN_SWEEP_INTERVAL_MS=${CHAT_MEDIA_ORPHAN_SWEEP_INTERVAL_MS:-}- CHAT_MEDIA_ORPHAN_GRACE_MS=${CHAT_MEDIA_ORPHAN_GRACE_MS:-}- SEND_PACING_ENABLED=${SEND_PACING_ENABLED:-}diff --git a/docker-compose.yml b/docker-compose.ymlindex 34b4ee732..858527745 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -201,6 +201,7 @@ services:- CHAT_MEDIA_ARCHIVE_OUTBOUND=${CHAT_MEDIA_ARCHIVE_OUTBOUND:-}- CHAT_MEDIA_ARCHIVE_MAX_BYTES=${CHAT_MEDIA_ARCHIVE_MAX_BYTES:-}- CHAT_MEDIA_ARCHIVE_TTL_DAYS=${CHAT_MEDIA_ARCHIVE_TTL_DAYS:-}+ - MESSAGE_INLINE_MEDIA=${MESSAGE_INLINE_MEDIA:-}- CHAT_MEDIA_ORPHAN_SWEEP_INTERVAL_MS=${CHAT_MEDIA_ORPHAN_SWEEP_INTERVAL_MS:-}- CHAT_MEDIA_ORPHAN_GRACE_MS=${CHAT_MEDIA_ORPHAN_GRACE_MS:-}# Send pacing (opt-in anti-ban governor). Forwarded explicitly for the same reason as thediff --git a/docs/03-system-architecture.md b/docs/03-system-architecture.mdindex 58f703c54..11683c2b1 100644--- a/docs/03-system-architecture.md+++ b/docs/03-system-architecture.md@@ -1312,6 +1312,8 @@ also writes status media through `putFile` (under `statuses/`) and sweeps orphan`deleteFile`. Incoming and outgoing message media is returned inline to REST/webhook consumers and is**not** written through `StorageService` unless `CHAT_MEDIA_ARCHIVE_ENABLED=true`, which archives a copyunder `chat-media/<sessionId>/` (media this account sent also needs `CHAT_MEDIA_ARCHIVE_OUTBOUND=true`).+That copy is in addition to the inline one unless `MESSAGE_INLINE_MEDIA=archive`, which replaces the+row's inline base64 with an `{ omitted: true, archived: true }` marker once the file reads back intact.On S3 every key sits under the `S3_KEY_PREFIX` root (default `media/`).**MinIO is not a separate type** β it is the `s3` backend. The S3 client is created from credentialsalone, so plain AWS S3 works with no endpoint (the SDK derives one from the region); `S3_ENDPOINT` isdiff --git a/docs/05-database-design.md b/docs/05-database-design.mdindex b9e45d1c6..2433d1a07 100644--- a/docs/05-database-design.md+++ b/docs/05-database-design.md@@ -855,8 +855,8 @@ flowchart LROpenWA runs **two separate TypeORM connections**, each with its own migrations directory and CLI DataSource:-| Connection | DataSource | Migrations dir | Owns |-| ---------- | --------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Connection | DataSource | Migrations dir | Owns |+| ---------- | --------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || **main** | `data-source-main.ts` | `src/database/migrations-main/` | `api_keys`, `audit_logs`, always SQLite (`./data/main.sqlite` by default) || **data** | `data-source.ts` | `src/database/migrations/` | `sessions`, `webhooks`, `messages`, `message_batches`, `templates`, `status_updates`, `automation_rules`, `webhook_delivery_failures`, `webhook_outbox_events`, `send_idempotency_keys`, the integration tables (`plugin_instances`, `ingress_events`, `conversation_mappings`, `integration_delivery_failures`), engine tables, SQLite **or** PostgreSQL |diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex fe6b0354d..2da23139c 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -1353,7 +1353,7 @@ Get persisted message history for a session from the local DB (paginated, filterEach `Message`: `{ id (uuid), sessionId, waMessageId (string|null), chatId, from, to, chatName (string|null; the sender's push name, or their saved contact name when no push name was reported), author (string|null; the real sender of a group, status or broadcast-list message, where from holds the group, status@broadcast or list id; on Baileys a list message the account received is filed under the sender, so from is the sender too), body (string|null), type, direction ('incoming'|'outgoing'), timestamp (number|null), metadata (object|null), mediaPath (string|null; storage key of archived media), mediaMimetype (string|null), status ('pending'|'sent'|'delivered'|'read'|'failed'), createdAt (ISO date) }`. Ordered by `createdAt` DESC, then by a dialect-dependent second key. The tiebreaker matters: `createdAt` is not unique (SQLite stores whole seconds, a PostgreSQL bulk write ties every row it inserts, and a history backfill carries WhatsApp's own second-resolution timestamp), and without a total order two pages of one walk can repeat a row and omit another. On SQLite the second key is `rowid`, the stored insertion sequence, so messages sharing a second come back in the order they arrived. PostgreSQL has no equivalent (`ctid` moves on every ack update), so it keeps `id`, a random uuid: the walk is equally correct there, but a same-second group is not in arrival order. Note that `offset` still addresses a position by count, so a list taking concurrent writes can shift under a walk: a message arriving mid-walk pushes every older row down one, and the next page re-serves a row the previous one already returned. Pass `after` instead to walk a live chat safely; it anchors on the last row you received, which an arriving message cannot move. The response is the raw service object (no envelope). Unlike the live `IncomingMessage` shape below, this persisted `Message` does **not** carry `kind` β re-derive the chat kind from `chatId` (see `ChatKind` / `chatKind()`) if needed. When present, `metadata` may include `media`, `quotedMessage`, `call`, `reactions`, and, for Baileys inbound business prompts, `buttons: [{ id, text }, β¦]` so a client (including the dashboard Chats thread) can re-render the choices after reload and tap them via [`POST .../click-button`](#post-apisessionssessionidmessagesclick-button).-> **Inline media is carried up to a budget, then omitted.** `MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES` (8 MiB of encoded base64 by default) bounds how much inline media one response may hold across its rows. A row is not a bounded object β `limit` is clamped to `[1,100]` but each row can carry its base64 in `metadata.media.data`, so a page of media rows could otherwise reach hundreds of megabytes and fail the read outright. The budget is spent newest-first, matching the `createdAt` DESC order above, so a page that cannot carry everything keeps the most recent media. Past it a payload is replaced with `{ mimetype, filename?, omitted: true, sizeBytes }` β the same marker the engine emits for inbound media over `MEDIA_DOWNLOAD_MAX_BYTES` β and the bytes remain available from [`GET /messages/:chatId/:messageId/media`](#get-apisessionssessionidmessageschatidmessageidmedia). Two rules bound the edges: the newest payload is always inlined even when it alone exceeds the budget (otherwise a single large photo would be permanently unreadable through this route), and a budget of `0` means "never inline" and grants no such allowance. The knob is validated at boot β `8MiB` would parse to 8 bytes β and is forwarded by both compose files. The MCP `MessageList` tool shares this path and the same budget.+> **Inline media is carried up to a budget, then omitted.** `MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES` (8 MiB of encoded base64 by default) bounds how much inline media one response may hold across its rows. A row is not a bounded object , `limit` is clamped to `[1,100]` but each row can carry its base64 in `metadata.media.data`, so a page of media rows could otherwise reach hundreds of megabytes and fail the read outright. The budget is spent newest-first, matching the `createdAt` DESC order above, so a page that cannot carry everything keeps the most recent media. Past it a payload is replaced with `{ mimetype, filename?, omitted: true, sizeBytes }` , the same marker the engine emits for inbound media over `MEDIA_DOWNLOAD_MAX_BYTES` , and the bytes remain available from [`GET /messages/:chatId/:messageId/media`](#get-apisessionssessionidmessageschatidmessageidmedia). Two rules bound the edges: the newest payload is always inlined even when it alone exceeds the budget (otherwise a single large photo would be permanently unreadable through this route), and a budget of `0` means "never inline" and grants no such allowance. The knob is validated at boot , `8MiB` would parse to 8 bytes , and is forwarded by both compose files. The MCP `MessageList` tool shares this path and the same budget. A row stored under `MESSAGE_INLINE_MEDIA=archive` arrives with the marker already in place, plus `archived: true` , its bytes live only in the chat-media archive, behind the same media route (see that route for the mode).**Errors:** `400` `after` names no message in this session Β· `401` missing/invalid API key Β· `403` a key restricted to selected chats sent no `chatId`, or one outside its allowlist@@ -1555,6 +1555,22 @@ The inline fallback also keeps an inbound message's media downloadable after`CHAT_MEDIA_ARCHIVE_TTL_DAYS` retention purges the archived file, since retention leaves the inlinecopy in place.+**Archive-only storage (`MESSAGE_INLINE_MEDIA=archive`).** By default an archived file is a second+copy: the row keeps its inline base64 too. Setting `MESSAGE_INLINE_MEDIA=archive` (it needs+`CHAT_MEDIA_ARCHIVE_ENABLED=true`; the boot fails otherwise) stores each archived file once: after+the file is written, read back byte for byte and the row points at it, the row's+`metadata.media` is replaced with `{ mimetype, filename?, omitted: true, sizeBytes, archived: true }`,+and this route becomes the only way to the bytes. Any failure along the way (a store that does not+read back intact, a row revoked or re-pointed meanwhile) keeps the inline copy, so the mode can miss+a saving but not lose media. What it does not cover: media over `CHAT_MEDIA_ARCHIVE_MAX_BYTES` is+not archived and stays inline; outbound media is archived (and replaced) only with+`CHAT_MEDIA_ARCHIVE_OUTBOUND=true`; rows stored before the switch keep their inline copy. Two+consequences to weigh before enabling it: with a non-zero `CHAT_MEDIA_ARCHIVE_TTL_DAYS`, retention+now removes the only copy, after which this route answers `404`; and a database export no longer+carries those bytes, so back up the media store alongside the database. Webhook payloads carry the+in-memory engine message rather than the row, so they are unaffected. The dashboard previews+archived images, video and audio inline by fetching them from this route.+A revoked message (deleted for everyone, or through `POST /messages/delete`) has no media: its row iscleared on revoke, and this route answers `404` for it.diff --git a/docs/10-devops-infrastructure.md b/docs/10-devops-infrastructure.mdindex a40a897b1..c9a2f24ea 100644--- a/docs/10-devops-infrastructure.md+++ b/docs/10-devops-infrastructure.md@@ -383,6 +383,8 @@ LOG_FORMAT=json# chat-media/<sessionId>/; media this account sent also needs CHAT_MEDIA_ARCHIVE_OUTBOUND=true.# With the archive off, chat media stays inline on the message row (up to MEDIA_DOWNLOAD_MAX_BYTES),# where GET /api/sessions/:sessionId/messages/:chatId/:messageId/media still serves it.+# With the archive on, the row keeps its inline copy too unless MESSAGE_INLINE_MEDIA=archive, which+# makes the store the only copy of archived media: back it up alongside the database.# On S3 every key sits under the S3_KEY_PREFIX root (default media/, so media/chat-media/...).# While S3 has not been reachable since boot, or its credentials are missing, files go to# STORAGE_LOCAL_PATH instead.diff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.mdindex d1e5414d6..3ac62d2d0 100644--- a/docs/11-operational-runbooks.md+++ b/docs/11-operational-runbooks.md@@ -994,7 +994,8 @@ find /backups -name "*.tar.gz" -mtime +30 -delete# keeps the old environment. Sessions reconnect on their own only with AUTO_START_SESSIONS=true;# otherwise POST /api/sessions/{sessionId}/start each one. Expiry clears the file and the row's# media columns. Under the production compose the media lives in the openwa_openwa-data volume,-# not in ./data in the checkout.+# not in ./data in the checkout. With MESSAGE_INLINE_MEDIA=archive the expired file is the only+# copy (no inline fallback), so expiry makes that media unreadable for good.# 4. Verifydf -hdiff --git a/src/config/configuration.ts b/src/config/configuration.tsindex 8d0e3703d..ba849a4fd 100644--- a/src/config/configuration.ts+++ b/src/config/configuration.ts@@ -456,6 +456,11 @@ export default () => ({const n = parseInt(process.env.CHAT_MEDIA_ORPHAN_GRACE_MS ?? '', 10);return Number.isFinite(n) && n > 0 ? n : 60 * 60 * 1000;})(),+ // What happens to a row's inline base64 once its media is archived. 'inline' (the default) keeps+ // it, as before. 'archive' replaces it with the omitted marker after the file is stored and+ // verified, so the bytes live once, in the file store; reads go through the media route.+ // Validated at boot to need CHAT_MEDIA_ARCHIVE_ENABLED=true.+ inlineMode: process.env.MESSAGE_INLINE_MEDIA === 'archive' ? ('archive' as const) : ('inline' as const),},// Session ownership across processes. A session's engine runs in exactly one process; thesediff --git a/src/config/env-precedence.ts b/src/config/env-precedence.tsindex 342b9f6a1..695fbe33f 100644--- a/src/config/env-precedence.ts+++ b/src/config/env-precedence.ts@@ -65,6 +65,7 @@ export const BLANK_SHADOWED_ENV_KEYS: string[] = ['CHAT_MEDIA_ARCHIVE_OUTBOUND','CHAT_MEDIA_ARCHIVE_MAX_BYTES','CHAT_MEDIA_ARCHIVE_TTL_DAYS',+ 'MESSAGE_INLINE_MEDIA','CHAT_MEDIA_ORPHAN_SWEEP_INTERVAL_MS','CHAT_MEDIA_ORPHAN_GRACE_MS',// Send pacing. Blank-forwarded by compose like the chat-media keys, so an operator who setsdiff --git a/src/config/env.validation.spec.ts b/src/config/env.validation.spec.tsindex d9e97cf34..5406c00b7 100644--- a/src/config/env.validation.spec.ts+++ b/src/config/env.validation.spec.ts@@ -104,6 +104,21 @@ describe('validateEnv', () => {expect(() => validateEnv({ STORAGE_TYPE: 's3' })).not.toThrow();});+ it('accepts MESSAGE_INLINE_MEDIA inline or archive, and refuses a typo', () => {+ expect(() => validateEnv({ MESSAGE_INLINE_MEDIA: 'inline' })).not.toThrow();+ expect(() => validateEnv({ MESSAGE_INLINE_MEDIA: 'archive', CHAT_MEDIA_ARCHIVE_ENABLED: 'true' })).not.toThrow();+ expect(() => validateEnv({ MESSAGE_INLINE_MEDIA: 'archived' })).toThrow(/MESSAGE_INLINE_MEDIA must be one of/);+ });++ it('refuses MESSAGE_INLINE_MEDIA=archive without the archiver, which would silently do nothing', () => {+ expect(() => validateEnv({ MESSAGE_INLINE_MEDIA: 'archive' })).toThrow(+ /MESSAGE_INLINE_MEDIA=archive needs CHAT_MEDIA_ARCHIVE_ENABLED=true/,+ );+ expect(() => validateEnv({ MESSAGE_INLINE_MEDIA: 'archive', CHAT_MEDIA_ARCHIVE_ENABLED: 'false' })).toThrow(+ /needs CHAT_MEDIA_ARCHIVE_ENABLED=true/,+ );+ });+// The runtime compares these raw (`=== 'postgres'`, the engine plugin lookup, `=== 's3'`), so a// padded value that only matches after trimming would validate here and then take the default branch.it.each([diff --git a/src/config/env.validation.ts b/src/config/env.validation.tsindex eeff25849..5328acd66 100644--- a/src/config/env.validation.ts+++ b/src/config/env.validation.ts@@ -100,6 +100,13 @@ export function validateEnv(config: EnvConfig): EnvConfig {};checkEnum('ENGINE_TYPE', ['whatsapp-web.js', 'baileys']);checkEnum('STORAGE_TYPE', ['local', 's3']);+ checkEnum('MESSAGE_INLINE_MEDIA', ['inline', 'archive']);+ // 'archive' drops the inline copy only after the archiver stored the file; with the archiver off+ // nothing is ever stored, so the mode would silently do nothing. Refuse that rather than let an+ // operator believe the inline copies are being reclaimed.+ if (rawEnum('MESSAGE_INLINE_MEDIA') === 'archive' && config.CHAT_MEDIA_ARCHIVE_ENABLED !== 'true') {+ errors.push('MESSAGE_INLINE_MEDIA=archive needs CHAT_MEDIA_ARCHIVE_ENABLED=true');+ }// The S3 key root. A prefix that is absolute, traverses, or is only slashes would put this// deployment's objects (and its orphan sweeps' deletes) at the bucket root or outside its own root;// one with an empty or '.' segment builds keys an S3-compatible store refuses on every write.diff --git a/src/modules/chat-media/chat-media-archive.service.spec.ts b/src/modules/chat-media/chat-media-archive.service.spec.tsindex db6633924..792476d89 100644--- a/src/modules/chat-media/chat-media-archive.service.spec.ts+++ b/src/modules/chat-media/chat-media-archive.service.spec.ts@@ -68,6 +68,7 @@ describe('ChatMediaArchiveService', () => {});afterEach(async () => {+ jest.restoreAllMocks();await repository.clear();for await (const file of storageService.iterateFiles('')) await storageService.deleteFile(file);});@@ -224,6 +225,151 @@ describe('ChatMediaArchiveService', () => {});});+ describe('archive with MESSAGE_INLINE_MEDIA=archive', () => {+ const replacing = (overrides: Record<string, unknown> = {}): ChatMediaArchiveService =>+ enabled({ 'chatMedia.inlineMode': 'archive', ...overrides });+ const mediaOf = async (id: string) =>+ ((await repository.findOneByOrFail({ id })).metadata as { media: Record<string, unknown> }).media;++ it('replaces the inline copy with the archived marker once the file is stored', async () => {+ const row = await saveRow({ mimetype: 'image/png', data: PNG.toString('base64'), filename: 'cat.png' });++ const key = await replacing().archive(row);++ expect(key).not.toBeNull();+ expect(await mediaOf(row.id)).toEqual({+ mimetype: 'image/png',+ filename: 'cat.png',+ omitted: true,+ sizeBytes: PNG.length,+ archived: true,+ });+ // The bytes now live once, in the store, and the media route reads them from there.+ expect(await storageService.getFile(key!)).toEqual(PNG);+ });++ it('keeps the rest of the metadata the row gained since it was persisted', async () => {+ const row = await saveRow({ mimetype: 'image/png', data: PNG.toString('base64') });+ await repository.update(+ { id: row.id },+ {+ metadata: { ...row.metadata, quotedMessage: { id: 'q1', body: 'hi' } },+ },+ );++ await replacing().archive(row);++ const reloaded = await repository.findOneByOrFail({ id: row.id });+ expect((reloaded.metadata as { quotedMessage: unknown }).quotedMessage).toEqual({ id: 'q1', body: 'hi' });+ expect((reloaded.metadata as { media: { data?: string } }).media.data).toBeUndefined();+ });++ it('keeps the inline copy when the stored file does not read back intact', async () => {+ const base64 = PNG.toString('base64');+ const row = await saveRow({ mimetype: 'image/png', data: base64 });+ const get = jest.spyOn(storageService, 'getFile').mockResolvedValueOnce(Buffer.from('truncated'));++ expect(await replacing().archive(row)).toBeNull();++ expect((await mediaOf(row.id)).data).toBe(base64);+ expect((await repository.findOneByOrFail({ id: row.id })).mediaPath).toBeNull();+ get.mockRestore();+ });++ it('keeps the inline copy when the read-back fails', async () => {+ const base64 = PNG.toString('base64');+ const row = await saveRow({ mimetype: 'image/png', data: base64 });+ const get = jest.spyOn(storageService, 'getFile').mockRejectedValueOnce(new Error('s3 down'));++ await expect(replacing().archive(row)).resolves.toBeNull();++ expect((await mediaOf(row.id)).data).toBe(base64);+ expect((await repository.findOneByOrFail({ id: row.id })).mediaPath).toBeNull();+ get.mockRestore();+ });++ it('keeps metadata changed between the inline snapshot and replacement', async () => {+ const base64 = PNG.toString('base64');+ const row = await saveRow({ mimetype: 'image/png', data: base64 });+ const originalFindOne = repository.findOne.bind(repository);+ const find = jest.spyOn(repository, 'findOne').mockImplementationOnce(async options => {+ const snapshot = await originalFindOne(options);+ await repository.update({ id: row.id }, { metadata: { ...row.metadata, reactions: { user: 'ok' } } });+ return snapshot;+ });++ await replacing().archive(row);++ find.mockRestore();+ const current = await repository.findOneByOrFail({ id: row.id });+ expect(current.metadata).toEqual({ ...row.metadata, reactions: { user: 'ok' } });+ expect(current.mediaPath).toBeNull();+ });++ it('keeps an inline payload that changed while the archive was written', async () => {+ const row = await saveRow({ mimetype: 'image/png', data: PNG.toString('base64') });+ const changedMedia = { mimetype: 'image/png', data: Buffer.from('new bytes').toString('base64') };+ const originalPut = storageService.putFile.bind(storageService);+ const put = jest.spyOn(storageService, 'putFile').mockImplementationOnce(async (key, bytes) => {+ await originalPut(key, bytes);+ await repository.update({ id: row.id }, { metadata: { media: changedMedia } });+ });++ await replacing().archive(row);++ put.mockRestore();+ expect(await mediaOf(row.id)).toEqual(changedMedia);+ expect((await repository.findOneByOrFail({ id: row.id })).mediaPath).toBeNull();+ });++ it('does not publish media revoked while the verified snapshot was read', async () => {+ const row = await saveRow({ mimetype: 'image/png', data: PNG.toString('base64') });+ const originalFindOne = repository.findOne.bind(repository);+ const find = jest.spyOn(repository, 'findOne').mockImplementationOnce(async options => {+ const snapshot = await originalFindOne(options);+ await repository.update({ id: row.id }, { type: 'revoked', metadata: null as unknown as undefined });+ return snapshot;+ });++ expect(await replacing().archive(row)).toBeNull();++ find.mockRestore();+ const current = await repository.findOneByOrFail({ id: row.id });+ expect(current.type).toBe('revoked');+ expect(current.metadata).toBeNull();+ expect(current.mediaPath).toBeNull();+ });++ it('keeps the inline copy when the file could not be written', async () => {+ const base64 = PNG.toString('base64');+ const row = await saveRow({ mimetype: 'image/png', data: base64 });+ const put = jest.spyOn(storageService, 'putFile').mockRejectedValueOnce(new Error('disk on fire'));++ await replacing().archive(row);++ expect((await mediaOf(row.id)).data).toBe(base64);+ put.mockRestore();+ });++ it('keeps the inline copy of media above the archive cap, which is not archived', async () => {+ const base64 = PNG.toString('base64');+ const row = await saveRow({ mimetype: 'image/png', data: base64 });++ expect(await replacing({ 'chatMedia.maxBytes': 4 }).archive(row)).toBeNull();++ expect((await mediaOf(row.id)).data).toBe(base64);+ });++ it('leaves the inline copy alone in the default inline mode', async () => {+ const base64 = PNG.toString('base64');+ const row = await saveRow({ mimetype: 'image/png', data: base64 });++ await enabled({ 'chatMedia.inlineMode': 'inline' }).archive(row);++ expect((await mediaOf(row.id)).data).toBe(base64);+ });+ });+describe('getMedia', () => {it('resolves an archived file by session + chat + WhatsApp message id', async () => {const row = await saveRow({ mimetype: 'image/png', data: PNG.toString('base64') });diff --git a/src/modules/chat-media/chat-media-archive.service.ts b/src/modules/chat-media/chat-media-archive.service.tsindex 7882a5d54..191ddd102 100644--- a/src/modules/chat-media/chat-media-archive.service.ts+++ b/src/modules/chat-media/chat-media-archive.service.ts@@ -53,9 +53,12 @@ interface InlineMedia {* Archives chat-message media to the file store so it stays retrievable after delivery, independent* of the inline base64 copy the message row already carries.*- * Opt-in (`CHAT_MEDIA_ARCHIVE_ENABLED`, default off) because it doubles storage for media under the- * cap: the inline copy is deliberately left in place, since the dashboard renders from it and- * stripping it would break the response contract.+ * Opt-in (`CHAT_MEDIA_ARCHIVE_ENABLED`, default off) because, by default, it doubles storage for+ * media under the cap: the inline copy is left in place, since the dashboard renders from it.+ * `MESSAGE_INLINE_MEDIA=archive` changes that: once a file is stored, read back intact and the row+ * points at it, the row's inline copy is replaced with the omitted marker (`omitted: true`,+ * `archived: true`), so the bytes are kept once and served by the media route. Any failure along+ * the way leaves the inline copy, so the mode can lose a saving but never the media.** Two recurring sweeps run regardless of that flag, which gates the writer rather than the store: a* retention purge (when `CHAT_MEDIA_ARCHIVE_TTL_DAYS` is non-zero) that clears files past their TTL@@ -87,6 +90,11 @@ export class ChatMediaArchiveService implements OnModuleInit, OnModuleDestroy {return this.configService.get<boolean>('chatMedia.archiveEnabled', false);}+ /** MESSAGE_INLINE_MEDIA=archive: an archived file replaces the row's inline copy. */+ get replacesInline(): boolean {+ return this.configService.get<'inline' | 'archive'>('chatMedia.inlineMode', 'inline') === 'archive';+ }+onModuleInit(): void {const runPurge = (): void => {if (this.purging) return;@@ -153,8 +161,9 @@ export class ChatMediaArchiveService implements OnModuleInit, OnModuleDestroy {// id into S3 keys. The row is read on the way out anyway, so nothing is gained by a derivable// key. Mirrors the status store.const key = `${CHAT_MEDIA_PREFIX}${row.sessionId}/${randomUUID()}.${extFromMimetype(media.mimetype)}`;+ const bytes = Buffer.from(media.data, 'base64');try {- await this.storageService.putFile(key, Buffer.from(media.data, 'base64'));+ await this.storageService.putFile(key, bytes);} catch (error) {this.logger.error(`Failed to archive chat media for session ${row.sessionId}, message ${row.id}`,@@ -164,14 +173,48 @@ export class ChatMediaArchiveService implements OnModuleInit, OnModuleDestroy {}try {- // Conditional on the row not being revoked: a revoke that landed while the file was written- // cleared the row, and pointing it at the file would bring the deleted media back. And on no- // pointer yet: the other writer may have passed the snapshot guard above while this file was- // being written, and the first pointer wins so the losing file is deleted, not stranded.- const result = await this.repository.update(- { id: row.id, type: Not('revoked'), mediaPath: IsNull() },- { mediaPath: key, mediaMimetype: media.mimetype },- );+ let result;+ if (this.replacesInline) {+ const stored = await this.storageService.getFile(key);+ if (!stored.equals(bytes)) throw new Error('Archived media did not read back intact');+ const current = await this.repository.findOne({+ where: { id: row.id, mediaPath: IsNull(), type: Not('revoked') },+ select: { id: true, metadata: true },+ });+ const metadata = current?.metadata;+ const currentMedia = (metadata as { media?: InlineMedia } | null | undefined)?.media;+ if (!currentMedia?.data || currentMedia.data !== media.data) {+ await this.storageService.deleteFile(key).catch(() => undefined);+ return null;+ }+ const { data: _data, ...rest } = currentMedia;+ void _data;+ // Publish the verified pointer and remove only the exact metadata snapshot we read.+ // A concurrent reaction, edit or revoke wins instead of being overwritten.+ result = await this.repository+ .createQueryBuilder()+ .update()+ .set({+ mediaPath: key,+ mediaMimetype: media.mimetype,+ metadata: {+ ...metadata,+ media: { ...rest, omitted: true, sizeBytes: bytes.length, archived: true },+ },+ })+ .where({ id: row.id, type: Not('revoked'), mediaPath: IsNull() })+ .andWhere('"metadata" = :snapshot', { snapshot: JSON.stringify(metadata) })+ .execute();+ } else {+ // Conditional on the row not being revoked: a revoke that landed while the file was written+ // cleared the row, and pointing it at the file would bring the deleted media back. And on no+ // pointer yet: the other writer may have passed the snapshot guard above while this file was+ // being written, and the first pointer wins so the losing file is deleted, not stranded.+ result = await this.repository.update(+ { id: row.id, type: Not('revoked'), mediaPath: IsNull() },+ { mediaPath: key, mediaMimetype: media.mimetype },+ );+ }if (result.affected === 0) {await this.storageService.deleteFile(key).catch(() => undefined); // else the orphan sweep reaps itreturn null;@@ -179,9 +222,12 @@ export class ChatMediaArchiveService implements OnModuleInit, OnModuleDestroy {} catch (error) {// The file exists but no row references it β an orphan the sweep reaps after its grace// window. The row itself stays consistent (mediaPath still null), so nothing else to undo.- this.logger.warn(`Chat media ${key} written but the row update failed; leaving it for the orphan sweep`, {- error: String(error),- });+ this.logger.warn(+ `Chat media ${key} written but not published; keeping inline media and leaving the file for the orphan sweep`,+ {+ error: String(error),+ },+ );return null;}return key;