Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { redactTcAddress } from '../lib/tailcatAddress.js';
import { EventEmitter } from 'node:events';
import {
allocateLocalPort,
startForwardProcess,
classifyTailcatRuntimeError,
verifyTunnelReachable,
addPeerViaTailcat,
listTailcatForwards,
attachTailcatForwardsToPeers,
retryTailcatForward,
forgetTailcatForward,
_resetLiveForwardsForTests,
_liveForwardCountForTests,
stopAllForwards,
stopForwardForPeer,
restoreForwards,
} from './tailcatPeer.js';
import { DEFAULT_TAILCAT_LOCAL_PORT, DEFAULT_TAILCAT_REMOTE_PORT } from '../lib/ports.js';
vi.mock('../lib/fileUtils.js', async (original) => ({
...(await original()),
readJSONFile: vi.fn(),
ensureDir: vi.fn().mockResolvedValue(undefined),
atomicWrite: vi.fn().mockResolvedValue(undefined),
}));
import { readJSONFile, atomicWrite } from '../lib/fileUtils.js';
// No installed CLI or package manager: exercise the real shared installation failure.
vi.mock('../lib/commandExists.js', () => ({ commandOutput: vi.fn().mockResolvedValue(null) }));
vi.mock('../lib/processEnv.js', async (original) => ({
...(await original()),
findCommandOnPath: vi.fn().mockReturnValue(null),
}));
const EXAMPLE_TC = 'tcEXAMPLE' + 'A'.repeat(40);
function fakeChild() {
const child = new EventEmitter();
child.killed = false;
child.stderr = new EventEmitter();
child.stdout = new EventEmitter();
child.kill = vi.fn(() => {
child.killed = true;
child.emit('exit', 0, null);
});
return child;
}
describe('tailcatPeer helpers', () => {
beforeEach(() => {
_resetLiveForwardsForTests();
vi.clearAllMocks();
readJSONFile.mockResolvedValue({ version: 1, forwards: [] });
});
afterEach(() => {
_resetLiveForwardsForTests();
vi.useRealTimers();
});
it('surfaces shared installation failure without starting a tunnel', async () => {
const startForward = vi.fn();
await expect(addPeerViaTailcat({ tcAddress: EXAMPLE_TC, startForward })).rejects.toMatchObject({
status: 503, code: 'TAILCAT_MISSING',
});
expect(startForward).not.toHaveBeenCalled();
expect(_liveForwardCountForTests()).toBe(0);
});
it('allocateLocalPort prefers 15555 then walks upward when busy', async () => {
expect(DEFAULT_TAILCAT_LOCAL_PORT).toBe(15555);
expect(DEFAULT_TAILCAT_REMOTE_PORT).toBe(5565);
const isFree = vi.fn(async (port) => port === 15557);
const port = await allocateLocalPort({ preferred: 15555, isFree, limit: 5 });
expect(port).toBe(15557);
expect(isFree).toHaveBeenCalledWith(15555);
expect(isFree).toHaveBeenCalledWith(15556);
expect(isFree).toHaveBeenCalledWith(15557);
});
it('startForwardProcess spawns tailcat forward with local:remote mapping', async () => {
const child = fakeChild();
const spawnFn = vi.fn(() => {
queueMicrotask(() => child.stderr.emit('data', 'forwarding 127.0.0.1:15555 -> remote localhost:5555\n'));
return child;
});
const started = await startForwardProcess({
bin: '/usr/bin/tailcat',
tcAddress: EXAMPLE_TC,
localPort: 15555,
remotePort: 5555,
spawnFn,
readyMs: 200,
probeMs: 5,
isListening: async () => false,
});
expect(started).toBe(child);
expect(spawnFn).toHaveBeenCalledWith(
'/usr/bin/tailcat',
['forward', '--verbose', '--bind=127.0.0.1', EXAMPLE_TC, '15555:5555'],
expect.any(Object)
);
});
it('startForwardProcess rejects when the child exits immediately', async () => {
const child = fakeChild();
const spawnFn = vi.fn(() => {
// Schedule exit after startForwardProcess attaches its listeners.
process.nextTick(() => child.emit('exit', 2, null));
return child;
});
await expect(startForwardProcess({
bin: '/usr/bin/tailcat',
tcAddress: EXAMPLE_TC,
localPort: 15555,
spawnFn,
readyMs: 5_000,
isListening: async () => false,
})).rejects.toThrow(/exited early/);
});
it('times out and kills a process that never confirms its listener', async () => {
vi.useFakeTimers();
const child = fakeChild();
const result = startForwardProcess({ bin: 'tailcat', tcAddress: EXAMPLE_TC,
localPort: 15555, spawnFn: () => child, readyMs: 8000, isListening: async () => false });
const assertion = expect(result).rejects.toThrow('startup timed out');
await vi.advanceTimersByTimeAsync(8000);
await assertion;
expect(child.kill).toHaveBeenCalledWith('SIGTERM');
vi.useRealTimers();
});
it('never exposes capability diagnostics across repeated or split chunks', async () => {
const child = fakeChild();
const result = startForwardProcess({ bin: 'tailcat', tcAddress: EXAMPLE_TC,
localPort: 15555, spawnFn: () => child, isListening: async () => false });
child.stderr.emit('data', EXAMPLE_TC.slice(0, 10));
child.stderr.emit('data', EXAMPLE_TC.slice(10) + EXAMPLE_TC);
child.emit('error', new Error(EXAMPLE_TC));
// The message now carries tailcat's own (redacted) diagnostics, which is the
// whole point — but never the capability itself, however it was chunked.
const failure = await result.catch((err) => err);
expect(failure.message).toContain('tailcat forward process failed');
expect(failure.message).not.toContain('tcEXAMPLE');
});
it('reports a post-startup delivery failure instead of a bound-but-dead "running"', async () => {
const child = fakeChild();
const errors = [];
const logSpy = vi.spyOn(console, 'error').mockImplementation((line) => errors.push(line));
const spawnFn = vi.fn(() => {
queueMicrotask(() => child.stderr.emit('data', 'forwarding 127.0.0.1:15555 -> remote localhost:5555\n'));
return child;
});
await startForwardProcess({
bin: 'tailcat', tcAddress: EXAMPLE_TC, localPort: 15555, remotePort: 5555,
spawnFn, readyMs: 200, probeMs: 5, isListening: async () => false,
});
// Healthy relay churn is not a verdict; only a failed delivery is.
child.stderr.emit('data', 'derp-301: [v1] backoff: 114 msec\n');
expect(child.tailcatRuntimeError).toBeNull();
// Split across chunks, exactly as a real pipe delivers it.
child.stderr.emit('data', 'dial remote port 5555: context');
child.stderr.emit('data', ' deadline exceeded\n');
expect(child.tailcatRuntimeError.message).toContain('dial remote port 5555');
expect(errors.join(' ')).toContain('cannot reach the remote');
logSpy.mockRestore();
});
it('never leaks the capability through a post-startup diagnostic', async () => {
const child = fakeChild();
const spawnFn = vi.fn(() => {
queueMicrotask(() => child.stderr.emit('data', 'forwarding 127.0.0.1:15555 -> remote localhost:5555\n'));
return child;
});
await startForwardProcess({
bin: 'tailcat', tcAddress: EXAMPLE_TC, localPort: 15555, remotePort: 5555,
spawnFn, readyMs: 200, probeMs: 5, isListening: async () => false,
});
child.stderr.emit('data', `dial remote target ${EXAMPLE_TC}: refused\n`);
expect(child.tailcatRuntimeError.message).not.toContain('tcEXAMPLE');
});
it('classifyTailcatRuntimeError ignores relay churn and picks the delivery failure', () => {
expect(classifyTailcatRuntimeError('netcheck: UDP is blocked, trying HTTPS')).toBeNull();
expect(classifyTailcatRuntimeError('derp-301: [v1] backoff: 5 msec')).toBeNull();
expect(classifyTailcatRuntimeError(
'derp-301: [v1] backoff: 5 msec\ndial remote port 5555: context deadline exceeded'
)).toContain('dial remote port 5555: context deadline exceeded');
});
it.each([5555, DEFAULT_TAILCAT_REMOTE_PORT])('adds a peer using the selected remote port %s', async (remotePort) => {
const child = fakeChild();
const addPeerFn = vi.fn(async (data) => ({ id: 'peer-1', ...data }));
const peer = await addPeerViaTailcat({
tcAddress: EXAMPLE_TC,
remotePort,
name: 'sandbox',
ensureInstalled: async () => ({ bin: '/usr/bin/tailcat', installed: false }),
allocatePort: async () => 15555,
startForward: async (options) => { expect(options.remotePort).toBe(remotePort); return child; },
addPeerFn,
primeDerpMap: async () => ({ primed: false }),
persistForwardEntry: async (entry) => { expect(entry.remotePort).toBe(remotePort); },
patchForwardEntry: async (_id, patch) => { expect(patch.remotePort).toBe(remotePort); return {}; },
});
expect(addPeerFn).toHaveBeenCalledWith({
address: '127.0.0.1',
port: 15555,
name: 'sandbox',
auth: undefined,
transport: 'tailcat',
protocol: 'http',
});
expect(peer.transport).toBe('tailcat');
expect(peer.address).toBe('127.0.0.1');
});
});
describe('tailcat lifecycle failure contracts', () => {
beforeEach(() => {
_resetLiveForwardsForTests();
vi.clearAllMocks();
readJSONFile.mockResolvedValue({ version: 1, forwards: [] });
});
afterEach(() => { _resetLiveForwardsForTests(); vi.useRealTimers(); });
function addOptions(child, overrides = {}) {
return {
tcAddress: EXAMPLE_TC,
ensureInstalled: async () => ({ bin: '/example/bin/tailcat' }),
allocatePort: async () => 15555,
startForward: async () => child,
addPeerFn: async (data) => ({ id: 'peer-example', ...data }),
primeDerpMap: async () => ({ primed: false }),
persistForwardEntry: async () => {},
patchForwardEntry: async () => ({}),
...overrides,
};
}
it('rejects stalled startup at the deadline and terminates the process', async () => {
vi.useFakeTimers();
const child = fakeChild();
const pending = startForwardProcess({ bin: 'tailcat', tcAddress: EXAMPLE_TC,
localPort: 15555, spawnFn: () => child, readyMs: 8000, isListening: async () => false });
const failure = expect(pending).rejects.toThrow('startup timed out');
await vi.advanceTimersByTimeAsync(7999);
expect(child.kill).not.toHaveBeenCalled();
await vi.advanceTimersByTimeAsync(1);
await failure;
expect(child.kill).toHaveBeenCalledWith('SIGTERM');
});
it('waits for the correct listener and accepts a readiness line split over chunks', async () => {
const child = fakeChild();
let ready = false;
const pending = startForwardProcess({ bin: 'tailcat', tcAddress: EXAMPLE_TC,
localPort: 15555, remotePort: 5555, spawnFn: () => child, probeMs: 5, isListening: async () => false })
.then(() => { ready = true; });
child.stderr.emit('data', 'forwarding 127.0.0.1:15556 -> remote localhost:5555\n');
await Promise.resolve();
expect(ready).toBe(false);
child.stderr.emit('data', 'forwarding 127.0.0.1:15555 -> ');
child.stderr.emit('data', 'remote localhost:5555\n');
await pending;
expect(ready).toBe(true);
});
it('never includes split or repeated capability diagnostics in startup errors', async () => {
const child = fakeChild();
const pending = startForwardProcess({ bin: 'tailcat', tcAddress: EXAMPLE_TC,
localPort: 15555, spawnFn: () => child, isListening: async () => false });
child.stderr.emit('data', EXAMPLE_TC.slice(0, 16));
child.stderr.emit('data', EXAMPLE_TC.slice(16) + EXAMPLE_TC + EXAMPLE_TC);
child.emit('exit', 1, null);
await expect(pending).rejects.toThrow('tailcat forward exited early (code=1, signal=null)');
await pending.catch((error) => expect(error.message).not.toContain('tcEXAMPLE'));
});
it('rolls back the peer and child if restart metadata cannot be saved', async () => {
const child = fakeChild();
const removePeerFn = vi.fn().mockResolvedValue(undefined);
await expect(addPeerViaTailcat(addOptions(child, {
patchForwardEntry: async () => { throw new Error('disk full'); }, removePeerFn,
}))).rejects.toMatchObject({ code: 'TAILCAT_PERSIST_FAILED' });
expect(removePeerFn).toHaveBeenCalledWith('peer-example', { stopTransport: false });
expect(child.killed).toBe(true);
expect(_liveForwardCountForTests()).toBe(0);
});
it('terminates the forward when peer registration fails', async () => {
const child = fakeChild();
await expect(addPeerViaTailcat(addOptions(child, {
addPeerFn: async () => { throw new Error('peer write failed'); },
}))).rejects.toThrow('peer write failed');
expect(child.killed).toBe(true);
});
it('refuses to register a peer the tunnel cannot actually reach', async () => {
const child = fakeChild();
child.tailcatRuntimeError = { message: 'dial remote port 5555: context deadline exceeded', at: 'now' };
const addPeerFn = vi.fn();
const saved = [];
// tailcat's own line is the cause; ours would only say the request failed.
await expect(addPeerViaTailcat(addOptions(child, {
addPeerFn,
patchForwardEntry: async (_id, patch) => { saved.push(patch); return {}; },
verifyTunnel: async () => 'fetch failed',
}))).rejects.toMatchObject({
code: 'TAILCAT_TUNNEL_UNREACHABLE',
status: 502,
message: expect.stringContaining('dial remote port 5555: context deadline exceeded'),
});
// A forward whose tunnel is dead must not leave a peer behind that will
// never answer — and the entry stays retryable without re-pasting the tc address.
expect(addPeerFn).not.toHaveBeenCalled();
expect(child.killed).toBe(true);
expect(_liveForwardCountForTests()).toBe(0);
expect(saved.at(-1)).toMatchObject({ status: 'failed' });
});
it('passes the verification through when the tunnel answers', async () => {
const child = fakeChild();
const verifyTunnel = vi.fn(async () => null);
const peer = await addPeerViaTailcat(addOptions(child, { verifyTunnel, protocol: 'https' }));
expect(peer.id).toBe('peer-example');
expect(verifyTunnel).toHaveBeenCalledWith({ localPort: 15555, protocol: 'https', auth: null });
});
it('stops children on shutdown while preserving their restart metadata', async () => {
const child = fakeChild();
await addPeerViaTailcat(addOptions(child));
stopAllForwards();
expect(child.killed).toBe(true);
expect(_liveForwardCountForTests()).toBe(0);
expect(atomicWrite).not.toHaveBeenCalled();
await expect(addPeerViaTailcat(addOptions(fakeChild()))).rejects.toThrow('shutting down');
});
it('restores only mappings that still belong to existing managed peers, and retires them on removal', async () => {
// Pre-retry entries carried no id/status, so restore must still recognize them.
const entry = { peerId: 'peer-example', tcAddress: EXAMPLE_TC, localPort: 15555, remotePort: 5555 };
readJSONFile.mockResolvedValue({ version: 1, forwards: [entry, { ...entry, peerId: 'deleted-peer' }] });
const child = fakeChild();
const startForward = vi.fn().mockResolvedValue(child);
const getPeersFn = async () => [{ id: 'peer-example', transport: 'tailcat', address: '127.0.0.1', port: 15555 }];
const options = {
ensureInstalled: async () => ({ bin: 'tailcat' }),
primeDerpMap: async () => ({ primed: false }),
startForward,
getPeersFn,
};
await expect(restoreForwards(options)).resolves.toEqual({ restored: 1 });
await expect(restoreForwards(options)).resolves.toEqual({ restored: 0 });
expect(startForward).toHaveBeenCalledTimes(1);
await stopForwardForPeer('peer-example');
expect(child.killed).toBe(true);
// Removing the peer drops only its own mapping; the stale one stays put.
const [, written] = atomicWrite.mock.calls.at(-1);
expect(written.version).toBe(1);
expect(written.forwards).toHaveLength(1);
expect(written.forwards[0]).toMatchObject({ peerId: 'deleted-peer', tcAddress: EXAMPLE_TC });
});
it('records why a boot-time restore failed so the retry surface can show it', async () => {
const entry = { id: 'fwd_1', peerId: 'peer-example', tcAddress: EXAMPLE_TC, localPort: 15555, remotePort: 5555 };
readJSONFile.mockResolvedValue({ version: 1, forwards: [entry] });
await expect(restoreForwards({
ensureInstalled: async () => ({ bin: 'tailcat' }),
primeDerpMap: async () => ({ primed: false }),
startForward: async () => { throw new Error(`could not dial ${EXAMPLE_TC}`); },
getPeersFn: async () => [{ id: 'peer-example', transport: 'tailcat', address: '127.0.0.1', port: 15555 }],
})).resolves.toEqual({ restored: 0 });
const [, written] = atomicWrite.mock.calls.at(-1);
expect(written.forwards[0]).toMatchObject({ id: 'fwd_1', status: 'failed' });
expect(written.forwards[0].lastError).toContain('could not dial');
expect(written.forwards[0].lastError).not.toContain('tcEXAMPLE');
});
});
describe('saved tailcat forwards', () => {
beforeEach(() => {
_resetLiveForwardsForTests();
vi.clearAllMocks();
readJSONFile.mockResolvedValue({ version: 1, forwards: [] });
});
afterEach(() => { _resetLiveForwardsForTests(); });
it('saves the capability before anything can fail, so a broken add stays retryable', async () => {
const saved = [];
await expect(addPeerViaTailcat({
tcAddress: EXAMPLE_TC,
name: 'sandbox',
ensureInstalled: async () => { throw new Error('tailcat is not installed'); },
persistForwardEntry: async (entry) => { saved.push(entry); },
patchForwardEntry: async () => ({}),
})).rejects.toThrow('tailcat is not installed');
expect(saved).toHaveLength(1);
expect(saved[0]).toMatchObject({ tcAddress: EXAMPLE_TC, name: 'sandbox', status: 'pending', peerId: null });
});
it('never lets the capability out through the list endpoint', async () => {
readJSONFile.mockResolvedValue({ version: 1, forwards: [{
id: 'fwd_1', peerId: 'peer-1', tcAddress: EXAMPLE_TC, localPort: 15555, remotePort: 5555,
name: 'sandbox', protocol: 'https', auth: { username: 'u', password: 'p' },
status: 'failed', lastError: 'tailcat listener startup timed out', createdAt: '2026-01-01T00:00:00.000Z',
}] });
const [row] = await listTailcatForwards();
expect(row).toMatchObject({
id: 'fwd_1', peerId: 'peer-1', localPort: 15555, protocol: 'https',
hasAuth: true, status: 'failed', live: false,
});
expect(row.tcAddress).toBe(redactTcAddress(EXAMPLE_TC));
expect(JSON.stringify(row)).not.toContain(EXAMPLE_TC);
// The stored Basic credential is a secret too — presence only, never a value.
expect(JSON.stringify(row)).not.toContain('password');
});
it('attaches the redacted forward onto a tailcat peer payload for the peer card', async () => {
readJSONFile.mockResolvedValue({ version: 1, forwards: [{
id: 'fwd_1', peerId: 'peer-1', tcAddress: EXAMPLE_TC, localPort: 15555, remotePort: 5555,
name: 'sandbox', protocol: 'http', auth: null,
status: 'active', lastError: null, createdAt: '2026-01-01T00:00:00.000Z',
}] });
const peers = [
{ id: 'peer-1', name: 'sandbox', transport: 'tailcat', address: '127.0.0.1', port: 15555 },
{ id: 'peer-2', name: 'classic', address: '10.0.0.2', port: 5555 },
];
const enriched = await attachTailcatForwardsToPeers(peers);
expect(enriched[0].tailcatForward).toMatchObject({
id: 'fwd_1', peerId: 'peer-1', localPort: 15555, status: 'active', live: false,
});
expect(JSON.stringify(enriched[0].tailcatForward)).not.toContain(EXAMPLE_TC);
expect(enriched[1].tailcatForward).toBeUndefined();
});
it('separates a bound listener from a tunnel that cannot carry a request', async () => {
const child = fakeChild();
const saved = [];
await addPeerViaTailcat({
tcAddress: EXAMPLE_TC,
name: 'sandbox',
ensureInstalled: async () => ({ bin: '/example/bin/tailcat' }),
primeDerpMap: async () => null,
allocatePort: async () => 15555,
startForward: async () => child,
addPeerFn: async (data) => ({ id: 'peer-1', ...data }),
persistForwardEntry: async (entry) => { saved.push(entry); },
patchForwardEntry: async (id, patch) => ({ ...saved[0], ...patch, id }),
});
readJSONFile.mockResolvedValue({ version: 1, forwards: [{
...saved[0], peerId: 'peer-1', localPort: 15555, status: 'active',
}] });
// Bound and tracked: the row reads exactly as the operator's did — green.
const [healthy] = await listTailcatForwards();
expect(healthy).toMatchObject({ live: true, status: 'active', tunnelError: null });
const at = new Date().toISOString();
child.tailcatRuntimeError = { message: 'dial remote port 5555: context deadline exceeded', at };
const [broken] = await listTailcatForwards();
expect(broken).toMatchObject({
live: true, status: 'active', tunnelErrorAt: at,
tunnelError: 'dial remote port 5555: context deadline exceeded',
});
// A forward that started working again goes quiet, so the failure ages out
// rather than latching "no route" on a tunnel that now delivers.
child.tailcatRuntimeError = { message: 'dial remote port 5555: context deadline exceeded',
at: new Date(Date.now() - 6 * 60 * 1000).toISOString() };
const [recovered] = await listTailcatForwards();
expect(recovered).toMatchObject({ live: true, tunnelError: null, tunnelErrorAt: null });
});
it('retries from the stored address without the operator supplying it again', async () => {
readJSONFile.mockResolvedValue({ version: 1, forwards: [{
id: 'fwd_1', peerId: null, tcAddress: EXAMPLE_TC, localPort: null, remotePort: 5555,
name: 'sandbox', protocol: 'https', status: 'failed', lastError: 'startup timed out',
}] });
const child = fakeChild();
const startForward = vi.fn().mockResolvedValue(child);
const addPeerFn = vi.fn(async (data) => ({ id: 'peer-9', ...data }));
const patches = [];
const peer = await retryTailcatForward('fwd_1', {
ensureInstalled: async () => ({ bin: '/example/bin/tailcat' }),
primeDerpMap: async () => ({ primed: true }),
allocatePort: async () => 15556,
startForward,
addPeerFn,
patchForwardEntry: async (id, patch) => { patches.push([id, patch]); return { id, ...patch }; },
getPeersFn: async () => [],
});
expect(startForward).toHaveBeenCalledWith(expect.objectContaining({ tcAddress: EXAMPLE_TC, localPort: 15556, remotePort: 5555 }));
expect(addPeerFn).toHaveBeenCalledWith(expect.objectContaining({
address: '127.0.0.1', port: 15556, name: 'sandbox', transport: 'tailcat', protocol: 'https',
}));
expect(peer.id).toBe('peer-9');
expect(patches).toEqual([['fwd_1', expect.objectContaining({ peerId: 'peer-9', status: 'active', lastError: null })]]);
});
it('waits for process exit across concurrent retries, escalating even after a prior signal', async () => {
vi.useFakeTimers();
const child = fakeChild();
child.exitCode = null;
child.signalCode = null;
child.kill.mockImplementation(() => { child.killed = true; return true; });
readJSONFile.mockResolvedValue({ version: 1, forwards: [{
id: 'fwd_1', peerId: 'peer-1', tcAddress: EXAMPLE_TC, localPort: 15555, remotePort: 5555,
}] });
const replacement = fakeChild();
const startForward = vi.fn().mockResolvedValueOnce(child).mockResolvedValue(replacement);
const options = {
ensureInstalled: async () => ({ bin: 'tailcat' }),
primeDerpMap: async () => null,
allocatePort: vi.fn(async () => 15555), startForward,
getPeersFn: async () => [{ id: 'peer-1', transport: 'tailcat', port: 15555 }],
patchForwardEntry: async (id, patch) => ({ id, ...patch }),
};
try {
await retryTailcatForward('fwd_1', options);
child.kill('SIGTERM'); // A sent signal must never stand in for an exit.
const retry = retryTailcatForward('fwd_1', options);
const concurrentRetry = retryTailcatForward('fwd_1', options);
await vi.advanceTimersByTimeAsync(8000);
expect(child.kill).toHaveBeenLastCalledWith('SIGKILL');
expect(startForward).toHaveBeenCalledTimes(1);
expect(options.allocatePort).toHaveBeenCalledTimes(1);
child.signalCode = 'SIGKILL';
child.emit('exit', null, 'SIGKILL');
await Promise.all([retry, concurrentRetry]);
expect(startForward).toHaveBeenCalledTimes(3);
expect(_liveForwardCountForTests()).toBe(1);
} finally {
vi.useRealTimers();
}
});
it('retains a child that will not exit and refuses to spawn a replacement', async () => {
vi.useFakeTimers();
const child = fakeChild();
child.exitCode = null;
child.signalCode = null;
child.kill.mockImplementation(() => { child.killed = true; return true; });
readJSONFile.mockResolvedValue({ version: 1, forwards: [{
id: 'fwd_1', peerId: 'peer-1', tcAddress: EXAMPLE_TC, localPort: 15555, remotePort: 5555,
}] });
const startForward = vi.fn(async () => child);
const options = {
ensureInstalled: async () => ({ bin: 'tailcat' }), primeDerpMap: async () => null,
allocatePort: async () => 15555, startForward,
getPeersFn: async () => [{ id: 'peer-1', transport: 'tailcat', port: 15555 }],
patchForwardEntry: async (id, patch) => ({ id, ...patch }),
};
try {
await retryTailcatForward('fwd_1', options);
const result = expect(retryTailcatForward('fwd_1', options))
.rejects.toMatchObject({ code: 'TAILCAT_STOP_TIMEOUT' });
await vi.advanceTimersByTimeAsync(16000);
await result;
expect(startForward).toHaveBeenCalledTimes(1);
expect(_liveForwardCountForTests()).toBe(1);
} finally {
child.emit('exit', null, 'SIGKILL');
vi.useRealTimers();
}
});
it('replaces a stale relay address without recreating its paired peer', async () => {
const replacement = 'tcEXAMPLE' + 'B'.repeat(40);
const savedPeer = { id: 'peer-1', transport: 'tailcat', port: 15555, syncSecret: 'example-pair-secret', syncCategories: { brain: true } };
readJSONFile.mockResolvedValue({ version: 1, forwards: [{
id: 'fwd_1', peerId: savedPeer.id, tcAddress: EXAMPLE_TC, localPort: 15555, remotePort: 5565,
}] });
const patches = [];
const startForward = vi.fn(async () => fakeChild());
const addPeerFn = vi.fn();
const peer = await retryTailcatForward('fwd_1', {
tcAddress: ` ${replacement} `,
ensureInstalled: async () => ({ bin: 'tailcat' }),
primeDerpMap: async () => ({}),
allocatePort: async () => 15555,
startForward, addPeerFn,
patchForwardEntry: async (id, patch) => { patches.push(patch); return { id, ...patch }; },
getPeersFn: async () => [savedPeer],
});
expect(patches[0]).toEqual({ tcAddress: replacement });
expect(startForward).toHaveBeenCalledWith(expect.objectContaining({ tcAddress: replacement, remotePort: 5565 }));
expect(peer).toBe(savedPeer);
expect(addPeerFn).not.toHaveBeenCalled();
const persist = vi.fn();
await expect(retryTailcatForward('fwd_1', { tcAddress: 'invalid', patchForwardEntry: persist }))
.rejects.toMatchObject({ code: 'TAILCAT_BAD_ADDRESS' });
expect(persist).not.toHaveBeenCalled();
});
it('repoints an existing peer when a retry has to bind a different port', async () => {
readJSONFile.mockResolvedValue({ version: 1, forwards: [{
id: 'fwd_1', peerId: 'peer-1', tcAddress: EXAMPLE_TC, localPort: 15555, remotePort: 5555,
}] });
const addPeerFn = vi.fn();
const setPeerPort = vi.fn(async (id, port) => ({ id, port, transport: 'tailcat' }));
const peer = await retryTailcatForward('fwd_1', {
ensureInstalled: async () => ({ bin: 'tailcat' }),
primeDerpMap: async () => ({ primed: false }),
allocatePort: async () => 15557,
remotePort: DEFAULT_TAILCAT_REMOTE_PORT,
startForward: async ({ remotePort }) => { expect(remotePort).toBe(DEFAULT_TAILCAT_REMOTE_PORT); return fakeChild(); },
addPeerFn,
patchForwardEntry: async (id, patch) => ({ id, ...patch }),
getPeersFn: async () => [{ id: 'peer-1', transport: 'tailcat', address: '127.0.0.1', port: 15555 }],
setPeerPortFn: setPeerPort,
});
// Re-registering would create a duplicate peer; the record has to follow the port.
expect(addPeerFn).not.toHaveBeenCalled();
expect(setPeerPort).toHaveBeenCalledWith('peer-1', 15557);
expect(peer.port).toBe(15557);
});
it('fails the retry rather than leaving a peer pointed at the dead port', async () => {
readJSONFile.mockResolvedValue({ version: 1, forwards: [{
id: 'fwd_1', peerId: 'peer-1', tcAddress: EXAMPLE_TC, localPort: 15555, remotePort: 5555,
}] });
const child = fakeChild();
await expect(retryTailcatForward('fwd_1', {
ensureInstalled: async () => ({ bin: 'tailcat' }),
primeDerpMap: async () => ({ primed: false }),
allocatePort: async () => 15557,
startForward: async () => child,
addPeerFn: async () => { throw new Error('must not register a duplicate'); },
patchForwardEntry: async (id, patch) => ({ id, ...patch }),
getPeersFn: async () => [{ id: 'peer-1', transport: 'tailcat', address: '127.0.0.1', port: 15555 }],
// The record vanished (or stopped being a tailcat peer) mid-retry.
setPeerPortFn: async () => null,
})).rejects.toMatchObject({ code: 'TAILCAT_PEER_REPOINT_FAILED', status: 409 });
expect(child.killed).toBe(true);
});
it('registers a fresh peer when the saved peerId no longer names a tailcat peer', async () => {
readJSONFile.mockResolvedValue({ version: 1, forwards: [{
id: 'fwd_1', peerId: 'peer-1', tcAddress: EXAMPLE_TC, localPort: 15555, remotePort: 5555,
}] });
const addPeerFn = vi.fn(async (data) => ({ id: 'peer-new', ...data }));
const setPeerPortFn = vi.fn();
const peer = await retryTailcatForward('fwd_1', {
ensureInstalled: async () => ({ bin: 'tailcat' }),
primeDerpMap: async () => ({ primed: false }),
allocatePort: async () => 15555,
startForward: async () => fakeChild(),
addPeerFn,
patchForwardEntry: async (id, patch) => ({ id, ...patch }),
// Same id, but a classic peer now — adopting it would repoint an unrelated route.
getPeersFn: async () => [{ id: 'peer-1', address: '192.0.2.10', port: 5555 }],
setPeerPortFn,
});
expect(setPeerPortFn).not.toHaveBeenCalled();
expect(addPeerFn).toHaveBeenCalledOnce();
expect(peer.id).toBe('peer-new');
});
it('records a redacted reason when a retry fails again', async () => {
readJSONFile.mockResolvedValue({ version: 1, forwards: [{
id: 'fwd_1', peerId: null, tcAddress: EXAMPLE_TC, localPort: 15555, remotePort: 5555,
}] });
const patches = [];
await expect(retryTailcatForward('fwd_1', {
ensureInstalled: async () => ({ bin: 'tailcat' }),
primeDerpMap: async () => ({ primed: false }),
allocatePort: async () => 15555,
startForward: async () => { throw new Error(`no relay for ${EXAMPLE_TC}`); },
patchForwardEntry: async (id, patch) => { patches.push(patch); return { id, ...patch }; },
getPeersFn: async () => [],
})).rejects.toMatchObject({ code: 'TAILCAT_FORWARD_FAILED' });
expect(patches.at(-1)).toMatchObject({ status: 'failed' });
expect(patches.at(-1).lastError).toContain('no relay');
expect(patches.at(-1).lastError).not.toContain('tcEXAMPLE');
});
it('rejects a retry for an unknown forward instead of inventing one', async () => {
await expect(retryTailcatForward('fwd_missing')).rejects.toMatchObject({ status: 404 });
});
it('forget removes the stored capability along with its peer', async () => {
readJSONFile.mockResolvedValue({ version: 1, forwards: [{
id: 'fwd_1', peerId: 'peer-1', tcAddress: EXAMPLE_TC, localPort: 15555, remotePort: 5555,
}] });
const removePeerFn = vi.fn().mockResolvedValue({ id: 'peer-1' });
await expect(forgetTailcatForward('fwd_missing', { removePeerFn })).rejects.toMatchObject({ status: 404 });
await expect(forgetTailcatForward('fwd_1', { removePeerFn })).resolves.toEqual({ id: 'fwd_1', peerId: 'peer-1' });
expect(removePeerFn).toHaveBeenCalledWith('peer-1', { stopTransport: false });
const [, written] = atomicWrite.mock.calls.at(-1);
expect(written.forwards).toEqual([]);
});
});
describe('tailcat startup diagnostics', () => {
beforeEach(() => { _resetLiveForwardsForTests(); vi.clearAllMocks(); });
afterEach(() => { _resetLiveForwardsForTests(); });
it('reports what tailcat said when startup times out, instead of only that it did', async () => {
vi.useFakeTimers();
const child = fakeChild();
const pending = startForwardProcess({ bin: 'tailcat', tcAddress: EXAMPLE_TC, localPort: 15555,
spawnFn: () => child, readyMs: 8000, isListening: async () => false });
const assertion = expect(pending).rejects.toThrow(/fetching DERPMap/);
child.stderr.emit('data', 'Expand: fetching DERPMap for region -1: context deadline exceeded\n');
await vi.advanceTimersByTimeAsync(8000);
await assertion;
vi.useRealTimers();
});
it('accepts a listening local port as readiness, so a quiet CLI build still works', async () => {
// tailcat <=0.5.0 logs `forwarding …` only under --verbose; readiness must not
// depend on any log wording, or a released build times out while working fine.
const child = fakeChild();
let probes = 0;
await expect(startForwardProcess({
bin: 'tailcat', tcAddress: EXAMPLE_TC, localPort: 15555, spawnFn: () => child,
readyMs: 2_000, probeMs: 5,
// First probe: nothing listening yet. Second: the listener is up.
isListening: async () => { probes += 1; return probes > 1; },
})).resolves.toBe(child);
});
});
describe('verifyTunnelReachable', () => {
const url = 'http://127.0.0.1:15555/api/system/health';
it('treats any HTTP response as proof the tunnel carried the request', async () => {
// 401 from an auth-gating proxy still means bytes crossed — this probes the
// transport, not the API.
const fetchFn = vi.fn(async () => ({ status: 401 }));
await expect(verifyTunnelReachable({ localPort: 15555, fetchFn })).resolves.toBeNull();
expect(fetchFn.mock.calls[0][0]).toBe(url);
});
it('returns the failure detail when nothing answers, and honors https + auth', async () => {
const fetchFn = vi.fn(async () => { throw new Error('fetch failed'); });
const auth = { username: 'u', password: 'p' };
await expect(verifyTunnelReachable({ localPort: 15556, protocol: 'https', auth, fetchFn }))
.resolves.toBe('fetch failed');
expect(fetchFn.mock.calls[0][0]).toBe('https://127.0.0.1:15556/api/system/health');
expect(fetchFn.mock.calls[0][2]).toEqual({ auth });
});
it('skips verification rather than reaching the network when no fetch is available', async () => {
await expect(verifyTunnelReachable({ localPort: 15555, fetchFn: null })).resolves.toBeNull();
});
});