Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
refactor(media): resolve media bodies in one place
Yudhi Armyndharis754a67ff1f73
diff --git a/docs/09-testing-strategy.md b/docs/09-testing-strategy.mdindex 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.jsonindex 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": 85diff --git a/src/modules/group/group.service.ts b/src/modules/group/group.service.tsindex 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.tsindex 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.tsindex 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): vthrow 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.tsindex 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.tsindex 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.tsindex 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),);