Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.1 KB
Raw Blame
/**
 * waitForCompletion tests. Uses PGLite in-memory so the poll path exercises
 * a real getJob over a real engine.
 */

import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { MinionQueue } from '../src/core/minions/queue.ts';
import { waitForCompletion, waitForCompletionRenewing, TimeoutError, __testing } from '../src/core/minions/wait-for-completion.ts';

let engine: PGLiteEngine;
let queue: MinionQueue;

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({ database_url: '' });
  await engine.initSchema();
  queue = new MinionQueue(engine);
}, 60_000);

afterAll(async () => {
  await engine.disconnect();
});

beforeEach(async () => {
  await engine.executeRaw('DELETE FROM minion_jobs');
});

describe('waitForCompletion terminal states', () => {
  test('TERMINAL_STATES covers every terminal MinionJobStatus value', () => {
    expect(__testing.TERMINAL_STATES).toEqual(['completed', 'failed', 'dead', 'cancelled']);
  });

  test('returns immediately when job already completed (fast path)', async () => {
    const j = await queue.add('t', {});
    const claimed = await queue.claim('tok', 30000, 'default', ['t']);
    await queue.completeJob(claimed!.id, 'tok', { ok: true });

    const t0 = Date.now();
    const res = await waitForCompletion(queue, j.id, { pollMs: 500 });
    expect(res.status).toBe('completed');
    expect(Date.now() - t0).toBeLessThan(300); // no full poll cycle
  });

  test('returns when job transitions to failed mid-wait', async () => {
    const j = await queue.add('t', {});
    const p = waitForCompletion(queue, j.id, { pollMs: 25, timeoutMs: 5000 });
    // Transition the job to failed after a brief delay.
    setTimeout(async () => {
      const claimed = await queue.claim('tok', 30000, 'default', ['t']);
      await queue.failJob(claimed!.id, 'tok', 'boom', 'failed');
    }, 60);
    const res = await p;
    expect(res.status).toBe('failed');
  });

  test('returns when job transitions to cancelled', async () => {
    const j = await queue.add('t', {});
    const p = waitForCompletion(queue, j.id, { pollMs: 25, timeoutMs: 5000 });
    setTimeout(() => { queue.cancelJob(j.id); }, 60);
    const res = await p;
    expect(res.status).toBe('cancelled');
  });

  test('throws TimeoutError when job stays non-terminal past timeoutMs', async () => {
    const j = await queue.add('t', {});
    await expect(
      waitForCompletion(queue, j.id, { pollMs: 25, timeoutMs: 100 })
    ).rejects.toBeInstanceOf(TimeoutError);
  });

  test('TimeoutError carries the jobId and elapsedMs', async () => {
    const j = await queue.add('t', {});
    try {
      await waitForCompletion(queue, j.id, { pollMs: 25, timeoutMs: 80 });
      throw new Error('should have thrown');
    } catch (e) {
      expect(e).toBeInstanceOf(TimeoutError);
      const te = e as TimeoutError;
      expect(te.jobId).toBe(j.id);
      expect(te.elapsedMs).toBeGreaterThanOrEqual(80);
    }
  });

  test('TimeoutError does NOT cancel the job', async () => {
    const j = await queue.add('t', {});
    try {
      await waitForCompletion(queue, j.id, { pollMs: 25, timeoutMs: 80 });
    } catch {}
    const still = await queue.getJob(j.id);
    expect(still?.status).toBe('waiting');
  });

  test('AbortSignal exits loop early without throwing', async () => {
    const j = await queue.add('t', {});
    const ac = new AbortController();
    setTimeout(() => ac.abort(), 50);
    const res = await waitForCompletion(queue, j.id, {
      pollMs: 25,
      timeoutMs: 5000,
      signal: ac.signal,
    });
    expect(res.id).toBe(j.id);
    // Still waiting — we just stopped polling.
    expect(res.status).toBe('waiting');
  });

  test('throws when job id does not exist', async () => {
    await expect(waitForCompletion(queue, 99_999, { pollMs: 10, timeoutMs: 100 }))
      .rejects.toThrow(/not found/);
  });
});

