Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.3 KB
Raw Blame
import { afterEach, describe, expect, test } from 'bun:test';
import { chmodSync, existsSync, linkSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import { nativeExportPublisher, type NativeExportPublisher } from '../src/core/persistence/native-lock.ts';

const roots: string[] = [];
const handles: Array<{ publisher: NativeExportPublisher; handle: object }> = [];
const incomplete = 'GBRAIN EXPORT INCOMPLETE\n';
const marker = '.gbrain-export-status';
function temporary(): string {
  const root = realpathSync(mkdtempSync(join(tmpdir(), 'gbrain-export-native-')));
  roots.push(root);
  return root;
}
async function begin(root: string) {
  const publisher = await nativeExportPublisher();
  const handle = publisher.beginExport(root);
  handles.push({ publisher, handle });
  return { publisher, handle };
}
afterEach(() => {
  for (const { publisher, handle } of handles.splice(0)) publisher.closeExport(handle);
  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
});

describe('native export publication', () => {
  test('creates nested destinations, publishes exact binary bytes, completes and closes twice', async () => {
    const root = join(temporary(), 'new', 'export ünicode');
    const { publisher, handle } = await begin(root);
    expect(readFileSync(join(root, marker), 'utf8')).toBe(incomplete);
    const bytes = Buffer.from([0, 1, 255, 10, 0, 13]);
    publisher.publishExportFile(handle, 'nested/ü.txt', bytes);
    publisher.publishExportFile(handle, 'empty', Buffer.alloc(0));
    expect(readFileSync(join(root, 'nested/ü.txt'))).toEqual(bytes);
    expect(readdirSync(join(root, 'nested'))).toEqual(['ü.txt']);
    publisher.completeExport(handle);
    expect(readFileSync(join(root, marker), 'utf8')).toBe(`${incomplete}COMPLETE\n`);
    expect(() => publisher.publishExportFile(handle, 'later', bytes)).toThrow();
    publisher.closeExport(handle);
    publisher.closeExport(handle);
    expect(() => publisher.completeExport(handle)).toThrow();
  });

  test('reserves the marker exclusively and retains evidence after close', async () => {
    const root = temporary();
    const { publisher, handle } = await begin(root);
    expect(() => publisher.beginExport(root)).toThrow();
    publisher.closeExport(handle);
    expect(() => publisher.beginExport(root)).toThrow();
    expect(readFileSync(join(root, marker), 'utf8')).toBe(incomplete);
  });

  test('never modifies a preexisting marker or a non-directory destination prefix', async () => {
    const root = temporary();
    const publisher = await nativeExportPublisher();
    writeFileSync(join(root, marker), 'operator-owned bytes');
    expect(() => publisher.beginExport(root)).toThrow();
    expect(readFileSync(join(root, marker), 'utf8')).toBe('operator-owned bytes');
    writeFileSync(join(root, 'file'), 'keep');
    expect(() => publisher.beginExport(join(root, 'file', 'child'))).toThrow();
    expect(readFileSync(join(root, 'file'), 'utf8')).toBe('keep');
  });

  test.skipIf(process.platform === 'win32').each(['destination', 'ancestor', 'marker'])('refuses once-only %s replacement before publication', async kind => {
    const base = temporary();
    const root = join(base, 'parent', 'export');
    const { publisher, handle } = await begin(root);
    publisher.publishExportFile(handle, 'first', Buffer.from('first bytes'));
    let retainedRoot = root;
    let retainedMarker = join(root, marker);
    if (kind === 'marker') {
      retainedMarker = join(root, 'old-marker');
      renameSync(join(root, marker), retainedMarker);
      writeFileSync(join(root, marker), 'replacement marker');
    } else {
      const replaced = kind === 'ancestor' ? join(base, 'parent') : root;
      renameSync(replaced, `${replaced}-old`);
      mkdirSync(root, { recursive: true });
      retainedRoot = kind === 'ancestor' ? join(base, 'parent-old', 'export') : `${root}-old`;
      retainedMarker = join(retainedRoot, marker);
    }
    expect(() => publisher.publishExportFile(handle, 'second', Buffer.from('second bytes'))).toThrow();
    expect(() => publisher.completeExport(handle)).toThrow();
    expect(readFileSync(retainedMarker, 'utf8')).toBe(incomplete);
    expect(existsSync(join(retainedRoot, 'second'))).toBe(false);
    expect(existsSync(join(root, 'second'))).toBe(false);
    if (kind === 'marker') expect(readFileSync(join(root, marker), 'utf8')).toBe('replacement marker');
    else expect(readdirSync(root)).toEqual([]);
  });

  test.skipIf(process.platform === 'win32').each(['destination', 'ancestor', 'marker'])('refuses once-only %s replacement immediately before completion', async kind => {
    const base = temporary();
    const root = join(base, 'parent', 'export');
    const { publisher, handle } = await begin(root);
    publisher.publishExportFile(handle, 'first', Buffer.from('first bytes'));
    let retainedMarker: string;
    if (kind === 'marker') {
      retainedMarker = join(root, 'old-marker');
      renameSync(join(root, marker), retainedMarker);
      writeFileSync(join(root, marker), 'replacement marker');
    } else {
      const replaced = kind === 'ancestor' ? join(base, 'parent') : root;
      renameSync(replaced, `${replaced}-old`);
      mkdirSync(root, { recursive: true });
      retainedMarker = join(kind === 'ancestor' ? join(base, 'parent-old', 'export') : `${root}-old`, marker);
    }
    expect(() => publisher.completeExport(handle)).toThrow();
    expect(readFileSync(retainedMarker, 'utf8')).toBe(incomplete);
    if (kind === 'marker') expect(readFileSync(join(root, marker), 'utf8')).toBe('replacement marker');
    else expect(readdirSync(root)).toEqual([]);
    expect(() => publisher.publishExportFile(handle, 'second', Buffer.from('no'))).toThrow();
  });

  test.each(['file', 'directory', 'hardlink'])('never replaces an existing %s', async kind => {
    const root = temporary();
    const leaf = join(root, 'occupied');
    if (kind === 'directory') mkdirSync(leaf);
    else {
      writeFileSync(join(root, 'original'), 'original bytes');
      if (kind === 'hardlink') linkSync(join(root, 'original'), leaf);
      else writeFileSync(leaf, 'original bytes');
    }
    const { publisher, handle } = await begin(root);
    expect(() => publisher.publishExportFile(handle, 'occupied', Buffer.from('replacement'))).toThrow();
    expect(() => publisher.completeExport(handle)).toThrow();
    if (kind !== 'directory') expect(readFileSync(leaf, 'utf8')).toBe('original bytes');
    else expect(readdirSync(leaf)).toEqual([]);
    expect(readdirSync(root).filter(name => name.endsWith('.tmp'))).toEqual([]);
    expect(readFileSync(join(root, marker), 'utf8')).toBe(incomplete);
  });

  test.each(['../escape', '/absolute', 'a//b', 'a/./b', 'a/../b', 'a/', 'a\\b', 'a:b', 'trailing.', 'trailing ', 'NUL', 'COM1.txt', 'LPT²', 'bad\0name', '.gbrain-export-status'])('rejects invalid path %j and poisons completion', async path => {
    const root = temporary();
    const { publisher, handle } = await begin(root);
    expect(() => publisher.publishExportFile(handle, path, Buffer.from('no'))).toThrow();
    expect(() => publisher.completeExport(handle)).toThrow();
    expect(readFileSync(join(root, marker), 'utf8')).toBe(incomplete);
  });

  test('publishes a staged file by path in bounded reads, byte for byte, across several read buffers', async () => {
    const stage = temporary();
    const root = join(temporary(), 'out');
    const bytes = Buffer.alloc(3 * 1024 * 1024 + 7);
    for (let i = 0; i < bytes.length; i++) bytes[i] = (i * 31 + (i >> 11)) & 255;
    writeFileSync(join(stage, 'page.md'), bytes);
    writeFileSync(join(stage, 'empty.md'), '');
    const { publisher, handle } = await begin(root);
    publisher.publishExportFileFrom(handle, 'notes/ü.md', join(stage, 'page.md'));
    publisher.publishExportFileFrom(handle, 'empty.md', join(stage, 'empty.md'));
    publisher.completeExport(handle);
    expect(readFileSync(join(root, 'notes/ü.md')).equals(bytes)).toBe(true);
    expect(readFileSync(join(root, 'empty.md')).length).toBe(0);
    expect(readdirSync(join(root, 'notes'))).toEqual(['ü.md']);
    expect(readFileSync(join(stage, 'page.md')).equals(bytes)).toBe(true);
  });

  test.skipIf(process.platform === 'win32').each(['relative', 'missing', 'directory', 'symlink'])('a %s staged source refuses without a leaf and poisons completion', async kind => {
    const stage = temporary();
    const root = temporary();
    writeFileSync(join(stage, 'real.md'), 'staged bytes');
    mkdirSync(join(stage, 'dir'));
    symlinkSync(join(stage, 'real.md'), join(stage, 'link.md'));
    const source = { relative: 'real.md', missing: join(stage, 'absent.md'), directory: join(stage, 'dir'), symlink: join(stage, 'link.md') }[kind]!;
    const { publisher, handle } = await begin(root);
    expect(() => publisher.publishExportFileFrom(handle, 'page.md', source)).toThrow();
    expect(() => publisher.completeExport(handle)).toThrow();
    expect(readdirSync(root)).toEqual([marker]);
    expect(readFileSync(join(root, marker), 'utf8')).toBe(incomplete);
  });

  test('rejects a nonbuffer without permitting completion', async () => {
    const { publisher, handle } = await begin(temporary());
    expect(() => publisher.publishExportFile(handle, 'file', 'text' as unknown as Buffer)).toThrow();
    expect(() => publisher.completeExport(handle)).toThrow();
  });

  test('incomplete publication arguments poison an identifiable handle', async () => {
    const { publisher, handle } = await begin(temporary());
    expect(() => Reflect.apply(publisher.publishExportFile, publisher, [handle, 'file'])).toThrow();
    expect(() => publisher.completeExport(handle)).toThrow();
  });

  test('refuses filesystem case aliases when the filesystem aliases them', async () => {
    const root = temporary();
    writeFileSync(join(root, 'Taken'), 'existing');
    if (!existsSync(join(root, 'taken'))) return;
    const { publisher, handle } = await begin(root);
    expect(() => publisher.publishExportFile(handle, 'taken', Buffer.from('replacement'))).toThrow();
    expect(readFileSync(join(root, 'Taken'), 'utf8')).toBe('existing');
    expect(() => publisher.completeExport(handle)).toThrow();
  });

  test('rejects foreign objects and keeps export handles separate from lock handles', async () => {
    const { publisher, handle } = await begin(temporary());
    const addon = publisher as NativeExportPublisher & { openLock(path: string): object; close(handle: object): void };
    const lock = addon.openLock(join(temporary(), 'writer.lock'));
    try {
      expect(() => publisher.closeExport({})).toThrow();
      expect(() => publisher.closeExport(lock)).toThrow();
      expect(() => addon.close(handle)).toThrow();
      publisher.completeExport(handle);
    } finally { addon.close(lock); }
  });

  test.each(['destination', 'parent', 'leaf', 'marker'])('refuses a symlink/reparse %s without touching its target', async kind => {
    const root = temporary();
    const outside = temporary();
    writeFileSync(join(outside, 'sentinel'), 'unchanged');
    const publisher = await nativeExportPublisher();
    if (kind === 'destination') {
      symlinkSync(outside, join(root, 'alias'), process.platform === 'win32' ? 'junction' : 'dir');
      expect(() => publisher.beginExport(join(root, 'alias', 'child'))).toThrow();
    } else if (kind === 'marker') {
      symlinkSync(outside, join(root, marker), process.platform === 'win32' ? 'junction' : 'dir');
      expect(() => publisher.beginExport(root)).toThrow();
    } else {
      const { handle } = await begin(root);
      symlinkSync(outside, join(root, 'alias'), process.platform === 'win32' ? 'junction' : 'dir');
      expect(() => publisher.publishExportFile(handle, kind === 'parent' ? 'alias/sentinel' : 'alias', Buffer.from('no'))).toThrow();
      expect(() => publisher.completeExport(handle)).toThrow();
    }
    expect(readdirSync(outside)).toEqual(['sentinel']);
    expect(readFileSync(join(outside, 'sentinel'), 'utf8')).toBe('unchanged');
  });

  test.skipIf(process.platform === 'win32' || process.getuid?.() === 0)('retains incomplete evidence on a real permission failure', async () => {
    const root = temporary();
    const { publisher, handle } = await begin(root);
    mkdirSync(join(root, 'readonly'));
    chmodSync(join(root, 'readonly'), 0o500);
    try {
      expect(() => publisher.publishExportFile(handle, 'readonly/file', Buffer.from('no'))).toThrow();
      expect(() => publisher.completeExport(handle)).toThrow();
      expect(readFileSync(join(root, marker), 'utf8')).toBe(incomplete);
    } finally { chmodSync(join(root, 'readonly'), 0o700); }
  });

  test('competing processes have exactly one marker owner and process exit retains evidence', async () => {
    const root = temporary();
    const fixture = resolve(import.meta.dir, 'fixtures/native-export-process.ts');
    const children = Array.from({ length: 4 }, () => Bun.spawn([process.execPath, '--no-env-file', fixture, root], {
      stdout: 'pipe', stderr: 'pipe', env: { PATH: process.env.PATH, SYSTEMROOT: process.env.SYSTEMROOT, TEMP: process.env.TEMP, TMP: process.env.TMP },
    }));
    const exits = await Promise.all(children.map(child => child.exited));
    expect(exits.filter(code => code === 0)).toHaveLength(1);
    expect(exits.filter(code => code === 2)).toHaveLength(3);
    expect(readFileSync(join(root, marker), 'utf8')).toBe(incomplete);
  });
});