@a5c-ai/krate 5.0.1-staging.04a3db697

package/tests/async-controller.test.js

@@ -0,0 +1,252 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  createEventBatcher,
+  createRetryPolicy,
+  createDeliveryQueue,
+  createCheckpointer,
+} from '../src/async-controller.js';
+
+// ---------------------------------------------------------------------------
+// createEventBatcher
+// ---------------------------------------------------------------------------
+
+test('createEventBatcher returns push, flush, and stop methods', () => {
+  const batcher = createEventBatcher(() => {});
+  assert.ok(typeof batcher.push === 'function', 'has push');
+  assert.ok(typeof batcher.flush === 'function', 'has flush');
+  assert.ok(typeof batcher.stop === 'function', 'has stop');
+});
+
+test('createEventBatcher: manual flush delivers accumulated events', async () => {
+  const flushed = [];
+  const batcher = createEventBatcher((events) => { flushed.push(...events); }, { flushIntervalMs: 60000 });
+  batcher.push('a');
+  batcher.push('b');
+  batcher.push('c');
+  assert.equal(flushed.length, 0, 'not flushed yet');
+  await batcher.flush();
+  assert.deepEqual(flushed, ['a', 'b', 'c']);
+});
+
+test('createEventBatcher: auto-flush when maxBatchSize is reached', async () => {
+  const flushed = [];
+  const batcher = createEventBatcher((events) => { flushed.push(...events); }, { maxBatchSize: 3, flushIntervalMs: 60000 });
+  batcher.push(1);
+  batcher.push(2);
+  batcher.push(3); // triggers auto-flush synchronously
+  // Allow microtasks to settle
+  await new Promise((r) => setImmediate(r));
+  assert.equal(flushed.length, 3, 'batch of 3 was flushed');
+  assert.deepEqual(flushed, [1, 2, 3]);
+});
+
+test('createEventBatcher: flush clears the batch (subsequent flush sends nothing)', async () => {
+  const calls = [];
+  const batcher = createEventBatcher((events) => calls.push(events), { flushIntervalMs: 60000 });
+  batcher.push('x');
+  await batcher.flush();
+  await batcher.flush();
+  assert.equal(calls.length, 1, 'only one flush call had data');
+});
+
+test('createEventBatcher: stop discards pending events', async () => {
+  const flushed = [];
+  const batcher = createEventBatcher((events) => flushed.push(...events), { flushIntervalMs: 60000 });
+  batcher.push('pending');
+  batcher.stop();
+  await new Promise((r) => setTimeout(r, 10));
+  assert.equal(flushed.length, 0, 'stopped batcher should not flush');
+});
+
+test('createEventBatcher: handler is called with array of events', async () => {
+  let received = null;
+  const batcher = createEventBatcher((events) => { received = events; }, { flushIntervalMs: 60000 });
+  batcher.push({ id: 1 });
+  await batcher.flush();
+  assert.ok(Array.isArray(received), 'handler receives an array');
+  assert.equal(received.length, 1);
+  assert.deepEqual(received[0], { id: 1 });
+});
+
+// ---------------------------------------------------------------------------
+// createRetryPolicy
+// ---------------------------------------------------------------------------
+
+test('createRetryPolicy returns shouldRetry and getDelay methods', () => {
+  const policy = createRetryPolicy();
+  assert.ok(typeof policy.shouldRetry === 'function', 'has shouldRetry');
+  assert.ok(typeof policy.getDelay === 'function', 'has getDelay');
+});
+
+test('createRetryPolicy: shouldRetry returns true while under maxRetries', () => {
+  const policy = createRetryPolicy({ maxRetries: 3 });
+  assert.equal(policy.shouldRetry(0, new Error()), true);
+  assert.equal(policy.shouldRetry(1, new Error()), true);
+  assert.equal(policy.shouldRetry(2, new Error()), true);
+});
+
+test('createRetryPolicy: shouldRetry returns false when maxRetries is reached', () => {
+  const policy = createRetryPolicy({ maxRetries: 3 });
+  assert.equal(policy.shouldRetry(3, new Error()), false);
+  assert.equal(policy.shouldRetry(4, new Error()), false);
+});
+
+test('createRetryPolicy: getDelay implements exponential backoff', () => {
+  const policy = createRetryPolicy({ baseDelayMs: 100, maxDelayMs: 10000, jitter: false });
+  assert.equal(policy.getDelay(0), 100);
+  assert.equal(policy.getDelay(1), 200);
+  assert.equal(policy.getDelay(2), 400);
+  assert.equal(policy.getDelay(3), 800);
+});
+
+test('createRetryPolicy: getDelay respects maxDelayMs cap', () => {
+  const policy = createRetryPolicy({ baseDelayMs: 1000, maxDelayMs: 3000, jitter: false });
+  assert.ok(policy.getDelay(5) <= 3000, 'delay should be capped at maxDelayMs');
+  assert.equal(policy.getDelay(10), 3000);
+});
+
+test('createRetryPolicy: getDelay with jitter returns non-negative value within cap', () => {
+  const policy = createRetryPolicy({ baseDelayMs: 100, maxDelayMs: 1000, jitter: true });
+  for (let i = 0; i < 20; i++) {
+    const delay = policy.getDelay(2);
+    assert.ok(delay >= 0, 'jitter delay must be >= 0');
+    assert.ok(delay <= 1000, 'jitter delay must be <= maxDelayMs');
+  }
+});
+
+// ---------------------------------------------------------------------------
+// createDeliveryQueue
+// ---------------------------------------------------------------------------
+
+test('createDeliveryQueue returns enqueue, drain, size, and stop methods', () => {
+  const q = createDeliveryQueue(async () => {});
+  assert.ok(typeof q.enqueue === 'function', 'has enqueue');
+  assert.ok(typeof q.drain === 'function', 'has drain');
+  assert.ok(typeof q.size === 'function', 'has size');
+  assert.ok(typeof q.stop === 'function', 'has stop');
+});
+
+test('createDeliveryQueue: processes enqueued items', async () => {
+  const processed = [];
+  const q = createDeliveryQueue(async (item) => processed.push(item));
+  q.enqueue('alpha');
+  q.enqueue('beta');
+  await q.drain();
+  assert.deepEqual(processed, ['alpha', 'beta']);
+});
+
+test('createDeliveryQueue: drain resolves when queue is empty before enqueue', async () => {
+  const q = createDeliveryQueue(async () => {});
+  await q.drain(); // should resolve immediately
+  assert.ok(true, 'drain resolved without hanging');
+});
+
+test('createDeliveryQueue: concurrency limit is respected', async () => {
+  let concurrent = 0;
+  let maxConcurrent = 0;
+  const q = createDeliveryQueue(async (_item) => {
+    concurrent++;
+    if (concurrent > maxConcurrent) maxConcurrent = concurrent;
+    await new Promise((r) => setTimeout(r, 10));
+    concurrent--;
+  }, { concurrency: 2 });
+
+  for (let i = 0; i < 6; i++) q.enqueue(i);
+  await q.drain();
+  assert.ok(maxConcurrent <= 2, `max concurrent was ${maxConcurrent}, expected <= 2`);
+});
+
+test('createDeliveryQueue: retries item on processor failure using retryPolicy', async () => {
+  let callCount = 0;
+  const retryPolicy = createRetryPolicy({ maxRetries: 2, baseDelayMs: 1, jitter: false });
+  const q = createDeliveryQueue(async (_item) => {
+    callCount++;
+    if (callCount < 3) throw new Error('transient');
+  }, { retryPolicy });
+
+  q.enqueue('item');
+  await q.drain();
+  assert.equal(callCount, 3, 'processor should have been called 3 times (2 retries)');
+});
+
+test('createDeliveryQueue: stop empties the queue', async () => {
+  const processed = [];
+  let resolveBlock;
+  const block = new Promise((r) => { resolveBlock = r; });
+  const q = createDeliveryQueue(async (item) => {
+    await block;
+    processed.push(item);
+  }, { concurrency: 1 });
+
+  q.enqueue('first');
+  q.enqueue('second');
+  q.enqueue('third');
+  q.stop();
+  resolveBlock();
+  await new Promise((r) => setTimeout(r, 20));
+  // After stop, queue is cleared so 'second' and 'third' should not be processed
+  assert.ok(processed.length < 3, 'stopped queue should not process remaining items');
+});
+
+// ---------------------------------------------------------------------------
+// createCheckpointer
+// ---------------------------------------------------------------------------
+
+test('createCheckpointer returns save, load, clear, and listKeys methods', () => {
+  const cp = createCheckpointer();
+  assert.ok(typeof cp.save === 'function', 'has save');
+  assert.ok(typeof cp.load === 'function', 'has load');
+  assert.ok(typeof cp.clear === 'function', 'has clear');
+  assert.ok(typeof cp.listKeys === 'function', 'has listKeys');
+});
+
+test('createCheckpointer: save and load a value', () => {
+  const cp = createCheckpointer();
+  cp.save('cursor', 42);
+  assert.equal(cp.load('cursor'), 42);
+});
+
+test('createCheckpointer: load returns undefined for unknown key', () => {
+  const cp = createCheckpointer();
+  assert.equal(cp.load('missing'), undefined);
+});
+
+test('createCheckpointer: clear removes a key', () => {
+  const cp = createCheckpointer();
+  cp.save('key', 'value');
+  cp.clear('key');
+  assert.equal(cp.load('key'), undefined);
+});
+
+test('createCheckpointer: listKeys returns all saved keys', () => {
+  const cp = createCheckpointer();
+  cp.save('a', 1);
+  cp.save('b', 2);
+  cp.save('c', 3);
+  const keys = cp.listKeys();
+  assert.deepEqual(keys.sort(), ['a', 'b', 'c']);
+});
+
+test('createCheckpointer: listKeys excludes cleared keys', () => {
+  const cp = createCheckpointer();
+  cp.save('keep', 1);
+  cp.save('remove', 2);
+  cp.clear('remove');
+  assert.deepEqual(cp.listKeys(), ['keep']);
+});
+
+test('createCheckpointer: save overwrites existing value', () => {
+  const cp = createCheckpointer();
+  cp.save('seq', 1);
+  cp.save('seq', 99);
+  assert.equal(cp.load('seq'), 99);
+});
+
+test('createCheckpointer: accepts external Map storage', () => {
+  const storage = new Map([['existing', 'data']]);
+  const cp = createCheckpointer(storage);
+  assert.equal(cp.load('existing'), 'data');
+  cp.save('new', 'value');
+  assert.equal(storage.get('new'), 'value');
+});