describe('waitForCompletionRenewing', () => {
  // Claim + complete the named job after `afterMs`. Returned promise is
  // awaited alongside the wait so a fixture failure surfaces instead of
  // vanishing in a detached timer callback.
  function completeLater(name: string, afterMs: number): Promise<void> {
    const token = `renew-tok-${afterMs}-${Math.random().toString(36).slice(2)}`;
    return (async () => {
      await new Promise(r => setTimeout(r, afterMs));
      const claimed = await queue.claim(token, 30_000, 'default', [name]);
      if (!claimed) throw new Error(`nothing to claim for ${name}`);
      await queue.completeJob(claimed.id, token, { done: true });
    })();
  }

  test('multi-chunk wait resolves with the terminal job after crossing >=2 chunk boundaries', async () => {
    const j = await queue.add('t', {});
    let renews = 0;
    const t0 = Date.now();
    const [res] = await Promise.all([
      waitForCompletionRenewing(queue, j.id, {
        pollMs: 25,
        timeoutMs: 30_000,
        chunkMs: 50, // clamped to the 1s floor — 2.3s completion spans >=2 chunks
        renew: async () => { renews++; },
      }),
      completeLater('t', 2300),
    ]);
    expect(res.id).toBe(j.id);
    expect(res.status).toBe('completed');
    expect(Date.now() - t0).toBeGreaterThanOrEqual(2000);
    expect(renews).toBeGreaterThanOrEqual(2);
  });

  test('renew is invoked between chunks when the wait spans a chunk boundary', async () => {
    const j = await queue.add('t', {});
    let renews = 0;
    const [res] = await Promise.all([
      waitForCompletionRenewing(queue, j.id, {
        pollMs: 25,
        timeoutMs: 30_000,
        chunkMs: 50,
        renew: async () => { renews++; },
      }),
      completeLater('t', 1300),
    ]);
    expect(res.status).toBe('completed');
    expect(renews).toBeGreaterThanOrEqual(1);
  });

  test('a throwing renew is swallowed: the wait continues and still resolves', async () => {
    const j = await queue.add('t', {});
    let renews = 0;
    const [res] = await Promise.all([
      waitForCompletionRenewing(queue, j.id, {
        pollMs: 25,
        timeoutMs: 30_000,
        chunkMs: 50,
        renew: async () => { renews++; throw new Error('lease renewal exploded'); },
      }),
      completeLater('t', 1300),
    ]);
    expect(res.status).toBe('completed');
    expect(renews).toBeGreaterThanOrEqual(1); // it DID throw at least once and was swallowed
  });

  test('a non-TimeoutError from the inner wait rethrows immediately without renewing', async () => {
    let renews = 0;
    const renew = async () => { renews++; };

    // Fast-path arm: the inner first read throws 'not found'.
    await expect(
      waitForCompletionRenewing(queue, 99_999, { pollMs: 10, timeoutMs: 30_000, renew })
    ).rejects.toThrow(/not found/);

    // Poll-loop arm: the row vanishes mid-wait and the inner poll throws.
    const j = await queue.add('t', {});
    const p = waitForCompletionRenewing(queue, j.id, { pollMs: 25, timeoutMs: 30_000, renew });
    setTimeout(() => { void engine.executeRaw('DELETE FROM minion_jobs WHERE id = $1', [j.id]); }, 60);
    await expect(p).rejects.toThrow(/disappeared mid-wait/);

    expect(renews).toBe(0);
  });

  test('total-deadline exhaustion propagates TimeoutError with jobId/elapsedMs and never renews or cancels', async () => {
    const j = await queue.add('t', {});
    let renews = 0;
    const t0 = Date.now();
    try {
      await waitForCompletionRenewing(queue, j.id, {
        pollMs: 25,
        timeoutMs: 150,
        chunkMs: 50,
        renew: async () => { renews++; },
      });
      throw new Error('should have thrown');
    } catch (e) {
      expect(e).toBeInstanceOf(TimeoutError);
      const te = e as TimeoutError;
      expect(te.jobId).toBe(j.id);
      expect(te.elapsedMs).toBeGreaterThan(0);
    }
    // The whole timeoutMs budget was honored before the throw.
    expect(Date.now() - t0).toBeGreaterThanOrEqual(150);
    // Deadline check precedes renew in the catch, so the final timeout never renews.
    expect(renews).toBe(0);
    // Like the plain wait, timing out never cancels the job.
    expect((await queue.getJob(j.id))?.status).toBe('waiting');
  });

  test('chunkMs below the 1s floor is clamped: a sub-second completion sees zero chunk timeouts', async () => {
    const j = await queue.add('t', {});
    let renews = 0;
    const [res] = await Promise.all([
      waitForCompletionRenewing(queue, j.id, {
        pollMs: 25,
        timeoutMs: 30_000,
        chunkMs: 1,
        renew: async () => { renews++; },
      }),
      completeLater('t', 200),
    ]);
    expect(res.status).toBe('completed');
    // If chunkMs 1 were honored literally, every 1ms chunk would time out and
    // renew would have fired dozens of times before the 200ms completion.
    expect(renews).toBe(0);
  });

  test('resolves across a chunk boundary when no renew option is provided', async () => {
    const j = await queue.add('t', {});
    const t0 = Date.now();
    const [res] = await Promise.all([
      waitForCompletionRenewing(queue, j.id, { pollMs: 25, timeoutMs: 30_000, chunkMs: 50 }),
      completeLater('t', 1300),
    ]);
    expect(res.status).toBe('completed');
    expect(Date.now() - t0).toBeGreaterThanOrEqual(1000); // crossed >=1 chunk boundary renew-less
  });
});