Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.5 KB
Raw Blame
/**
 * Wire validation pins for serve-delegated sync (sync-ipc.ts).
 *
 * The validator is the trust boundary between the unix socket and the serve
 * process's SyncOpts: unknown keys MUST reject (that is the only thing keeping
 * repoPath / skipLock / lockId / concurrency unreachable from the wire), and
 * timeoutSeconds is the bounded-job guarantee.
 */

import { describe, expect, test } from 'bun:test';
import {
  DELEGATED_SYNC_OPTION_FIELDS,
  DELEGATED_SYNC_TIMEOUT_MAX_SECONDS,
  WIRE_PAGES_AFFECTED_MAX,
  isSyncStartRegistration,
  toWireSyncResult,
  validateDelegatedSyncOptions,
} from '../../src/core/context/sync-ipc.ts';
import type { SyncResult } from '../../src/commands/sync.ts';

describe('validateDelegatedSyncOptions', () => {
  test('accepts the full allowlisted set and returns a fresh object', () => {
    const raw = {
      sourceId: 'notes',
      dryRun: true,
      full: false,
      noPull: true,
      noEmbed: false,
      noExtract: false,
      noSchemaPack: true,
      skipFailed: false,
      retryFailed: false,
      includeGitignored: true,
      timeoutSeconds: 3600,
    };
    const v = validateDelegatedSyncOptions(raw);
    expect(v.ok).toBe(true);
    if (!v.ok) throw new Error('unreachable');
    expect(v.options).toEqual(raw);
    expect(v.options).not.toBe(raw as never);
  });

  // #6712 PR 1: explicitProcessing is still validated by shape (an older CLI sends it) but dropped: the cursor's opt-outs are inherited.
  test('#6317: the managed catch-up fields validate by shape (lanes 1..16, explicitProcessing from the three processing keys, accepted and ignored)', () => {
    const ok = validateDelegatedSyncOptions({ noBulk: true, lanes: 4, explicitProcessing: ['noEmbed', 'noExtract'], timeoutSeconds: 60 } as never);
    expect(ok.ok).toBe(true);
    if (!ok.ok) throw new Error('unreachable');
    expect(ok.options).toEqual({ noBulk: true, lanes: 4, timeoutSeconds: 60 });
    for (const lanes of [0, 17, 1.5, '4']) expect(validateDelegatedSyncOptions({ lanes, timeoutSeconds: 60 })).toEqual({ ok: false, error: 'invalid_options:lanes' });
    for (const explicitProcessing of ['noEmbed', ['repoPath'], [1], ['noEmbed', 'noEmbed', 'noExtract', 'noSchemaPack']]) {
      expect(validateDelegatedSyncOptions({ explicitProcessing, timeoutSeconds: 60 })).toEqual({ ok: false, error: 'invalid_options:explicitProcessing' });
    }
  });

  test('#6317: a registration rides sync_start only in the agreed shape (uuid id, 64-hex credential, lane cli)', () => {
    const id = '11111111-2222-4333-8444-555555555555', credential = 'a'.repeat(64);
    expect(isSyncStartRegistration({ id, credential, lane: 'cli' })).toBe(true);
    expect(isSyncStartRegistration({ id, credential, lane: 'stdio' })).toBe(false);
    expect(isSyncStartRegistration({ id, credential: 'short', lane: 'cli' })).toBe(false);
    expect(isSyncStartRegistration({ id: 'not-a-uuid', credential, lane: 'cli' })).toBe(false);
    expect(isSyncStartRegistration({ id, credential, lane: 'cli', extra: 1 })).toBe(false);
    expect(isSyncStartRegistration(null)).toBe(false);
  });

  test('minimal valid payload: only timeoutSeconds', () => {
    const v = validateDelegatedSyncOptions({ timeoutSeconds: 60 });
    expect(v.ok).toBe(true);
  });

  test.each([
    ['repoPath', { repoPath: '/tmp/evil', timeoutSeconds: 60 }],
    ['skipLock', { skipLock: true, timeoutSeconds: 60 }],
    ['lockId', { lockId: 'gbrain-cycle', timeoutSeconds: 60 }],
    ['concurrency', { concurrency: 8, timeoutSeconds: 60 }],
    ['srcSubpath', { srcSubpath: '../escape', timeoutSeconds: 60 }],
    ['exclude', { exclude: ['*'], timeoutSeconds: 60 }],
    ['signal', { signal: {}, timeoutSeconds: 60 }],
    ['onProgress', { onProgress: () => {}, timeoutSeconds: 60 }],
  ])('rejects unknown/smuggled key %s fail-closed', (key, raw) => {
    const v = validateDelegatedSyncOptions(raw);
    expect(v.ok).toBe(false);
    if (v.ok) throw new Error('unreachable');
    expect(v.error).toBe(`invalid_options:${key}`);
  });

  test.each([
    ['non-object', null],
    ['array', []],
    ['string', 'sync'],
  ])('rejects a %s payload', (_label, raw) => {
    const v = validateDelegatedSyncOptions(raw);
    expect(v.ok).toBe(false);
  });

  test('rejects wrong-typed allowlisted fields', () => {
    expect(validateDelegatedSyncOptions({ dryRun: 'yes', timeoutSeconds: 60 }).ok).toBe(false);
    expect(validateDelegatedSyncOptions({ sourceId: 42, timeoutSeconds: 60 }).ok).toBe(false);
  });

  test('timeoutSeconds is required, integer, non-negative; 0 means no server timer', () => {
    expect(validateDelegatedSyncOptions({})).toEqual({
      ok: false,
      error: 'invalid_options:timeoutSeconds',
    });
    expect(validateDelegatedSyncOptions({ timeoutSeconds: -1 }).ok).toBe(false);
    expect(validateDelegatedSyncOptions({ timeoutSeconds: 1.5 }).ok).toBe(false);
    const zero = validateDelegatedSyncOptions({ timeoutSeconds: 0 });
    expect(zero.ok).toBe(true);
    if (zero.ok) expect(zero.options.timeoutSeconds).toBe(0);
  });

  test('timeoutSeconds clamps to the 24h ceiling', () => {
    const v = validateDelegatedSyncOptions({ timeoutSeconds: 999_999_999 });
    expect(v.ok).toBe(true);
    if (v.ok) expect(v.options.timeoutSeconds).toBe(DELEGATED_SYNC_TIMEOUT_MAX_SECONDS);
  });

  test('sourceId must satisfy the canonical shape', () => {
    expect(validateDelegatedSyncOptions({ sourceId: 'UPPER', timeoutSeconds: 60 })).toEqual({
      ok: false,
      error: 'invalid_options:sourceId',
    });
    expect(validateDelegatedSyncOptions({ sourceId: '-lead', timeoutSeconds: 60 }).ok).toBe(false);
    expect(validateDelegatedSyncOptions({ sourceId: 'ok-source', timeoutSeconds: 60 }).ok).toBe(true);
  });

  test('#6696 (A5): origin carries the admission origin and rejects anything else', () => {
    expect(validateDelegatedSyncOptions({ timeoutSeconds: 0, origin: 'interactive' })).toEqual({ ok: true, options: { timeoutSeconds: 0, origin: 'interactive' } });
    expect(validateDelegatedSyncOptions({ timeoutSeconds: 0, origin: 'background' })).toMatchObject({ ok: true });
    expect(validateDelegatedSyncOptions({ timeoutSeconds: 0, origin: 'admin' })).toEqual({ ok: false, error: 'invalid_options:origin' });
    expect(validateDelegatedSyncOptions({ timeoutSeconds: 0, origin: true })).toEqual({ ok: false, error: 'invalid_options:origin' });
  });

  test('field table and options interface stay in lockstep', () => {
    // The validator iterates the table; if a field is added to the interface
    // but not the table it becomes unreachable from the wire — this pin makes
    // that drift loud.
    expect(Object.keys(DELEGATED_SYNC_OPTION_FIELDS).sort()).toEqual([
      'dryRun',
      'embedDeferred',
      'full',
      'includeGitignored',
      'lanes',
      'noBulk',
      'noEmbed',
      'noExtract',
      'noPull',
      'noSchemaPack',
      'origin',
      'retryFailed',
      'skipFailed',
      'sourceId',
      'timeoutSeconds',
    ]);
    // #6712 PR 2: a retired field is not in the table (a newer client never sends it); its window still accepts it.
    expect(Object.keys(DELEGATED_SYNC_OPTION_FIELDS)).not.toContain('explicitProcessing');
    expect(validateDelegatedSyncOptions({ explicitProcessing: ['noEmbed'], timeoutSeconds: 0 })).toEqual({ ok: true, options: { timeoutSeconds: 0 }, ignored: ['explicitProcessing'] });
  });
});