package/tests/audit-controller.test.js

@@ -0,0 +1,227 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createAuditController, createEventPoller } from '../src/audit-controller.js';
+
+// ─── createAuditController shape ─────────────────────────────────────────────
+
+test('createAuditController returns controller with log, query, getStream, getMetrics methods', () => {
+  const controller = createAuditController();
+  assert.ok(typeof controller.log === 'function', 'has log method');
+  assert.ok(typeof controller.query === 'function', 'has query method');
+  assert.ok(typeof controller.getStream === 'function', 'has getStream method');
+  assert.ok(typeof controller.getMetrics === 'function', 'has getMetrics method');
+});
+
+// ─── log ─────────────────────────────────────────────────────────────────────
+
+test('log records an audit event with org, actor, action, resource, timestamp', () => {
+  const controller = createAuditController();
+  const event = controller.log({
+    org: 'acme',
+    actor: 'alice',
+    action: 'repository.create',
+    resource: { kind: 'Repository', name: 'my-repo' },
+  });
+  assert.equal(event.org, 'acme');
+  assert.equal(event.actor, 'alice');
+  assert.equal(event.action, 'repository.create');
+  assert.deepEqual(event.resource, { kind: 'Repository', name: 'my-repo' });
+  assert.ok(typeof event.timestamp === 'string', 'timestamp is a string');
+  assert.ok(new Date(event.timestamp).getTime() > 0, 'timestamp is a valid ISO date');
+});
+
+test('log generates sequential event IDs', () => {
+  const controller = createAuditController();
+  const e1 = controller.log({ org: 'acme', actor: 'alice', action: 'repo.create', resource: {} });
+  const e2 = controller.log({ org: 'acme', actor: 'alice', action: 'repo.delete', resource: {} });
+  const e3 = controller.log({ org: 'acme', actor: 'bob',   action: 'user.create', resource: {} });
+  assert.ok(typeof e1.id === 'number', 'id is numeric');
+  assert.ok(e2.id > e1.id, 'e2.id > e1.id');
+  assert.ok(e3.id > e2.id, 'e3.id > e2.id');
+  assert.equal(e2.id - e1.id, 1, 'IDs are strictly sequential');
+  assert.equal(e3.id - e2.id, 1, 'IDs are strictly sequential');
+});
+
+test('log rejects missing org', () => {
+  const controller = createAuditController();
+  assert.throws(
+    () => controller.log({ actor: 'alice', action: 'repo.create', resource: {} }),
+    /org/i,
+    'throws when org is missing'
+  );
+});
+
+test('log rejects missing action', () => {
+  const controller = createAuditController();
+  assert.throws(
+    () => controller.log({ org: 'acme', actor: 'alice', resource: {} }),
+    /action/i,
+    'throws when action is missing'
+  );
+});
+
+// ─── query ────────────────────────────────────────────────────────────────────
+
+test('query returns events filtered by org', () => {
+  const controller = createAuditController();
+  controller.log({ org: 'acme', actor: 'alice', action: 'repo.create', resource: {} });
+  controller.log({ org: 'globex', actor: 'bob', action: 'repo.create', resource: {} });
+  controller.log({ org: 'acme', actor: 'carol', action: 'user.invite', resource: {} });
+
+  const result = controller.query({ org: 'acme' });
+  assert.equal(result.events.length, 2, 'returns only acme events');
+  assert.ok(result.events.every(e => e.org === 'acme'), 'all events belong to acme');
+});
+
+test('query returns events filtered by action', () => {
+  const controller = createAuditController();
+  controller.log({ org: 'acme', actor: 'alice', action: 'repo.create', resource: {} });
+  controller.log({ org: 'acme', actor: 'bob',   action: 'user.invite', resource: {} });
+  controller.log({ org: 'acme', actor: 'carol', action: 'repo.create', resource: {} });
+
+  const result = controller.query({ org: 'acme', action: 'repo.create' });
+  assert.equal(result.events.length, 2, 'returns only repo.create events');
+  assert.ok(result.events.every(e => e.action === 'repo.create'), 'all events have action repo.create');
+});
+
+test('query returns events filtered by time range (since/until)', () => {
+  const controller = createAuditController();
+
+  const t0 = new Date('2026-01-01T00:00:00Z');
+  const t1 = new Date('2026-01-02T00:00:00Z');
+  const t2 = new Date('2026-01-03T00:00:00Z');
+  const t3 = new Date('2026-01-04T00:00:00Z');
+
+  controller.log({ org: 'acme', actor: 'alice', action: 'a', resource: {}, timestamp: t0.toISOString() });
+  controller.log({ org: 'acme', actor: 'alice', action: 'b', resource: {}, timestamp: t1.toISOString() });
+  controller.log({ org: 'acme', actor: 'alice', action: 'c', resource: {}, timestamp: t2.toISOString() });
+  controller.log({ org: 'acme', actor: 'alice', action: 'd', resource: {}, timestamp: t3.toISOString() });
+
+  const result = controller.query({ org: 'acme', since: t1.toISOString(), until: t2.toISOString() });
+  assert.equal(result.events.length, 2, 'returns events within [since, until] inclusive');
+  assert.ok(result.events.some(e => e.action === 'b'), 'includes event at since boundary');
+  assert.ok(result.events.some(e => e.action === 'c'), 'includes event at until boundary');
+});
+
+test('query supports pagination (limit, offset)', () => {
+  const controller = createAuditController();
+  for (let i = 0; i < 10; i++) {
+    controller.log({ org: 'acme', actor: 'alice', action: `action-${i}`, resource: {} });
+  }
+  const page1 = controller.query({ org: 'acme', limit: 3, offset: 0 });
+  const page2 = controller.query({ org: 'acme', limit: 3, offset: 3 });
+
+  assert.equal(page1.events.length, 3, 'page1 has 3 events');
+  assert.equal(page2.events.length, 3, 'page2 has 3 events');
+  // IDs should be different between pages
+  const page1Ids = new Set(page1.events.map(e => e.id));
+  const page2Ids = new Set(page2.events.map(e => e.id));
+  for (const id of page2Ids) assert.ok(!page1Ids.has(id), 'page2 events are distinct from page1');
+});
+
+test('query returns events in reverse chronological order', () => {
+  const controller = createAuditController();
+  controller.log({ org: 'acme', actor: 'alice', action: 'a', resource: {}, timestamp: '2026-01-01T00:00:00Z' });
+  controller.log({ org: 'acme', actor: 'alice', action: 'b', resource: {}, timestamp: '2026-01-02T00:00:00Z' });
+  controller.log({ org: 'acme', actor: 'alice', action: 'c', resource: {}, timestamp: '2026-01-03T00:00:00Z' });
+
+  const result = controller.query({ org: 'acme' });
+  const timestamps = result.events.map(e => new Date(e.timestamp).getTime());
+  for (let i = 1; i < timestamps.length; i++) {
+    assert.ok(timestamps[i - 1] >= timestamps[i], `event[${i - 1}] should be >= event[${i}] (desc order)`);
+  }
+});
+
+// ─── getStream ────────────────────────────────────────────────────────────────
+
+test('getStream returns events after a sequence number (for replay)', () => {
+  const controller = createAuditController();
+  const e1 = controller.log({ org: 'acme', actor: 'alice', action: 'a', resource: {} });
+  const e2 = controller.log({ org: 'acme', actor: 'alice', action: 'b', resource: {} });
+  const e3 = controller.log({ org: 'acme', actor: 'alice', action: 'c', resource: {} });
+
+  const stream = controller.getStream({ org: 'acme', afterSeq: e1.id });
+  assert.ok(Array.isArray(stream.events), 'returns array of events');
+  assert.equal(stream.events.length, 2, 'returns 2 events after seq e1');
+  assert.ok(stream.events.every(e => e.id > e1.id), 'all returned events have id > afterSeq');
+  assert.ok(stream.events.some(e => e.id === e2.id), 'includes e2');
+  assert.ok(stream.events.some(e => e.id === e3.id), 'includes e3');
+});
+
+test('getStream returns empty array when no new events', () => {
+  const controller = createAuditController();
+  const e1 = controller.log({ org: 'acme', actor: 'alice', action: 'a', resource: {} });
+
+  const stream = controller.getStream({ org: 'acme', afterSeq: e1.id });
+  assert.equal(stream.events.length, 0, 'returns empty array when no new events');
+  assert.ok(Array.isArray(stream.events), 'events is still an array');
+});
+
+// ─── createEventPoller ────────────────────────────────────────────────────────
+
+test('createEventPoller returns poller with poll method and backoff state', () => {
+  const controller = createAuditController();
+  const poller = createEventPoller({ controller, org: 'acme' });
+  assert.ok(typeof poller.poll === 'function', 'has poll method');
+  assert.ok(typeof poller.getBackoff === 'function', 'has getBackoff method');
+  assert.ok(typeof poller.reset === 'function', 'has reset method');
+});
+
+test('poll increases backoff interval when no new events (1s, 2s, 4s... max 30s)', () => {
+  const controller = createAuditController();
+  const poller = createEventPoller({ controller, org: 'acme', initialBackoff: 1000, maxBackoff: 30000 });
+
+  // No events exist — each poll should grow backoff
+  assert.equal(poller.getBackoff(), 1000, 'initial backoff is 1s');
+  poller.poll();
+  assert.equal(poller.getBackoff(), 2000, 'after 1 empty poll: 2s');
+  poller.poll();
+  assert.equal(poller.getBackoff(), 4000, 'after 2 empty polls: 4s');
+  poller.poll();
+  assert.equal(poller.getBackoff(), 8000, 'after 3 empty polls: 8s');
+  poller.poll();
+  assert.equal(poller.getBackoff(), 16000, 'after 4 empty polls: 16s');
+  poller.poll();
+  assert.equal(poller.getBackoff(), 30000, 'capped at maxBackoff 30s');
+  poller.poll();
+  assert.equal(poller.getBackoff(), 30000, 'stays at maxBackoff');
+});
+
+test('poll resets backoff when new events arrive', () => {
+  const controller = createAuditController();
+  const poller = createEventPoller({ controller, org: 'acme', initialBackoff: 1000, maxBackoff: 30000 });
+
+  // First poll: no events — backoff grows
+  poller.poll();
+  assert.equal(poller.getBackoff(), 2000, 'backoff grew to 2s');
+
+  // Add a new event
+  controller.log({ org: 'acme', actor: 'alice', action: 'repo.create', resource: {} });
+
+  // Poll again — should see the event and reset backoff
+  const result = poller.poll();
+  assert.ok(result.events.length > 0, 'poll returns new events');
+  assert.equal(poller.getBackoff(), 1000, 'backoff resets to initial after receiving events');
+});
+
+// ─── getMetrics ───────────────────────────────────────────────────────────────
+
+test('getMetrics returns aggregate counts (events by action, by org, by hour)', () => {
+  const controller = createAuditController();
+  controller.log({ org: 'acme',   actor: 'alice', action: 'repo.create', resource: {}, timestamp: '2026-05-13T10:00:00Z' });
+  controller.log({ org: 'acme',   actor: 'alice', action: 'repo.create', resource: {}, timestamp: '2026-05-13T10:30:00Z' });
+  controller.log({ org: 'acme',   actor: 'bob',   action: 'user.invite',  resource: {}, timestamp: '2026-05-13T11:00:00Z' });
+  controller.log({ org: 'globex', actor: 'carol', action: 'repo.create', resource: {}, timestamp: '2026-05-13T10:15:00Z' });
+
+  const metrics = controller.getMetrics({ org: 'acme' });
+
+  assert.ok(typeof metrics.byAction === 'object', 'has byAction');
+  assert.ok(typeof metrics.byOrg === 'object', 'has byOrg');
+  assert.ok(typeof metrics.byHour === 'object', 'has byHour');
+  assert.equal(metrics.byAction['repo.create'], 2, 'acme has 2 repo.create events');
+  assert.equal(metrics.byAction['user.invite'], 1, 'acme has 1 user.invite event');
+  assert.equal(metrics.byOrg['acme'], 3, 'acme org total is 3');
+  // byHour keys are ISO hour strings (e.g. "2026-05-13T10")
+  assert.ok(metrics.byHour['2026-05-13T10'] >= 2, 'at least 2 events in 2026-05-13T10 hour');
+  assert.ok(metrics.byHour['2026-05-13T11'] >= 1, 'at least 1 event in 2026-05-13T11 hour');
+});