Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

15.1 KB
Raw Blame
import { ConfigService } from '@nestjs/config';
import { HttpException } from '@nestjs/common';
import { DataSource, Repository } from 'typeorm';
import { EngineRegistry } from '../../engine/engine-registry.service';
import { type IWhatsAppEngine } from '../../engine/interfaces/whatsapp-engine.interface';
import { HookManager, type HookContext } from '../../core/hooks';
import { Session } from '../session/entities/session.entity';
import { Message, MessageDirection } from './entities/message.entity';
import { MessageSendService } from './message-send.service';
import { SEND_PACING_LIMITED, SendPacingService } from './send-pacing.service';
import { computeSendPacingConfig } from './send-pacing.config';
import { closeSessionWrites } from '../../common/utils/session-write-scope';

const NOW = new Date('2026-06-01T12:00:00Z');
const deferred = () => {
  let resolve!: () => void;
  const promise = new Promise<void>(res => (resolve = res));
  return { promise, resolve };
};

describe('MessageSendService preparation pacing', () => {
  let ds: DataSource;
  let messages: Repository<Message>;
  let sender: MessageSendService;
  let hooks: HookManager;
  let engines: EngineRegistry;
  let engine: Record<string, jest.Mock>;
  let pacingConfig: ReturnType<typeof computeSendPacingConfig>;
  let pacing: SendPacingService;

  const send = () => sender.sendText('s1', { chatId: '[email protected]', text: 'hello' });
  const replaceSession = async () => {
    const deletion = closeSessionWrites(ds, 's1');
    await deletion.drain();
    engines.delete('s1');
    await ds.transaction(async manager => {
      await manager.delete(Message, { sessionId: 's1' });
      await manager.delete(Session, { id: 's1' });
    });
    deletion.release();
    await ds.getRepository(Session).save({ id: 's1', name: 'replacement', createdAt: new Date() });
    engines.set('s1', engine as unknown as IWhatsAppEngine);
  };
  const expectLimited = async () => {
    try {
      await sender.sendText('s1', { chatId: '[email protected]', text: 'second' });
      throw new Error('Expected the send to be paced');
    } catch (error) {
      expect(error).toBeInstanceOf(HttpException);
      const response = (error as HttpException).getResponse() as { code: string; retryAfterSeconds: number };
      expect(response.code).toBe(SEND_PACING_LIMITED);
      expect(Number.isFinite(response.retryAfterSeconds)).toBe(true);
      expect(response.retryAfterSeconds).toBeGreaterThan(0);
    }
  };

  beforeEach(async () => {
    process.env.SIMULATE_TYPING = 'false';
    jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate', 'queueMicrotask'] }).setSystemTime(NOW);
    ds = new DataSource({
      type: 'better-sqlite3',
      database: ':memory:',
      entities: [Session, Message],
      synchronize: true,
    });
    await ds.initialize();
    const sessions = ds.getRepository(Session);
    await sessions.save({ id: 's1', name: 'sender', createdAt: NOW });
    messages = ds.getRepository(Message);
    pacingConfig = { ...computeSendPacingConfig({}), enabled: true, warmupSchedule: [1], coldSchedule: [] };
    const config = { get: (key: string) => (key === 'sendPacing' ? pacingConfig : undefined) } as ConfigService;
    pacing = new SendPacingService(messages, sessions, config);
    hooks = new HookManager();
    engines = new EngineRegistry();
    engine = {};
    let sent = 0;
    for (const method of [
      'sendTextMessage',
      'sendImageMessage',
      'sendVideoMessage',
      'sendAudioMessage',
      'sendDocumentMessage',
      'sendStickerMessage',
      'sendLocationMessage',
      'sendContactMessage',
      'sendPollMessage',
      'replyToMessage',
      'clickButton',
      'forwardMessage',
    ])
      engine[method] = jest
        .fn()
        .mockImplementation(() => Promise.resolve({ id: `sent-${++sent}`, timestamp: Date.now() / 1000 }));
    engines.set('s1', engine as unknown as IWhatsAppEngine);
    sender = new MessageSendService(
      messages,
      { findOne: (id: string) => sessions.findOneByOrFail({ id }) } as never,
      engines,
      hooks,
      {} as never,
      pacing,
      config,
    );
  });

  afterEach(async () => {
    jest.useRealTimers();
    delete process.env.SIMULATE_TYPING;
    jest.restoreAllMocks();
    await ds.destroy();
  });

  it.each(['daily', 'cold'])('holds the %s allowance while a hook takes more than five minutes', async cap => {
    if (cap === 'cold') {
      pacingConfig.warmupSchedule = [100];
      pacingConfig.coldSchedule = [1];
    }
    const entered = deferred();
    const finish = deferred();
    let calls = 0;
    hooks.register('moderation', 'message:sending', async context => {
      if (++calls === 1) {
        entered.resolve();
        await finish.promise;
      }
      return { continue: true, data: context.data };
    });
    const pending = send();
    await entered.promise;
    expect(await messages.count()).toBe(0);
    jest.setSystemTime(NOW.getTime() + 5 * 60_000 + 1);
    try {
      await expectLimited();
      expect(calls).toBe(1);
    } finally {
      finish.resolve();
      await pending;
    }
    expect(engine.sendTextMessage).toHaveBeenCalledTimes(1);
    expect(await messages.count()).toBe(1);
    await expectLimited();
  });

  it.each(['reply', 'clickButton', 'save'])('holds the allowance through delayed %s preparation', async stage => {
    const entered = deferred();
    const finish = deferred();
    if (stage === 'save') {
      const save = messages.save.bind(messages);
      jest.spyOn(messages, 'save').mockImplementationOnce(async message => {
        entered.resolve();
        await finish.promise;
        return save(message);
      });
    } else {
      jest
        .spyOn(sender as unknown as { resolveQuotedBody: () => Promise<string> }, 'resolveQuotedBody')
        .mockImplementationOnce(async () => {
          entered.resolve();
          await finish.promise;
          return 'prompt';
        });
    }
    const pending =
      stage === 'reply'
        ? sender.reply('s1', { chatId: '[email protected]', quotedMessageId: 'prompt', text: 'reply' })
        : stage === 'clickButton'
          ? sender.clickButton('s1', { chatId: '[email protected]', messageId: 'prompt', buttonId: 'yes' })
          : send();
    await entered.promise;
    jest.setSystemTime(NOW.getTime() + 5 * 60_000 + 1);
    try {
      await expectLimited();
    } finally {
      finish.resolve();
      await pending;
    }
    expect(await messages.count()).toBe(1);
  });

  it.each(['veto', 'missing engine', 'invalid media', 'quote lookup', 'initial save'])(
    'refunds a no-row send after %s',
    async reason => {
      if (reason === 'veto')
        hooks.register('moderation', 'message:sending', () => Promise.resolve({ continue: false }));
      if (reason === 'missing engine') engines.delete('s1');
      if (reason === 'initial save') jest.spyOn(messages, 'save').mockRejectedValueOnce(new Error('write failed'));
      if (reason === 'quote lookup') {
        jest
          .spyOn(sender as unknown as { resolveQuotedBody: () => Promise<string> }, 'resolveQuotedBody')
          .mockRejectedValueOnce(new Error('quote lookup failed'));
      }

      const pending =
        reason === 'invalid media'
          ? sender.sendImage('s1', { chatId: '[email protected]' })
          : reason === 'quote lookup'
            ? sender.reply('s1', { chatId: '[email protected]', quotedMessageId: 'prompt', text: 'reply' })
            : send();
      await expect(pending).rejects.toThrow();

      expect(await messages.count()).toBe(0);
      expect(engine.sendTextMessage).not.toHaveBeenCalled();
      hooks.unregisterPlugin('moderation');
      engines.set('s1', engine as unknown as IWhatsAppEngine);
      await expect(send()).resolves.toMatchObject({ messageId: 'sent-1' });
      expect(await messages.count()).toBe(1);
    },
  );

  it('counts the durable row once after handing off its admission', async () => {
    pacingConfig.warmupSchedule = [2];

    await send();
    await send();

    expect(await messages.count()).toBe(2);
    expect(engine.sendTextMessage).toHaveBeenCalledTimes(2);
    await expectLimited();
  });

  it('keeps pacing optional', async () => {
    pacingConfig.enabled = false;

    await send();
    await send();

    expect(await messages.count()).toBe(2);
    expect(engine.sendTextMessage).toHaveBeenCalledTimes(2);
  });

  it.each(['daily', 'cold'])('carries a preparing %s admission across UTC midnight', async cap => {
    if (cap === 'cold') {
      pacingConfig.warmupSchedule = [100];
      pacingConfig.coldSchedule = [1];
    }
    const entered = deferred();
    const finish = deferred();
    let calls = 0;
    hooks.register('moderation', 'message:sending', async context => {
      if (++calls === 1) {
        entered.resolve();
        await finish.promise;
      }
      return { continue: true, data: context.data };
    });
    const pending = send();
    await entered.promise;
    jest.setSystemTime(new Date('2026-06-02T00:00:01Z'));
    try {
      await expectLimited();
    } finally {
      finish.resolve();
      await pending;
    }
    expect(await messages.count()).toBe(1);
  });

  it.each(['daily', 'cold'])('includes current-day rows when carrying a preparing %s admission', async cap => {
    pacingConfig.warmupSchedule = cap === 'daily' ? [2] : [100];
    pacingConfig.coldSchedule = cap === 'cold' ? [2] : [];
    const entered = deferred();
    const finish = deferred();
    let calls = 0;
    hooks.register('moderation', 'message:sending', async context => {
      if (++calls === 1) {
        entered.resolve();
        await finish.promise;
      }
      return { continue: true, data: context.data };
    });
    const pending = send();
    await entered.promise;
    jest.setSystemTime(new Date('2026-06-02T00:00:01Z'));
    await messages.save({
      sessionId: 's1',
      chatId: '[email protected]',
      from: 'a',
      to: 'b',
      type: 'text',
      direction: MessageDirection.OUTGOING,
    });
    try {
      await expectLimited();
    } finally {
      finish.resolve();
      await pending;
    }
    expect(await messages.count()).toBe(2);
  });

  it('keeps the current-day admission when an older preparation is refunded', async () => {
    pacingConfig.warmupSchedule = [2];
    const older = await pacing.assertSendAllowed('s1', '[email protected]', { whilePreparing: true });
    jest.setSystemTime(new Date('2026-06-02T00:00:01Z'));
    const current = await pacing.assertSendAllowed('s1', '[email protected]', { whilePreparing: true });

    older?.();
    pacingConfig.warmupSchedule = [1];
    await expectLimited();
    current?.();

    await expect(send()).resolves.toMatchObject({ messageId: 'sent-1' });
  });

  it('refunds a retired preparation before its sending hook completes', async () => {
    const entered = deferred();
    const finish = deferred();
    hooks.register('moderation', 'message:sending', async context => {
      entered.resolve();
      await finish.promise;
      return { continue: true, data: context.data };
    });
    const old = send().catch((error: unknown) => error);
    await entered.promise;
    await replaceSession();
    hooks.unregisterPlugin('moderation');
    expect(await messages.count()).toBe(0);

    try {
      await expect(send()).resolves.toMatchObject({ messageId: 'sent-1' });
      expect(engine.sendTextMessage).toHaveBeenCalledTimes(1);
    } finally {
      finish.resolve();
      await old;
    }
    expect(await old).toMatchObject({ status: 404 });
    expect(await messages.count()).toBe(1);
    await expectLimited();
  });

  it('refunds an admission whose lifetime retires during the pacing lookup', async () => {
    const entered = deferred();
    const finish = deferred();
    const count = messages.count.bind(messages);
    jest.spyOn(messages, 'count').mockImplementationOnce(async options => {
      entered.resolve();
      await finish.promise;
      return count(options);
    });
    const hook = jest.fn((context: HookContext) => Promise.resolve({ continue: true, data: context.data }));
    hooks.register('moderation', 'message:sending', hook);
    const old = send().catch((error: unknown) => error);
    await entered.promise;
    await replaceSession();

    finish.resolve();
    expect(await old).toMatchObject({ status: 404 });
    expect(hook).not.toHaveBeenCalled();
    expect(await messages.count()).toBe(0);
    await expect(send()).resolves.toMatchObject({ messageId: 'sent-1' });
    expect(engine.sendTextMessage).toHaveBeenCalledTimes(1);
  });

  // The delete transaction must not start while the insert of a pending row is in flight: the row would
  // land after the delete, for a session that no longer exists and with nothing left to settle it.
  it('drains its pending insert before the session content is deleted', async () => {
    const entered = deferred();
    const finish = deferred();
    const save = messages.save.bind(messages);
    jest.spyOn(messages, 'save').mockImplementationOnce(async message => {
      entered.resolve();
      await finish.promise;
      return save(message);
    });
    const old = send().catch((error: unknown) => error);
    await entered.promise;
    let deleted = false;
    const deletion = replaceSession().then(() => {
      deleted = true;
    });
    await new Promise<void>(setImmediate);
    const deletedBeforeInsert = deleted;
    finish.resolve();
    await Promise.all([deletion, old]);

    expect(deletedBeforeInsert).toBe(false);
    expect(await old).toMatchObject({ status: 404 });
    expect(await messages.count()).toBe(0);
  });

  // Told apart by the status the caller gets: a deleted session is a 404, where continuing to the engine
  // lookup would answer a 400 telling them to start a session that is gone.
  it('answers 404, not a missing engine, when its session is deleted during the sending hook', async () => {
    const entered = deferred();
    const finish = deferred();
    hooks.register('moderation', 'message:sending', async context => {
      entered.resolve();
      await finish.promise;
      return { continue: true, data: context.data };
    });
    const old = send().catch((error: unknown) => error);
    await entered.promise;
    const deletion = closeSessionWrites(ds, 's1');
    engines.delete('s1');
    await deletion.drain();
    deletion.release();
    finish.resolve();

    expect(await old).toMatchObject({ status: 404 });
    expect(engine.sendTextMessage).not.toHaveBeenCalled();
  });

  it('cannot dispatch or settle successfully after its pending write lifetime retires', async () => {
    const entered = deferred();
    const finish = deferred();
    const save = sender.saveOutgoingMessage.bind(sender);
    jest.spyOn(sender, 'saveOutgoingMessage').mockImplementationOnce(async (sessionId, data, lifetime) => {
      const message = await save(sessionId, data, lifetime);
      entered.resolve();
      await finish.promise;
      return message;
    });
    const old = send().catch((error: unknown) => error);
    await entered.promise;
    expect(await messages.count()).toBe(1);
    await replaceSession();

    try {
      await expect(send()).resolves.toMatchObject({ messageId: 'sent-1' });
    } finally {
      finish.resolve();
      await old;
    }
    expect(await old).toMatchObject({ status: 404 });
    expect(engine.sendTextMessage).toHaveBeenCalledTimes(1);
    expect(await messages.count()).toBe(1);
  });
});