describe('toWireSyncResult', () => {
  const base: SyncResult = {
    status: 'synced',
    fromCommit: 'aaa',
    toCommit: 'bbb',
    added: 2,
    modified: 1,
    deleted: 0,
    renamed: 0,
    chunksCreated: 3,
    embedded: 0,
    pagesAffected: [],
  };

  test('passes small results through with an exact total', () => {
    const r = toWireSyncResult({ ...base, pagesAffected: ['a', 'b'] });
    expect(r.pagesAffected).toEqual(['a', 'b']);
    expect(r.pagesAffectedTotal).toBe(2);
  });

  test('truncates pagesAffected past the cap and reports the true total', () => {
    const pages = Array.from({ length: WIRE_PAGES_AFFECTED_MAX + 1 }, (_, i) => `p/${i}`);
    const r = toWireSyncResult({ ...base, pagesAffected: pages });
    expect(r.pagesAffected).toHaveLength(WIRE_PAGES_AFFECTED_MAX);
    expect(r.pagesAffectedTotal).toBe(WIRE_PAGES_AFFECTED_MAX + 1);
    expect(r.pagesAffected[0]).toBe('p/0');
  });

  test('preserves partial-result fields', () => {
    const r = toWireSyncResult({
      ...base,
      status: 'partial',
      reason: 'timeout',
      filesImported: 7,
      bankedFiles: 7,
    });
    expect(r.status).toBe('partial');
    expect(r.reason).toBe('timeout');
    expect(r.bankedFiles).toBe(7);
  });
});