Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
import { DataSource, Repository } from 'typeorm';
import { ConfigService } from '@nestjs/config';
import { StorageService } from '../../common/storage/storage.service';
import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.service';
import { LidMapping } from '../../engine/identity/lid-mapping.entity';
import { userPart } from '../../engine/identity/wa-id';
import { StatusUpdate } from './entities/status-update.entity';
import { StatusStoreService } from './status-store.service';
/** A ConfigService stub that returns each call's default unless overridden by `overrides`. */
function fakeConfigService(overrides: Record<string, unknown> = {}): ConfigService {
return {
get: (key: string, defaultValue?: unknown) => (key in overrides ? overrides[key] : defaultValue),
} as unknown as ConfigService;
}
function makeStorageService(localPath: string): StorageService {
return new StorageService(fakeConfigService({ 'storage.type': 'local', 'storage.localPath': localPath }));
}
describe('StatusStoreService (ingest / list / getMedia)', () => {
let baseDir: string;
let ds: DataSource;
let repository: Repository<StatusUpdate>;
let storageService: StorageService;
let service: StatusStoreService;
beforeAll(async () => {
baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'owa-status-store-'));
ds = new DataSource({ type: 'better-sqlite3', database: ':memory:', entities: [StatusUpdate], synchronize: true });
await ds.initialize();
repository = ds.getRepository(StatusUpdate);
storageService = makeStorageService(path.join(baseDir, 'media'));
service = new StatusStoreService(repository, storageService, fakeConfigService());
});
afterAll(async () => {
if (ds.isInitialized) await ds.destroy();
fs.rmSync(baseDir, { recursive: true, force: true });
});
// SQLite serves every repository from one connection, so a transaction a save opens is shared with the
// writes made while it is open, and the rollback of a duplicate's unique violation would undo them too,
// after ingest had reported them created and the status.received webhook had gone out.
it('keeps a row written while a duplicate that lost the unique-key race is refused', async () => {
const status = (waStatusId: string) => ({
waStatusId,
contactJid: '[email protected]',
type: 'text' as const,
caption: waStatusId,
postedAt: Date.now(),
});
await service.ingest('sess-race', status('dup'));
// The racing ingest read before the winner wrote, so it goes on to the insert that must be refused.
jest.spyOn(repository, 'findOne').mockResolvedValueOnce(null);
let concurrent: Promise<unknown> | undefined;
ds.subscribers.push({
listenTo: () => StatusUpdate,
beforeInsert: event => {
if ((event.entity as StatusUpdate).waStatusId === 'dup' && !concurrent) {
const other = status('other');
concurrent = repository.insert({
...other,
sessionId: 'sess-race',
expiresAt: other.postedAt + 24 * 60 * 60 * 1000,
mediaOmitted: false,
});
}
},
});
const { created } = await service.ingest('sess-race', status('dup'));
await concurrent;
expect(created).toBe(false);
const stored = (await repository.find({ where: { sessionId: 'sess-race' } })).map(row => row.waStatusId).sort();
expect(stored).toEqual(['dup', 'other']);
});
// Left open, the scope an ingest captures for itself keeps its session's write state from ever being released.
it('closes the scope it captures for itself, for a new status and for one already stored', async () => {
const closes: jest.SpyInstance[] = [];
const capture = service.captureWrites.bind(service);
const spy = jest.spyOn(service, 'captureWrites').mockImplementation(sessionId => {
const scope = capture(sessionId);
closes.push(jest.spyOn(scope, 'close'));
return scope;
});
const status = {
waStatusId: 'scope-close',
contactJid: '[email protected]',
type: 'text' as const,
caption: 'hi',
postedAt: Date.now(),
};
try {
expect((await service.ingest('sess-scope', status)).created).toBe(true);
expect((await service.ingest('sess-scope', status)).created).toBe(false);
} finally {
spy.mockRestore();
}
expect(closes).toHaveLength(2);
for (const close of closes) expect(close).toHaveBeenCalled();
});
it('does not publish media or recreate a row removed while storage is pending', async () => {
let release!: () => void;
let entered!: () => void;
const ready = new Promise<void>(resolve => {
entered = resolve;
});
const gate = new Promise<void>(resolve => {
release = resolve;
});
const put = storageService.putFile.bind(storageService);
let key = '';
const spy = jest.spyOn(storageService, 'putFile').mockImplementationOnce(async (file, bytes) => {
key = file;
await put(file, bytes);
entered();
await gate;
});
const pending = service.ingest('removed-status', {
waStatusId: 'pending-media',
contactJid: '[email protected]',
type: 'image',
postedAt: Date.now(),
media: { mimetype: 'image/png', data: 'dGlueQ==', sizeBytes: 4 },
});
try {
await ready;
await repository.delete({ sessionId: 'removed-status' });
} finally {
release();
}
const result = await pending;
spy.mockRestore();
expect(result.created).toBe(false);
expect(result.row.mediaOmitted).toBe(true);
expect(result.row.mediaPath).toBeUndefined();
expect(await repository.countBy({ sessionId: 'removed-status' })).toBe(0);
expect(await service.getMedia('removed-status', 'pending-media')).toBeNull();
await expect(storageService.getFile(key)).rejects.toMatchObject({ code: 'ENOENT' });
});
it('ingest writes a text row with expiresAt = postedAt + 24h, flagged as created', async () => {
const postedAt = Date.now();
const { row, created } = await service.ingest('sess', {
waStatusId: 'w1',
contactJid: '[email protected]',
type: 'text',
caption: 'hi',
postedAt,
});
expect(created).toBe(true);
expect(row.expiresAt).toBe(postedAt + 24 * 60 * 60 * 1000);
expect(row.mediaOmitted).toBe(false);
expect(row.mediaPath).toBeFalsy();
});
it('ingest persists text-status styling and serves it back in the API shape', async () => {
const { row } = await service.ingest('sess', {
waStatusId: 'styled',
contactJid: '[email protected]',
type: 'text',
caption: 'hi',
backgroundColor: '#25d366',
font: 2,
postedAt: Date.now(),
});
expect(row.backgroundColor).toBe('#25d366');
expect(row.font).toBe(2);
const styled = (await service.list('sess')).find(s => s.id === 'styled')!;
expect(styled.backgroundColor).toBe('#25d366');
expect(styled.font).toBe(2);
});
it('serves a status with no name, push name, caption or styling without those keys', async () => {
const postedAt = Date.now();
await service.ingest('sess', { waStatusId: 'bare', contactJid: '[email protected]', type: 'text', postedAt });
// The columns read back as null, but StatusDto and the openapi schema declare these fields optional,
// not nullable: a client typed from the contract must see them absent.
const listed = (await service.list('sess')).find(s => s.id === 'bare')!;
const [byContact] = await service.listByContact('sess', '[email protected]');
const wire = {
id: 'bare',
contact: { id: '[email protected]' },
type: 'text',
timestamp: new Date(postedAt).toISOString(),
expiresAt: new Date(postedAt + 24 * 60 * 60 * 1000).toISOString(),
};
expect(JSON.parse(JSON.stringify(listed))).toEqual(wire);
expect(JSON.parse(JSON.stringify(byContact))).toEqual(wire);
});
it('ingest persists media to a file under the cap and records mediaPath', async () => {
const { row } = await service.ingest('sess', {
waStatusId: 'w2',
contactJid: '[email protected]',
type: 'image',
media: { mimetype: 'image/jpeg', data: Buffer.from('x').toString('base64') },
postedAt: Date.now(),
});
expect(row.mediaPath).toBeTruthy();
expect(row.mediaMimetype).toBe('image/jpeg');
expect(row.mediaOmitted).toBe(false);
expect(row.mediaPath!.endsWith('.jpg')).toBe(true);
// The file was actually written under the storage root.
expect(fs.readFileSync(path.join(baseDir, 'media', row.mediaPath!), 'utf8')).toBe('x');
});
it('ingest marks media omitted when the engine already omitted it', async () => {
const { row } = await service.ingest('sess', {
waStatusId: 'w3',
contactJid: '[email protected]',
type: 'image',
media: { mimetype: 'image/jpeg', omitted: true, sizeBytes: 99 },
postedAt: Date.now(),
});
expect(row.mediaOmitted).toBe(true);
expect(row.omitReason).toBe('engine_omitted');
expect(row.mediaPath).toBeFalsy();
});
it('ingest marks media omitted when sizeBytes exceeds STATUS_MEDIA_MAX_BYTES', async () => {
const { row } = await service.ingest('sess', {
waStatusId: 'w4',
contactJid: '[email protected]',
type: 'image',
media: { mimetype: 'image/jpeg', data: '...', sizeBytes: 999_999_999 },
postedAt: Date.now(),
});
expect(row.mediaOmitted).toBe(true);
expect(row.omitReason).toBe('over_cap');
expect(row.mediaPath).toBeFalsy();
});
it('ingest records over_cap (not engine_omitted) when an engine-skipped blob exceeds the store cap', async () => {
// The seed's pre-gate skips downloads above the store cap with the engine-omitted flag set —
// the durable reason must still read over_cap on both arrival paths.
const { row } = await service.ingest('sess', {
waStatusId: 'w8',
contactJid: '[email protected]',
type: 'image',
media: { mimetype: 'image/jpeg', omitted: true, sizeBytes: 11 * 1024 * 1024 },
postedAt: Date.now(),
});
expect(row.mediaOmitted).toBe(true);
expect(row.omitReason).toBe('over_cap');
});
it('ingest is idempotent on (sessionId, waStatusId), flagged as not created on the duplicate', async () => {
await service.ingest('sess', { waStatusId: 'dup', contactJid: '[email protected]', type: 'text', postedAt: 1 });
const second = await service.ingest('sess', {
waStatusId: 'dup',
contactJid: '[email protected]',
type: 'text',
postedAt: 1,
});
const rows = await repository.find({ where: { sessionId: 'sess', waStatusId: 'dup' } });
expect(rows).toHaveLength(1);
expect(second.row.id).toBe(rows[0].id);
expect(second.created).toBe(false);
});
it('list maps rows to the Status shape newest-first, media path -> mediaUrl endpoint', async () => {
const out = await service.list('sess');
expect(out[0].contact.id).toBe('[email protected]');
expect(out[0].timestamp).toBeInstanceOf(Date);
expect(out[0].expiresAt).toBeInstanceOf(Date);
// Sorted newest (highest postedAt) first.
const postedOrder = out.map(s => s.timestamp.getTime());
expect(postedOrder).toEqual([...postedOrder].sort((a, b) => b - a));
const withMedia = out.find(s => s.id === 'w2')!;
expect(withMedia.mediaUrl).toBe('/api/sessions/sess/status/w2/media');
const omitted = out.find(s => s.id === 'w3')!;
expect(omitted.mediaUrl).toBeUndefined();
const textOnly = out.find(s => s.id === 'w1')!;
expect(textOnly.mediaUrl).toBeUndefined();
});
it('list and listByContact exclude already-expired rows (the purge sweep only runs every 15 min)', async () => {
await service.ingest('sess', {
waStatusId: 'stale',
contactJid: '[email protected]',
type: 'text',
postedAt: Date.now() - 25 * 60 * 60 * 1000, // 25h old — past the 24h TTL
});
expect((await service.list('sess')).map(s => s.id)).not.toContain('stale');
expect((await service.listByContact('sess', '[email protected]')).map(s => s.id)).not.toContain('stale');
});
it('getMedia treats an expired row as absent (404, matching "not found or expired")', async () => {
await service.ingest('sess', {
waStatusId: 'stale-media',
contactJid: '[email protected]',
type: 'image',
media: { mimetype: 'image/jpeg', data: Buffer.from('old').toString('base64') },
postedAt: Date.now() - 25 * 60 * 60 * 1000,
});
expect(await service.getMedia('sess', 'stale-media')).toBeNull();
});
it('listByContact filters to only that contact', async () => {
await service.ingest('sess', { waStatusId: 'w5', contactJid: '[email protected]', type: 'text', postedAt: Date.now() });
const out = await service.listByContact('sess', '[email protected]');
expect(out).toHaveLength(1);
expect(out[0].contact.id).toBe('[email protected]');
});
it('getMedia returns the path/mimetype for a status with kept media', async () => {
const media = await service.getMedia('sess', 'w2');
expect(media?.mimetype).toBe('image/jpeg');
expect(media?.path).toContain('statuses/sess/');
});
// A status whose media arrived without a type still has its bytes stored and its mediaUrl
// advertised, so the URL has to resolve; the media endpoint serves an unknown type as inert bytes.
it('getMedia serves stored media that arrived without a mimetype as octet-stream', async () => {
await service.ingest('sess', {
waStatusId: 'untyped',
contactJid: '[email protected]',
type: 'image',
media: { mimetype: '', data: Buffer.from('raw').toString('base64') },
postedAt: Date.now(),
});
const media = await service.getMedia('sess', 'untyped');
expect(media?.mimetype).toBe('application/octet-stream');
expect(media?.path).toContain('statuses/sess/');
});
it('getMedia returns null for an omitted-media status', async () => {
expect(await service.getMedia('sess', 'w3')).toBeNull();
});
it('getMedia returns null for a text-only status', async () => {
expect(await service.getMedia('sess', 'w1')).toBeNull();
});
it('getMedia returns null for an unknown status id', async () => {
expect(await service.getMedia('sess', 'nope')).toBeNull();
});
it('ingest marks media write_failed when the storage backend throws', async () => {
const failingStorage = {
putFile: jest.fn().mockRejectedValue(new Error('disk full')),
} as unknown as StorageService;
const failingService = new StatusStoreService(repository, failingStorage, fakeConfigService());
const { row } = await failingService.ingest('sess', {
waStatusId: 'w6',
contactJid: '[email protected]',
type: 'image',
media: { mimetype: 'image/jpeg', data: Buffer.from('y').toString('base64') },
postedAt: 7000,
});
expect(row.mediaOmitted).toBe(true);
expect(row.omitReason).toBe('write_failed');
expect(row.mediaPath).toBeFalsy();
});
it('names the reason when the file lands but the row update fails (webhook must not see a bare omission)', async () => {
// The in-memory row returned here is exactly what dispatchStatusReceived sends. Every other
// omission path sets omitReason, so leaving it unset made a real media loss indistinguishable
// from an unexplained omission — and nothing retries it.
const updateSpy = jest.spyOn(repository, 'update').mockRejectedValueOnce(new Error('db blip'));
try {
const { row } = await service.ingest('sess', {
waStatusId: 'w-row-fail',
contactJid: '[email protected]',
type: 'image',
media: { mimetype: 'image/jpeg', data: Buffer.from('q').toString('base64') },
postedAt: 9100,
});
expect(row.mediaOmitted).toBe(true);
expect(row.omitReason).toBe('write_failed');
expect(row.mediaPath).toBeFalsy();
} finally {
updateSpy.mockRestore();
}
});
it('respects a configured status.mediaMaxBytes cap', async () => {
const strictService = new StatusStoreService(
repository,
storageService,
fakeConfigService({ 'status.mediaMaxBytes': 0 }),
);
const { row } = await strictService.ingest('sess', {
waStatusId: 'w7',
contactJid: '[email protected]',
type: 'image',
media: { mimetype: 'image/png', data: Buffer.from('z').toString('base64') },
postedAt: 8000,
});
expect(row.mediaOmitted).toBe(true);
expect(row.omitReason).toBe('over_cap');
});
});
describe('StatusStoreService ingest race (unique-constraint loser)', () => {
let baseDir: string;
let storageService: StorageService;
beforeEach(() => {
baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'owa-status-race-'));
storageService = makeStorageService(path.join(baseDir, 'media'));
});
afterEach(() => {
fs.rmSync(baseDir, { recursive: true, force: true });
});
const mediaDir = (): string[] => {
const dir = path.join(baseDir, 'media', 'statuses', 'sess');
return fs.existsSync(dir) ? fs.readdirSync(dir) : [];
};
it('never writes a media file when a concurrent ingest wins the unique constraint (row-first)', async () => {
// The winner committed its own media file; with row-first ordering the loser has not written
// anything at the point its save fails, so there is nothing to reap and no second file.
fs.mkdirSync(path.join(baseDir, 'media', 'statuses', 'sess'), { recursive: true });
fs.writeFileSync(path.join(baseDir, 'media', 'statuses', 'sess', 'winner.jpg'), 'winner');
const winner = new StatusUpdate();
winner.mediaPath = 'statuses/sess/winner.jpg';
// First findOne (top of ingest) sees nothing; the post-save-failure re-read returns the winner.
const repo = {
findOne: jest.fn().mockResolvedValueOnce(null).mockResolvedValue(winner),
save: jest.fn().mockRejectedValue(new Error('UNIQUE constraint failed')),
} as unknown as Repository<StatusUpdate>;
const service = new StatusStoreService(repo, storageService, fakeConfigService());
const { row, created } = await service.ingest('sess', {
waStatusId: 'raced',
contactJid: '[email protected]',
type: 'image',
media: { mimetype: 'image/jpeg', data: Buffer.from('loser').toString('base64') },
postedAt: 1000,
});
expect(row).toBe(winner);
expect(created).toBe(false);
expect(mediaDir()).toEqual(['winner.jpg']);
});
it('writes no file when the row save fails with no winner row, then rethrows', async () => {
const repo = {
findOne: jest.fn().mockResolvedValue(null),
save: jest.fn().mockRejectedValue(new Error('database is locked')),
} as unknown as Repository<StatusUpdate>;
const service = new StatusStoreService(repo, storageService, fakeConfigService());
await expect(
service.ingest('sess', {
waStatusId: 'raced',
contactJid: '[email protected]',
type: 'image',
media: { mimetype: 'image/jpeg', data: Buffer.from('loser').toString('base64') },
postedAt: 1000,
}),
).rejects.toThrow('database is locked');
// Row-first: the save precedes any file write, so a failed save can never leak an orphan.
expect(mediaDir()).toHaveLength(0);
});
it('rethrows a non-unique save error even when the commit landed, leaving no orphan file behind', async () => {
// The pathological "driver errored on a commit that landed" case: the re-read finds a row, but
// the failure is genuine (not a unique violation) and must surface. The landed row carries no
// media reference (the file write comes after the save), so the state stays consistent.
const landed = new StatusUpdate();
const repo = {
findOne: jest.fn().mockResolvedValueOnce(null).mockResolvedValue(landed),
save: jest.fn().mockRejectedValue(new Error('driver reported failure after commit')),
} as unknown as Repository<StatusUpdate>;
const service = new StatusStoreService(repo, storageService, fakeConfigService());
await expect(
service.ingest('sess', {
waStatusId: 'raced',
contactJid: '[email protected]',
type: 'image',
media: { mimetype: 'image/jpeg', data: Buffer.from('self').toString('base64') },
postedAt: 1000,
}),
).rejects.toThrow('driver reported failure after commit');
expect(mediaDir()).toHaveLength(0);
});
it('rethrows a non-unique save error even when a coincidental winner row exists', async () => {
fs.mkdirSync(path.join(baseDir, 'media', 'statuses', 'sess'), { recursive: true });
fs.writeFileSync(path.join(baseDir, 'media', 'statuses', 'sess', 'winner.jpg'), 'winner');
const winner = new StatusUpdate();
winner.mediaPath = 'statuses/sess/winner.jpg';
const repo = {
findOne: jest.fn().mockResolvedValueOnce(null).mockResolvedValue(winner),
save: jest.fn().mockRejectedValue(new Error('database is locked')),
} as unknown as Repository<StatusUpdate>;
const service = new StatusStoreService(repo, storageService, fakeConfigService());
// A genuine persistence failure must not be swallowed into an idempotent return just because
// a matching row happens to exist — and this call never wrote a file to begin with.
await expect(
service.ingest('sess', {
waStatusId: 'raced',
contactJid: '[email protected]',
type: 'image',
media: { mimetype: 'image/jpeg', data: Buffer.from('loser').toString('base64') },
postedAt: 1000,
}),
).rejects.toThrow('database is locked');
expect(mediaDir()).toEqual(['winner.jpg']);
});
});
describe('StatusStoreService contact identity (read-time lid resolution)', () => {
let baseDir: string;
let ds: DataSource;
let repository: Repository<StatusUpdate>;
let storageService: StorageService;
beforeEach(async () => {
baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'owa-status-lid-'));
ds = new DataSource({ type: 'better-sqlite3', database: ':memory:', entities: [StatusUpdate], synchronize: true });
await ds.initialize();
repository = ds.getRepository(StatusUpdate);
storageService = makeStorageService(path.join(baseDir, 'media'));
});
afterEach(async () => {
if (ds.isInitialized) await ds.destroy();
fs.rmSync(baseDir, { recursive: true, force: true });
});
const lidStore = (mappings: Record<string, string | null>): LidMappingStoreService => {
const getCached = (lid: string): string | null | undefined => (lid in mappings ? mappings[lid] : undefined);
return {
getCached,
findPhoneForLid: (lid: string) => Promise.resolve(getCached(lid) ?? null),
resolveLid: (jid: string) => getCached(userPart(jid)) ?? null,
findLidsForPhone: (phone: string) =>
Promise.resolve(
Object.entries(mappings)
.filter(([, p]) => p === phone)
.map(([l]) => l),
),
} as unknown as LidMappingStoreService;
};
it('resolves a @lid contact to the mapped phone at read time, so both forms group together', async () => {
const svc = new StatusStoreService(repository, storageService, fakeConfigService(), lidStore({ '111': '628111' }));
const now = Date.now();
await svc.ingest('sess', { waStatusId: 'l1', contactJid: '111@lid', type: 'text', postedAt: now });
await svc.ingest('sess', { waStatusId: 'l2', contactJid: '[email protected]', type: 'text', postedAt: now + 1 });
const contacts = new Set((await svc.list('sess')).map(s => s.contact.id));
expect(contacts).toEqual(new Set(['[email protected]']));
});
it('leaves unknown and known-unresolved lids untouched', async () => {
const svc = new StatusStoreService(repository, storageService, fakeConfigService(), lidStore({ '222': null }));
const now = Date.now();
await svc.ingest('sess', { waStatusId: 'u1', contactJid: '222@lid', type: 'text', postedAt: now });
await svc.ingest('sess', { waStatusId: 'u2', contactJid: '333@lid', type: 'text', postedAt: now + 1 });
const contacts = (await svc.list('sess')).map(s => s.contact.id);
expect(contacts).toContain('222@lid');
expect(contacts).toContain('333@lid');
});
it("listByContact matches rows stored under the contact's lid when queried by phone", async () => {
const svc = new StatusStoreService(repository, storageService, fakeConfigService(), lidStore({ '111': '628111' }));
await svc.ingest('sess', { waStatusId: 'l3', contactJid: '111@lid', type: 'text', postedAt: Date.now() });
const out = await svc.listByContact('sess', '[email protected]');
expect(out).toHaveLength(1);
expect(out[0].contact.id).toBe('[email protected]');
});
it("listByContact forward-resolves a lid query to rows stored under the contact's phone", async () => {
const svc = new StatusStoreService(repository, storageService, fakeConfigService(), lidStore({ '111': '628111' }));
await svc.ingest('sess', { waStatusId: 'l4', contactJid: '[email protected]', type: 'text', postedAt: Date.now() });
const out = await svc.listByContact('sess', '111@lid');
expect(out).toHaveLength(1);
expect(out[0].contact.id).toBe('[email protected]');
});
it.each(['[email protected]', '111@LID', ' 111@lid '])(
'listByContact treats %p as a lid, matching its phone and lid rows',
async query => {
const svc = new StatusStoreService(
repository,
storageService,
fakeConfigService(),
lidStore({ '111': '628111' }),
);
const now = Date.now();
await svc.ingest('sess', { waStatusId: 'h1', contactJid: '[email protected]', type: 'text', postedAt: now });
await svc.ingest('sess', { waStatusId: 'h2', contactJid: '111@lid', type: 'text', postedAt: now + 1 });
const out = await svc.listByContact('sess', query);
expect(out).toHaveLength(2);
},
);
it("listByContact never reads a lid's digits as a phone", async () => {
// Lid 111 is 628111. A phone 111 and the lid 999 mapped to that phone are someone else.
const svc = new StatusStoreService(
repository,
storageService,
fakeConfigService(),
lidStore({ '111': '628111', '999': '111' }),
);
const now = Date.now();
await svc.ingest('sess', { waStatusId: 'own-lid', contactJid: '111@lid', type: 'text', postedAt: now });
await svc.ingest('sess', { waStatusId: 'own-phone', contactJid: '[email protected]', type: 'text', postedAt: now + 1 });
await svc.ingest('sess', { waStatusId: 'other-phone', contactJid: '[email protected]', type: 'text', postedAt: now + 2 });
await svc.ingest('sess', { waStatusId: 'other-lid', contactJid: '999@lid', type: 'text', postedAt: now + 3 });
const ids = (await svc.listByContact('sess', '111@lid')).map(s => s.id).sort();
expect(ids).toEqual(['own-lid', 'own-phone']);
});
it.each([true, false])('listByContact checks table origin with an empty cache (reported=%s)', async isReported => {
const table = [{ lid: '111', phone: '628111', isReported }];
const store = new LidMappingStoreService({
find: () => Promise.resolve([]),
findOne: ({ where }: { where: { lid: string } }) => Promise.resolve(table.find(r => r.lid === where.lid) ?? null),
} as unknown as Repository<LidMapping>);
const svc = new StatusStoreService(repository, storageService, fakeConfigService(), store);
await svc.ingest('sess', { waStatusId: 'l6', contactJid: '[email protected]', type: 'text', postedAt: Date.now() });
const out = await svc.listByContact('sess', '111@lid');
expect(out).toHaveLength(isReported ? 1 : 0);
});
it('never resolves phone-shaped JIDs through the lid map (digit-collision guard)', async () => {
// A lid key colliding with a phone's digits must not rename a phone-form row.
const svc = new StatusStoreService(
repository,
storageService,
fakeConfigService(),
lidStore({ '628111': '628999' }),
);
await svc.ingest('sess', { waStatusId: 'l5', contactJid: '[email protected]', type: 'text', postedAt: Date.now() });
const out = await svc.list('sess');
expect(out[0].contact.id).toBe('[email protected]');
});
});
describe('StatusStoreService.purgeExpired', () => {
let baseDir: string;
let ds: DataSource;
let repository: Repository<StatusUpdate>;
let storageService: StorageService;
let service: StatusStoreService;
beforeEach(async () => {
baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'owa-status-purge-'));
ds = new DataSource({ type: 'better-sqlite3', database: ':memory:', entities: [StatusUpdate], synchronize: true });
await ds.initialize();
repository = ds.getRepository(StatusUpdate);
storageService = makeStorageService(path.join(baseDir, 'media'));
service = new StatusStoreService(repository, storageService, fakeConfigService());
});
afterEach(async () => {
if (ds.isInitialized) await ds.destroy();
fs.rmSync(baseDir, { recursive: true, force: true });
});
const ingestWithMedia = async (waStatusId: string, postedAt: number): Promise<StatusUpdate> =>
(
await service.ingest('sess', {
waStatusId,
contactJid: '[email protected]',
type: 'image',
media: { mimetype: 'image/jpeg', data: Buffer.from(waStatusId).toString('base64') },
postedAt,
})
).row;
it('deletes expired rows and their media files, keeps live ones', async () => {
const expiredWithMedia = await ingestWithMedia('expired-media', 1000);
await service.ingest('sess', {
waStatusId: 'expired-text',
contactJid: '[email protected]',
type: 'text',
postedAt: 2000,
});
const live = await ingestWithMedia('live-media', Date.now());
const mediaFile = path.join(baseDir, 'media', expiredWithMedia.mediaPath!);
expect(fs.existsSync(mediaFile)).toBe(true);
const now = 2000 + 24 * 60 * 60 * 1000 + 1; // after both 1000/2000-posted rows expire, before `live`
const removed = await service.purgeExpired(now);
expect(removed).toBe(2);
expect(fs.existsSync(mediaFile)).toBe(false);
const remaining = await repository.find();
expect(remaining.map(r => r.waStatusId)).toEqual(['live-media']);
expect(fs.existsSync(path.join(baseDir, 'media', live.mediaPath!))).toBe(true);
});
it('returns 0 and touches nothing when no rows are expired', async () => {
await ingestWithMedia('live', Date.now());
const removed = await service.purgeExpired(0);
expect(removed).toBe(0);
expect(await repository.count()).toBe(1);
});
it('keeps a row whose media delete failed (retried next sweep), still purging the rest', async () => {
const expiredWithMedia = await ingestWithMedia('expired-media', 1000);
await service.ingest('sess', {
waStatusId: 'expired-text',
contactJid: '[email protected]',
type: 'text',
postedAt: 2000,
});
const mediaFile = path.join(baseDir, 'media', expiredWithMedia.mediaPath!);
// A backend outage fails the file delete: the row must survive (deleting it would orphan the
// file permanently), while the file-less text row is still purged.
const failingStorage = {
deleteFile: jest.fn().mockRejectedValue(new Error('backend down')),
} as unknown as StorageService;
const failingService = new StatusStoreService(repository, failingStorage, fakeConfigService());
const now = 2000 + 24 * 60 * 60 * 1000 + 1;
const removed = await failingService.purgeExpired(now);
expect(removed).toBe(1); // only the text row (no file to delete)
const remaining = await repository.find();
expect(remaining.map(r => r.waStatusId)).toEqual(['expired-media']);
expect(fs.existsSync(mediaFile)).toBe(true);
// The next sweep, with a healthy backend, finishes the job.
const retried = await service.purgeExpired(now);
expect(retried).toBe(1);
expect(await repository.count()).toBe(0);
expect(fs.existsSync(mediaFile)).toBe(false);
});
it('returns 0 without throwing when every expired row keeps its row (all media deletes fail)', async () => {
const a = await ingestWithMedia('expired-a', 1000);
const b = await ingestWithMedia('expired-b', 2000);
// Every expired row has a media file and every delete fails, so nothing is deletable — an
// unguarded delete([]) would throw TypeORM's empty-criteria error instead of returning 0.
const deleteFile = jest.fn().mockRejectedValue(new Error('backend down'));
const failingStorage = { deleteFile } as unknown as StorageService;
const failingService = new StatusStoreService(repository, failingStorage, fakeConfigService());
const now = 2000 + 24 * 60 * 60 * 1000 + 1;
await expect(failingService.purgeExpired(now)).resolves.toBe(0);
// Rows and files all survive for the next sweep's retry.
const remaining = await repository.find();
expect(remaining.map(r => r.waStatusId).sort()).toEqual(['expired-a', 'expired-b']);
expect(fs.existsSync(path.join(baseDir, 'media', a.mediaPath!))).toBe(true);
expect(fs.existsSync(path.join(baseDir, 'media', b.mediaPath!))).toBe(true);
// Tried once each, not re-selected in a loop.
expect(deleteFile).toHaveBeenCalledTimes(2);
});
/** Seed rows cheaply, in statements well under SQLite's bind-parameter ceiling. */
const seed = async (rows: Array<Partial<StatusUpdate>>): Promise<void> => {
for (let i = 0; i < rows.length; i += 100) {
await repository.insert(
rows.slice(i, i + 100).map(r => ({
sessionId: 'sess',
contactJid: '[email protected]',
waStatusId: r.id,
type: 'text' as const,
mediaOmitted: false,
postedAt: 1000,
expiresAt: 2000,
...r,
})),
);
}
};
const id = (prefix: string, i: number): string => `${prefix}-0000-4000-8000-${String(i).padStart(12, '0')}`;
it('drains a backlog in batches, never deleting more than 500 rows in one statement', async () => {
await seed([
...Array.from({ length: 1201 }, (_, i) => ({ id: id('00000000', i) })),
{ id: id('ffffffff', 0), expiresAt: Date.now() + 60_000 },
]);
const del = jest.spyOn(repository, 'delete');
expect(await service.purgeExpired(Date.now())).toBe(1201);
const sizes = del.mock.calls.map(([ids]) => (ids as string[]).length);
expect(sizes).toEqual([500, 500, 201]);
expect((await repository.find()).map(r => r.id)).toEqual([id('ffffffff', 0)]);
del.mockRestore();
}, 30_000);
it('does not let a batch of undeletable media block newer expired rows', async () => {
// Ids sort the undeletable rows first: a purge that restarted from the lowest id after an
// all-failed batch would never reach the rows behind them.
await seed([
...Array.from({ length: 510 }, (_, i) => ({
id: id('00000000', i),
type: 'image' as const,
mediaPath: `bad/${i}`,
})),
...Array.from({ length: 5 }, (_, i) => ({
id: id('ffffffff', i),
type: 'image' as const,
mediaPath: `good/${i}`,
})),
]);
const deleteFile = jest.fn((key: string) =>
key.startsWith('bad/') ? Promise.reject(new Error('EACCES')) : Promise.resolve(),
);
const storage = { deleteFile } as unknown as StorageService;
const purger = new StatusStoreService(repository, storage, fakeConfigService());
// A batch where every delete fails ends the run instead of walking on through the backlog.
expect(await purger.purgeExpired(Date.now())).toBe(0);
expect(deleteFile).toHaveBeenCalledTimes(500);
// The next run resumes after that batch.
expect(await purger.purgeExpired(Date.now())).toBe(5);
expect(deleteFile).toHaveBeenCalledTimes(515);
expect(await repository.count()).toBe(510);
// Once the walk is drained, the next run starts over and retries the undeletable rows.
await purger.purgeExpired(Date.now());
expect(deleteFile.mock.calls[515][0]).toBe('bad/0');
}, 30_000);
});
describe('StatusStoreService.sweepOrphanedMedia', () => {
let baseDir: string;
let ds: DataSource;
let repository: Repository<StatusUpdate>;
let storageService: StorageService;
let service: StatusStoreService;
beforeEach(async () => {
baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'owa-status-sweep-'));
ds = new DataSource({ type: 'better-sqlite3', database: ':memory:', entities: [StatusUpdate], synchronize: true });
await ds.initialize();
repository = ds.getRepository(StatusUpdate);
storageService = makeStorageService(path.join(baseDir, 'media'));
service = new StatusStoreService(repository, storageService, fakeConfigService());
});
afterEach(async () => {
if (ds.isInitialized) await ds.destroy();
fs.rmSync(baseDir, { recursive: true, force: true });
});
const ingestWithMedia = async (waStatusId: string, postedAt: number): Promise<StatusUpdate> =>
(
await service.ingest('sess', {
waStatusId,
contactJid: '[email protected]',
type: 'image',
media: { mimetype: 'image/jpeg', data: Buffer.from(waStatusId).toString('base64') },
postedAt,
})
).row;
const writeFile = (key: string, contents: string): void => {
const full = path.join(baseDir, 'media', key);
fs.mkdirSync(path.dirname(full), { recursive: true });
fs.writeFileSync(full, contents);
};
it('reaps an orphan only after the grace window; never touches referenced or non-status files', async () => {
const live = await ingestWithMedia('live', Date.now());
const liveFile = path.join(baseDir, 'media', live.mediaPath!);
// A file with no referencing row — the crash-between-write-and-row-update leftover.
writeFile('statuses/sess/orphan.jpg', 'orphan');
// Chat media shares the store; the sweep is scoped to the statuses/ prefix.
writeFile('chat/sess/keep.jpg', 'keep');
const t0 = Date.now();
// First sighting only records the orphan; inside the grace window nothing is deleted.
expect(await service.sweepOrphanedMedia(t0)).toBe(0);
expect(await service.sweepOrphanedMedia(t0 + 30 * 60 * 1000)).toBe(0);
expect(fs.existsSync(path.join(baseDir, 'media', 'statuses', 'sess', 'orphan.jpg'))).toBe(true);
// Past the grace window (default 1h) the orphan is reaped; referenced and non-status files stay.
expect(await service.sweepOrphanedMedia(t0 + 61 * 60 * 1000)).toBe(1);
expect(fs.existsSync(path.join(baseDir, 'media', 'statuses', 'sess', 'orphan.jpg'))).toBe(false);
expect(fs.existsSync(liveFile)).toBe(true);
expect(fs.existsSync(path.join(baseDir, 'media', 'chat', 'sess', 'keep.jpg'))).toBe(true);
});
it('never reaps a file that becomes referenced between sightings', async () => {
// First pass sees the file while its row update has not landed yet (the ingest crash window).
writeFile('statuses/sess/pending.jpg', 'pending');
const t0 = Date.now();
expect(await service.sweepOrphanedMedia(t0)).toBe(0);
// The row update lands, now referencing the file.
const row = new StatusUpdate();
row.sessionId = 'sess';
row.contactJid = '[email protected]';
row.waStatusId = 'late-reference';
row.type = 'image';
row.postedAt = t0;
row.expiresAt = t0 + 24 * 60 * 60 * 1000;
row.mediaPath = 'statuses/sess/pending.jpg';
row.mediaMimetype = 'image/jpeg';
row.mediaOmitted = false;
await repository.save(row);
// Even past the grace window the file is safe — the referenced check re-reads the rows.
expect(await service.sweepOrphanedMedia(t0 + 61 * 60 * 1000)).toBe(0);
expect(fs.existsSync(path.join(baseDir, 'media', 'statuses', 'sess', 'pending.jpg'))).toBe(true);
});
it('honors a configured status.orphanGraceMs override', async () => {
const shortGrace = new StatusStoreService(
repository,
storageService,
fakeConfigService({ 'status.orphanGraceMs': 1000 }),
);
writeFile('statuses/sess/orphan.jpg', 'orphan');
const t0 = Date.now();
expect(await shortGrace.sweepOrphanedMedia(t0)).toBe(0);
expect(await shortGrace.sweepOrphanedMedia(t0 + 1001)).toBe(1);
expect(fs.existsSync(path.join(baseDir, 'media', 'statuses', 'sess', 'orphan.jpg'))).toBe(false);
});
it('reaps every orphan under its prefix, not just the first few', async () => {
for (let i = 0; i < 8; i++) writeFile(`statuses/sess/orphan-${i}.jpg`, 'orphan');
const t0 = Date.now();
expect(await service.sweepOrphanedMedia(t0)).toBe(0); // first sighting starts the grace clock
expect(await service.sweepOrphanedMedia(t0 + 61 * 60 * 1000)).toBe(8);
expect(fs.readdirSync(path.join(baseDir, 'media', 'statuses', 'sess'))).toHaveLength(0);
});
});
describe('StatusStoreService onModuleInit/onModuleDestroy (sweep scheduling)', () => {
const mockDeps = (): { repo: Repository<StatusUpdate>; storage: StorageService; find: jest.Mock } => {
const find = jest.fn().mockResolvedValue([]);
const repo = { find } as unknown as Repository<StatusUpdate>;
const storage = { iterateFiles: jest.fn().mockReturnValue([]) } as unknown as StorageService;
return { repo, storage, find };
};
it('purges once at startup and schedules a recurring sweep, cleared on destroy', async () => {
const { repo, storage } = mockDeps();
const service = new StatusStoreService(repo, storage, fakeConfigService());
jest.useFakeTimers();
try {
const purgeSpy = jest.spyOn(service, 'purgeExpired').mockResolvedValue(0);
service.onModuleInit();
expect(purgeSpy).toHaveBeenCalledTimes(1);
purgeSpy.mockClear();
await jest.advanceTimersByTimeAsync(15 * 60 * 1000);
expect(purgeSpy).toHaveBeenCalledTimes(1);
service.onModuleDestroy();
purgeSpy.mockClear();
await jest.advanceTimersByTimeAsync(15 * 60 * 1000);
expect(purgeSpy).not.toHaveBeenCalled();
} finally {
jest.useRealTimers();
}
});
it('skips a purge tick while the previous purge is still running', async () => {
const { repo, storage } = mockDeps();
const service = new StatusStoreService(repo, storage, fakeConfigService());
jest.useFakeTimers();
let release: () => void = () => undefined;
const purgeSpy = jest
.spyOn(service, 'purgeExpired')
.mockImplementationOnce(() => new Promise<number>(resolve => (release = () => resolve(0))))
.mockResolvedValue(0);
try {
service.onModuleInit();
await jest.advanceTimersByTimeAsync(15 * 60 * 1000);
await jest.advanceTimersByTimeAsync(15 * 60 * 1000);
expect(purgeSpy).toHaveBeenCalledTimes(1);
release();
await jest.advanceTimersByTimeAsync(15 * 60 * 1000);
expect(purgeSpy).toHaveBeenCalledTimes(2);
} finally {
service.onModuleDestroy();
release();
jest.useRealTimers();
}
});
it('skips an orphan sweep tick while the previous sweep is still running', async () => {
const { repo, storage } = mockDeps();
const service = new StatusStoreService(
repo,
storage,
fakeConfigService({ 'status.orphanSweepIntervalMs': 60_000 }),
);
jest.useFakeTimers();
let release: () => void = () => undefined;
jest.spyOn(service, 'purgeExpired').mockResolvedValue(0);
const sweepSpy = jest
.spyOn(service, 'sweepOrphanedMedia')
.mockImplementationOnce(() => new Promise<number>(resolve => (release = () => resolve(0))))
.mockResolvedValue(0);
try {
service.onModuleInit();
await jest.advanceTimersByTimeAsync(60_000);
await jest.advanceTimersByTimeAsync(60_000);
expect(sweepSpy).toHaveBeenCalledTimes(1);
release();
await jest.advanceTimersByTimeAsync(60_000);
expect(sweepSpy).toHaveBeenCalledTimes(2);
} finally {
service.onModuleDestroy();
release();
jest.useRealTimers();
}
});
it('runs the orphan sweep once at startup and on its own (slower) cadence, cleared on destroy', async () => {
const { repo, storage } = mockDeps();
const service = new StatusStoreService(repo, storage, fakeConfigService());
jest.useFakeTimers();
try {
const sweepSpy = jest.spyOn(service, 'sweepOrphanedMedia').mockResolvedValue(0);
service.onModuleInit();
expect(sweepSpy).toHaveBeenCalledTimes(1);
// The TTL purge fires every 15 min; the orphan sweep only on its own 1h interval.
sweepSpy.mockClear();
await jest.advanceTimersByTimeAsync(15 * 60 * 1000);
expect(sweepSpy).not.toHaveBeenCalled();
await jest.advanceTimersByTimeAsync(45 * 60 * 1000);
expect(sweepSpy).toHaveBeenCalledTimes(1);
service.onModuleDestroy();
sweepSpy.mockClear();
await jest.advanceTimersByTimeAsync(60 * 60 * 1000);
expect(sweepSpy).not.toHaveBeenCalled();
} finally {
jest.useRealTimers();
}
});
it('honors a configured status.orphanSweepIntervalMs override', async () => {
const { repo, storage } = mockDeps();
const service = new StatusStoreService(
repo,
storage,
fakeConfigService({ 'status.orphanSweepIntervalMs': 5 * 60 * 1000 }),
);
jest.useFakeTimers();
try {
const sweepSpy = jest.spyOn(service, 'sweepOrphanedMedia').mockResolvedValue(0);
service.onModuleInit();
sweepSpy.mockClear();
await jest.advanceTimersByTimeAsync(5 * 60 * 1000);
expect(sweepSpy).toHaveBeenCalledTimes(1);
service.onModuleDestroy();
} finally {
jest.useRealTimers();
}
});
});