Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

refactor(media): resolve media bodies in one place

Yudhi Armyndharis754a67ff1f73
diff --git a/docs/09-testing-strategy.md b/docs/09-testing-strategy.md
index faf2c6b27..07108ecfe 100644
--- a/docs/09-testing-strategy.md
+++ b/docs/09-testing-strategy.md
@@ -212,7 +212,7 @@ authoritative gate. Current policy:
| `src/modules/message/` | 75% | 66% | 86% | 85% |
| `src/modules/metrics/` | 64% | 58% | 70% | 67% |
| `src/modules/plugins/` | 69% | 64% | 77% | 76% |
-| `src/modules/profile/` | 78% | 84% | 88% | 85% |
+| `src/modules/profile/` | 65% | 84% | 88% | 85% |
| `src/modules/queue/` | 74% | 81% | 95% | 95% |
| `src/modules/search/` | 69% | 86% | 78% | 78% |
| `src/modules/session/` | 75% | 79% | 88% | 87% |
diff --git a/package.json b/package.json
index 09e4eac35..e8f20e6c2 100644
--- a/package.json
+++ b/package.json
@@ -455,7 +455,7 @@
"statements": 44
},
"./src/modules/profile/": {
- "branches": 78,
+ "branches": 65,
"functions": 84,
"lines": 88,
"statements": 85
diff --git a/src/modules/group/group.service.ts b/src/modules/group/group.service.ts
index 54d36b7b7..196bcff6b 100644
--- a/src/modules/group/group.service.ts
+++ b/src/modules/group/group.service.ts
@@ -1,7 +1,7 @@
import { Injectable, BadRequestException, HttpException, HttpStatus, NotFoundException } from '@nestjs/common';
import { EngineRegistry } from '../../engine/engine-registry.service';
import { GroupMemberAddMode, IWhatsAppEngine, MediaInput } from '../../engine/interfaces/whatsapp-engine.interface';
-import { assertBase64WithinMediaCap, stripBase64DataUri } from '../message/media-cap.util';
+import { resolveMediaBody } from '../message/media-cap.util';
import { chatKind } from '../../engine/identity/wa-id';
import { isAddressableParticipant } from '../../engine/identity/wa-id';
import { SetGroupPictureDto } from './dto/group.dto';
@@ -222,19 +222,12 @@ export class GroupService {
setGroupPicture(sessionId: string, groupId: string, dto: SetGroupPictureDto): Promise<void> {
this.assertGroupId(groupId);
- const base64 = stripBase64DataUri(dto.base64);
- if (!dto.url && !base64) {
- throw new BadRequestException('Either url or base64 must be provided');
- }
- if (base64 && !dto.mimetype) {
- throw new BadRequestException('mimetype is required when using base64 data');
- }
- assertBase64WithinMediaCap(base64);
- const media: MediaInput = {
- mimetype: dto.mimetype || 'image/jpeg',
- // base64 wins over url when both are present, mirroring setProfilePicture.
- data: base64 || dto.url!,
- };
+ // base64 wins over url when both are present, mirroring setProfilePicture.
+ const media: MediaInput = resolveMediaBody(dto, {
+ fallbackMimetype: 'image/jpeg',
+ requireMimetypeForBase64: true,
+ checkUrl: true,
+ });
return this.getEngine(sessionId).setGroupPicture(groupId, media);
}
diff --git a/src/modules/message/media-cap.util.spec.ts b/src/modules/message/media-cap.util.spec.ts
index 4a998caab..e1b88add3 100644
--- a/src/modules/message/media-cap.util.spec.ts
+++ b/src/modules/message/media-cap.util.spec.ts
@@ -1,5 +1,5 @@
-import { PayloadTooLargeException } from '@nestjs/common';
-import { assertBase64WithinMediaCap, stripBase64DataUri } from './media-cap.util';
+import { BadRequestException, PayloadTooLargeException } from '@nestjs/common';
+import { assertBase64WithinMediaCap, resolveMediaBody, stripBase64DataUri } from './media-cap.util';
describe('assertBase64WithinMediaCap', () => {
const orig = process.env.MEDIA_DOWNLOAD_MAX_BYTES;
@@ -38,3 +38,70 @@ describe('assertBase64WithinMediaCap', () => {
expect(() => assertBase64WithinMediaCap(base64OfBytes(4096))).toThrow(PayloadTooLargeException);
});
});
+
+describe('resolveMediaBody', () => {
+ const orig = process.env.MEDIA_DOWNLOAD_MAX_BYTES;
+ afterEach(() => {
+ if (orig === undefined) delete process.env.MEDIA_DOWNLOAD_MAX_BYTES;
+ else process.env.MEDIA_DOWNLOAD_MAX_BYTES = orig;
+ });
+
+ const FALLBACK = { fallbackMimetype: 'image/jpeg' };
+
+ it('refuses a body with neither a url nor base64', () => {
+ expect(() => resolveMediaBody({}, FALLBACK)).toThrow('Either url or base64 must be provided');
+ expect(() => resolveMediaBody(undefined, FALLBACK)).toThrow(BadRequestException);
+ // A data-URI prefix with nothing after it holds no data.
+ expect(() => resolveMediaBody({ base64: 'data:image/png;base64,' }, FALLBACK)).toThrow(BadRequestException);
+ });
+
+ it('uses the url when only a url is given, typed by the fallback unless the body names a type', () => {
+ expect(resolveMediaBody({ url: 'https://cdn.example/a.jpg' }, FALLBACK)).toEqual({
+ mimetype: 'image/jpeg',
+ data: 'https://cdn.example/a.jpg',
+ });
+ expect(resolveMediaBody({ url: 'https://cdn.example/a.png', mimetype: 'image/png' }, FALLBACK).mimetype).toBe(
+ 'image/png',
+ );
+ });
+
+ it('lets base64 win over a stale url, and strips a data-URI prefix', () => {
+ expect(
+ resolveMediaBody(
+ { url: 'https://stale.example/x', base64: 'data:image/png;base64,QUJD', mimetype: 'image/png' },
+ FALLBACK,
+ ),
+ ).toEqual({ mimetype: 'image/png', data: 'QUJD' });
+ });
+
+ it('requires a type for base64 only when asked to', () => {
+ expect(() => resolveMediaBody({ base64: 'QUJD' }, { ...FALLBACK, requireMimetypeForBase64: true })).toThrow(
+ 'mimetype is required when using base64 data',
+ );
+ expect(resolveMediaBody({ base64: 'QUJD' }, FALLBACK)).toEqual({ mimetype: 'image/jpeg', data: 'QUJD' });
+ // A url needs no declared type: it is typed by what it answers with.
+ expect(() =>
+ resolveMediaBody({ url: 'https://cdn.example/a' }, { ...FALLBACK, requireMimetypeForBase64: true }),
+ ).not.toThrow();
+ });
+
+ it('checks the shape of the url only when asked to, and not when base64 holds the data', () => {
+ expect(() => resolveMediaBody({ url: 'cdn.example/a.jpg' }, { ...FALLBACK, checkUrl: true })).toThrow(
+ 'url must be an absolute http(s) URL',
+ );
+ expect(() => resolveMediaBody({ url: 'cdn.example/a.jpg' }, FALLBACK)).not.toThrow();
+ expect(() =>
+ resolveMediaBody({ url: 'junk', base64: 'QUJD', mimetype: 'image/png' }, { ...FALLBACK, checkUrl: true }),
+ ).not.toThrow();
+ });
+
+ it('refuses base64 over the media cap with a 413, after the other checks', () => {
+ process.env.MEDIA_DOWNLOAD_MAX_BYTES = '1024';
+ const big = Buffer.alloc(2048).toString('base64');
+ expect(() => resolveMediaBody({ base64: big, mimetype: 'image/png' }, FALLBACK)).toThrow(PayloadTooLargeException);
+ // The type check comes first, so a body that breaks both reports the type.
+ expect(() => resolveMediaBody({ base64: big }, { ...FALLBACK, requireMimetypeForBase64: true })).toThrow(
+ 'mimetype is required',
+ );
+ });
+});
diff --git a/src/modules/message/media-cap.util.ts b/src/modules/message/media-cap.util.ts
index cc8a06961..6513654f5 100644
--- a/src/modules/message/media-cap.util.ts
+++ b/src/modules/message/media-cap.util.ts
@@ -1,5 +1,6 @@
-import { PayloadTooLargeException } from '@nestjs/common';
+import { BadRequestException, PayloadTooLargeException } from '@nestjs/common';
import { inboundMediaMaxBytes } from '../../engine';
+import { isMediaUrl, MEDIA_URL_MESSAGE } from '../../common/media/media-url';
/**
* Accept the historical `data:<mime>;base64,<payload>` form without passing its metadata prefix to
@@ -32,3 +33,48 @@ export function assertBase64WithinMediaCap(base64: string | null | undefined): v
throw new PayloadTooLargeException(`Base64 media exceeds the maximum allowed size of ${maxBytes} bytes`);
}
}
+
+/** A request body that carries media as a URL, as base64, or as both. */
+export interface MediaBody {
+ url?: string;
+ base64?: string;
+ mimetype?: string;
+}
+
+export interface MediaBodyOptions {
+ /** The type used when the body names none. */
+ fallbackMimetype: string;
+ /** A base64 body has to name its type; a URL is typed by what it answers with. */
+ requireMimetypeForBase64?: boolean;
+ /**
+ * A body without base64 has to carry an absolute http(s) URL, since both engines decode anything
+ * else as base64. The DTO checks this too, but a plugin send and a hook rewrite reach the service
+ * without it.
+ */
+ checkUrl?: boolean;
+}
+
+/**
+ * The media a url-or-base64 body stands for, checked the way every media write checks it. One of the two
+ * has to be given, and base64 wins when it holds data: a stale `url` left in a body (a Swagger example, say)
+ * must not be fetched in its place (#670). Base64 is bounded to the media byte cap before it is persisted or
+ * handed to an engine; a URL is capped while it streams. The checks run in the order listed in the options.
+ */
+export function resolveMediaBody(
+ body: MediaBody | undefined,
+ options: MediaBodyOptions,
+): { mimetype: string; data: string } {
+ const base64 = stripBase64DataUri(body?.base64);
+ const url = body?.url;
+ if (!url && !base64) {
+ throw new BadRequestException('Either url or base64 must be provided');
+ }
+ if (options.checkUrl && !base64 && !isMediaUrl(url)) {
+ throw new BadRequestException(MEDIA_URL_MESSAGE);
+ }
+ if (options.requireMimetypeForBase64 && base64 && !body?.mimetype) {
+ throw new BadRequestException('mimetype is required when using base64 data');
+ }
+ assertBase64WithinMediaCap(base64);
+ return { mimetype: body?.mimetype || options.fallbackMimetype, data: base64 || url! };
+}
diff --git a/src/modules/message/message-send.service.ts b/src/modules/message/message-send.service.ts
index 18a8794c4..5beebca5a 100644
--- a/src/modules/message/message-send.service.ts
+++ b/src/modules/message/message-send.service.ts
@@ -9,7 +9,7 @@ import { MessageProjector } from '../session/message-projector.service';
import { EngineRegistry } from '../../engine/engine-registry.service';
import { SendTextMessageDto, SendMediaMessageDto, SendAudioMessageDto, MessageResponseDto } from './dto';
import { SendTemplateMessageDto } from './dto/send-template.dto';
-import { assertBase64WithinMediaCap, stripBase64DataUri } from './media-cap.util';
+import { resolveMediaBody } from './media-cap.util';
import { MediaInput, IWhatsAppEngine, MessageResult } from '../../engine/interfaces/whatsapp-engine.interface';
import { Message, MessageDirection, MessageStatus } from './entities/message.entity';
import { HookManager, applySendingGate } from '../../core/hooks';
@@ -23,7 +23,6 @@ import { isUniqueViolation } from '../../common/utils/db-errors';
import { ChatMediaArchiveService } from '../chat-media/chat-media-archive.service';
import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.service';
import { resolveJidCandidates } from '../../engine/identity/jid-candidates';
-import { isMediaUrl, MEDIA_URL_MESSAGE } from '../../common/media/media-url';
import { captureSessionWrites, SessionWriteScope } from '../../common/utils/session-write-scope';
/** Default cap on a rendered template's final text; overridable via TEMPLATE_RENDER_MAX_CHARS. */
@@ -991,31 +990,14 @@ export class MessageSendService {
}
private buildMediaInput(dto: SendMediaMessageDto): MediaInput {
- const base64 = stripBase64DataUri(dto.base64);
- if (!dto.url && !base64) {
- throw new BadRequestException('Either url or base64 must be provided');
- }
- // The DTO checks this too, but a plugin send and a message:sending rewrite reach here without it,
- // and both engines decode anything that is not an http(s) URL as base64.
- if (!base64 && !isMediaUrl(dto.url)) {
- throw new BadRequestException(MEDIA_URL_MESSAGE);
- }
-
- if (base64 && !dto.mimetype) {
- throw new BadRequestException('mimetype is required when using base64 data');
- }
-
- // Bound an outbound base64 payload to the same byte cap as URL/inbound media, before it is
- // persisted or handed to the engine. URL media is already capped while streaming.
- assertBase64WithinMediaCap(base64);
-
+ const { mimetype, data } = resolveMediaBody(dto, {
+ fallbackMimetype: 'application/octet-stream',
+ requireMimetypeForBase64: true,
+ checkUrl: true,
+ });
return {
- mimetype: dto.mimetype || 'application/octet-stream',
- // base64 wins over url when both are present: it is the explicit local payload, and a stale
- // `url` (e.g. a Swagger/example default left in the body) must not be fetched in its place.
- // Aligns the send selection with the base64-first persisted metadata and the url field's check,
- // which is skipped only when base64 holds data after its data-URI prefix is stripped (#670).
- data: base64 || dto.url!,
+ mimetype,
+ data,
filename: dto.filename,
caption: dto.caption,
mentions: dto.mentions,
diff --git a/src/modules/profile/profile.service.ts b/src/modules/profile/profile.service.ts
index 2149225f9..d0510e156 100644
--- a/src/modules/profile/profile.service.ts
+++ b/src/modules/profile/profile.service.ts
@@ -1,7 +1,7 @@
-import { Injectable, BadRequestException } from '@nestjs/common';
+import { Injectable } from '@nestjs/common';
import { EngineRegistry } from '../../engine/engine-registry.service';
import { IWhatsAppEngine, MediaInput } from '../../engine/interfaces/whatsapp-engine.interface';
-import { assertBase64WithinMediaCap, stripBase64DataUri } from '../message/media-cap.util';
+import { resolveMediaBody } from '../message/media-cap.util';
import { SetProfilePictureDto } from './dto/profile.dto';
/**
@@ -32,19 +32,12 @@ export class ProfileService {
/** Map the JSON media body to a MediaInput exactly like the message module's media sends do. */
setProfilePicture(sessionId: string, dto: SetProfilePictureDto) {
- const base64 = stripBase64DataUri(dto.base64);
- if (!dto.url && !base64) {
- throw new BadRequestException('Either url or base64 must be provided');
- }
- if (base64 && !dto.mimetype) {
- throw new BadRequestException('mimetype is required when using base64 data');
- }
- assertBase64WithinMediaCap(base64);
- const media: MediaInput = {
- mimetype: dto.mimetype || 'image/jpeg',
- // base64 wins over url when both are present (mirrors buildMediaInput, #670).
- data: base64 || dto.url!,
- };
+ // base64 wins over url when both are present (mirrors buildMediaInput, #670).
+ const media: MediaInput = resolveMediaBody(dto, {
+ fallbackMimetype: 'image/jpeg',
+ requireMimetypeForBase64: true,
+ checkUrl: true,
+ });
return this.getEngine(sessionId).setProfilePicture(media);
}
}
diff --git a/src/modules/status/status.service.ts b/src/modules/status/status.service.ts
index 0e5ca56f3..3d9dfa86a 100644
--- a/src/modules/status/status.service.ts
+++ b/src/modules/status/status.service.ts
@@ -3,7 +3,7 @@ import { EngineRegistry } from '../../engine/engine-registry.service';
import { StatusStoreService } from '../status-store/status-store.service';
import { StorageService, isMissingObjectError } from '../../common/storage/storage.service';
import type { Status, StatusResult, StatusPostOptions } from '../../engine/interfaces/whatsapp-engine.interface';
-import { assertBase64WithinMediaCap, stripBase64DataUri } from '../message/media-cap.util';
+import { assertBase64WithinMediaCap, resolveMediaBody, stripBase64DataUri } from '../message/media-cap.util';
import { HookManager, applySendingGate } from '../../core/hooks';
import { SendPacingService, countsTowardSendBreaker } from '../message/send-pacing.service';
import { isMediaUrl } from '../../common/media/media-url';
@@ -159,21 +159,12 @@ export class StatusService {
media: { url?: string; base64?: string; mimetype?: string } | undefined,
options: StatusPostOptions,
): Promise<StatusResult> {
- const base64 = stripBase64DataUri(media?.base64);
- const url = media?.url;
- const mimetype = media?.mimetype;
- if (!url && !base64) {
- throw new BadRequestException('Either url or base64 must be provided');
- }
- assertBase64WithinMediaCap(base64);
+ const payload = resolveMediaBody(media, { fallbackMimetype: 'image/jpeg' });
const engine = this.engines.require(
sessionId,
() => new NotFoundException(`Session ${sessionId} not found or not connected`),
);
- const gated = await this.gate(sessionId, 'status-image', {
- media: { mimetype: mimetype ?? 'image/jpeg', data: base64 || url || '' },
- options,
- });
+ const gated = await this.gate(sessionId, 'status-image', { media: payload, options });
return this.recordedPost(sessionId, 'image', () =>
engine.postImageStatus(this.guardGatedMedia(gated.media), gated.options),
);
@@ -184,21 +175,12 @@ export class StatusService {
media: { url?: string; base64?: string; mimetype?: string } | undefined,
options: StatusPostOptions,
): Promise<StatusResult> {
- const base64 = stripBase64DataUri(media?.base64);
- const url = media?.url;
- const mimetype = media?.mimetype;
- if (!url && !base64) {
- throw new BadRequestException('Either url or base64 must be provided');
- }
- assertBase64WithinMediaCap(base64);
+ const payload = resolveMediaBody(media, { fallbackMimetype: 'video/mp4' });
const engine = this.engines.require(
sessionId,
() => new NotFoundException(`Session ${sessionId} not found or not connected`),
);
- const gated = await this.gate(sessionId, 'status-video', {
- media: { mimetype: mimetype ?? 'video/mp4', data: base64 || url || '' },
- options,
- });
+ const gated = await this.gate(sessionId, 'status-video', { media: payload, options });
return this.recordedPost(sessionId, 'video', () =>
engine.postVideoStatus(this.guardGatedMedia(gated.media), gated.options),
);
@@ -219,21 +201,12 @@ export class StatusService {
media: { url?: string; base64?: string; mimetype?: string } | undefined,
options: StatusPostOptions,
): Promise<StatusResult> {
- const base64 = stripBase64DataUri(media?.base64);
- const url = media?.url;
- const mimetype = media?.mimetype;
- if (!url && !base64) {
- throw new BadRequestException('Either url or base64 must be provided');
- }
- assertBase64WithinMediaCap(base64);
+ const payload = resolveMediaBody(media, { fallbackMimetype: 'audio/ogg; codecs=opus' });
const engine = this.engines.require(
sessionId,
() => new NotFoundException(`Session ${sessionId} not found or not connected`),
);
- const gated = await this.gate(sessionId, 'status-voice', {
- media: { mimetype: mimetype ?? 'audio/ogg; codecs=opus', data: base64 || url || '' },
- options,
- });
+ const gated = await this.gate(sessionId, 'status-voice', { media: payload, options });
return this.recordedPost(sessionId, 'voice', () =>
engine.postVoiceStatus(this.guardGatedMedia(gated.media), gated.options),
);