Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

23.2 KB
Raw Blame
import { createHash, randomBytes } from 'node:crypto'
import { createServer, request } from 'node:http'
import { connect } from 'node:net'
import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { dirname, join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import {
  askDataFolderServer, isLocalSocketName, isTrustedLocal, listenLocalSocket, localSocketListenPath, localSocketName, localSocketPath, ORPHAN_STILL_SERVING,
  ORPHAN_WAIT_MS, refuseServedDataFolder, servedFolderDeps, socketPathIn, unixSocketPath, type DataFolderServer, type LocalSocketServer, type ServedFolderDeps,
} from './localSocket.js'
import { daemonPipe } from './windows/daemonPipe.js'
import { writeDaemonRecord } from './daemonRecord.js'
import { ensureDaemonToken, newPipePath } from './windows/pipeAuth.js'

const LOCAL_SOCKET_NAME = localSocketName(18473)

/** A filesystem without hard links, when a test says so. */
const fsState = vi.hoisted(() => ({ noLinks: false }))
vi.mock('node:fs', async (importOriginal) => {
  const real = await importOriginal<typeof import('node:fs')>()
  return {
    ...real,
    linkSync: (...args: Parameters<typeof real.linkSync>) => {
      if (fsState.noLinks) throw Object.assign(new Error('EPERM: operation not permitted, link'), { code: 'EPERM' })
      return real.linkSync(...args)
    },
  }
})

// Socket paths are capped near 104 bytes; the test tmpdir on macOS is far longer.
const dirs: string[] = []
const opened: LocalSocketServer[] = []
function shortDir(): string {
  const dir = mkdtempSync('/tmp/hsock-')
  dirs.push(dir)
  return dir
}

afterEach(async () => {
  for (const socket of opened.splice(0)) await socket.close()
  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })
})

function get(socketPath: string, path: string): Promise<{ status: number; body: string }> {
  return new Promise((resolve, reject) => {
    const r = request({ socketPath, path }, (res) => {
      let body = ''
      res.on('data', (chunk) => { body += chunk })
      res.on('end', () => resolve({ status: res.statusCode ?? 0, body }))
    })
    r.on('error', reject)
    r.end()
  })
}

describe('localSocketPath', () => {
  it('names one socket per control port, and none on Windows or past the length limit', () => {
    expect(localSocketPath('/Users/me/.harness/cli/data', 18473, 'darwin')).toBe('/Users/me/.harness/cli/data/daemon-18473.sock')
    expect(localSocketPath('/home/me/.harness/cli/data', 18474, 'linux')).toBe('/home/me/.harness/cli/data/daemon-18474.sock')
    expect(localSocketPath('C:\\Users\\me\\.harness', 18473, 'win32')).toBeNull()
    // 96 bytes fits (the staging name adds 4, still under macOS's 104 with the terminator); 97 does not.
    const dirFor = (total: number) => `/${'d'.repeat(total - '/daemon-18473.sock'.length - 1)}`
    expect(localSocketPath(dirFor(96), 18473, 'darwin')).toHaveLength(96)
    expect(localSocketPath(dirFor(97), 18473, 'darwin')).toMatch(/\/\.harness\/s\/[0-9a-f]{16}\/daemon-18473\.sock$/)
    expect(isLocalSocketName('daemon-18473.sock')).toBe(true)
    expect(isLocalSocketName('daemon.sock')).toBe(false)
    expect(isLocalSocketName('daemon-18473.sock.bak')).toBe(false)
  })

  it('on Windows, names the pipe the running daemon recorded, and a new pipe for each start', () => {
    // os.tmpdir(), not shortDir()'s /tmp: this case runs on Windows too, and only names paths.
    const dir = mkdtempSync(join(tmpdir(), 'hsock-'))
    dirs.push(dir)
    expect(localSocketPath(dir, 18473, 'win32')).toBeNull()
    const pipe = newPipePath()
    writeDaemonRecord(dir, 18473, 24567, { pipe, pid: 4242 })
    expect(localSocketPath(dir, 18473, 'win32')).toBe(pipe)
    expect(localSocketPath(dir, 18474, 'win32')).toBeNull()
    // The filesystem socket the services and ws+unix clients use: none on Windows, the same everywhere else.
    expect(unixSocketPath(dir, 18473, 'win32')).toBeNull()
    expect(unixSocketPath(dir, 18473, 'darwin')).toBe(join(dir, LOCAL_SOCKET_NAME))
    expect(localSocketPath(dir, 18473, 'darwin')).toBe(join(dir, LOCAL_SOCKET_NAME))
    const first = localSocketListenPath(dir, 18473, 'win32')
    expect(first).toMatch(/^\\\\\.\\pipe\\harness-[0-9a-f]{32}$/)
    expect(localSocketListenPath(dir, 18473, 'win32')).not.toBe(first)
    expect(localSocketListenPath(dir, 18473, 'linux')).toBe(join(dir, LOCAL_SOCKET_NAME))
  })
})

describe('listenLocalSocket', () => {
  it('serves over a socket only its owner can open, and trusts exactly those requests', async () => {
    const path = join(shortDir(), LOCAL_SOCKET_NAME)
    let trusted: boolean | null = null
    const socket = await listenLocalSocket((req, res) => { trusted = isTrustedLocal(req); res.end('hi') }, path)
    opened.push(socket)

    expect(statSync(path).mode & 0o777).toBe(0o600)
    expect(await get(path, '/')).toEqual({ status: 200, body: 'hi' })
    expect(trusted).toBe(true)
    expect(isTrustedLocal(undefined)).toBe(false)
  })

  it('replaces a crashed daemon\'s socket file, and refuses to replace anything else', async () => {
    const dir = shortDir()
    const path = join(dir, LOCAL_SOCKET_NAME)
    // A socket file nobody listens on any more: what a crash leaves.
    const first = await listenLocalSocket((_req, res) => res.end('old'), path)
    first.server.close()
    const second = await listenLocalSocket((_req, res) => res.end('new'), path)
    opened.push(second)
    expect((await get(path, '/')).body).toBe('new')

    const notASocket = join(dir, 'plain')
    writeFileSync(notASocket, 'keep me')
    await expect(listenLocalSocket((_req, res) => res.end(), notASocket)).rejects.toThrow(/not a socket/)
    expect(existsSync(notASocket)).toBe(true)
  })

  it('gives daemons on different ports a socket each, in one data directory', async () => {
    // Each port has its own name, so a second daemon never touches the first one's socket and a
    // client that knows its port reaches the daemon on that port.
    const dir = shortDir()
    const first = await listenLocalSocket((_req, res) => res.end('18473'), localSocketPath(dir, 18473, 'darwin')!)
    const second = await listenLocalSocket((_req, res) => res.end('18474'), localSocketPath(dir, 18474, 'darwin')!)
    opened.push(first, second)
    expect((await get(first.path, '/')).body).toBe('18473')
    expect((await get(second.path, '/')).body).toBe('18474')
  })

  it('closes at once even while a peer holds an upgraded connection open', async () => {
    // What a restart-for-update meets: a WebSocket the app has not finished closing. Waiting on
    // `server.close`'s callback would hang the restart until that peer let go.
    const path = join(shortDir(), LOCAL_SOCKET_NAME)
    const socket = await listenLocalSocket((_req, res) => res.end(), path)
    const held: Array<import('node:net').Socket> = []
    socket.server.on('upgrade', (_req, raw) => {
      held.push(raw as import('node:net').Socket)
      raw.write('HTTP/1.1 101 Switching Protocols\r\nUpgrade: test\r\nConnection: Upgrade\r\n\r\n')
    })
    const client = connect(path)
    await new Promise<void>((resolve) => client.once('connect', () => resolve()))
    client.write('GET / HTTP/1.1\r\nHost: localhost\r\nUpgrade: test\r\nConnection: Upgrade\r\n\r\n')
    await new Promise<void>((resolve) => client.once('data', () => resolve()))

    const closed = await Promise.race([
      socket.close().then(() => 'closed'),
      new Promise((resolve) => setTimeout(() => resolve('hung'), 1000)),
    ])
    expect(closed).toBe('closed')
    expect(existsSync(path)).toBe(false)
    client.destroy()
    for (const raw of held) raw.destroy()
  })

  it('listens at the longest path it allows', async () => {
    const dir = shortDir()
    const padded = join(dir, 'p'.repeat(96 - dir.length - 1 - '/daemon-1.sock'.length))
    mkdirSync(padded)
    const path = localSocketPath(padded, 1, 'darwin')!
    expect(Buffer.byteLength(path)).toBe(96)
    const socket = await listenLocalSocket((_req, res) => res.end('long'), path)
    opened.push(socket)
    expect((await get(path, '/')).body).toBe('long')
    expect(statSync(path).mode & 0o777).toBe(0o600)
  })

  it('gives the socket to one of two daemons claiming it at once, and refuses the other', async () => {
    // Two masters racing (e2e/twodaemons.e2e.ts): both used to "claim" it, the second's socket replacing
    // the first's, which went on listening where nothing could reach it.
    for (let round = 0; round < 10; round++) {
      const path = join(shortDir(), LOCAL_SOCKET_NAME)
      const claims = await Promise.allSettled([
        listenLocalSocket((_req, res) => res.end('first'), path),
        listenLocalSocket((_req, res) => res.end('second'), path),
      ])
      const won = claims.flatMap((claim, i) => claim.status === 'fulfilled' ? [{ socket: claim.value, body: i ? 'second' : 'first' }] : [])
      const lost = claims.flatMap((claim) => claim.status === 'rejected' ? [claim.reason as NodeJS.ErrnoException] : [])
      expect(won).toHaveLength(1)
      opened.push(won[0]!.socket)
      expect(lost).toMatchObject([{ code: 'EADDRINUSE', message: `A Harness daemon is already serving ${path}` }])
      expect((await get(path, '/')).body).toBe(won[0]!.body)
      // Nothing staged is left behind.
      expect(readdirSync(join(path, '..'))).toEqual([LOCAL_SOCKET_NAME])
    }
  })

  it('takes its name the way it always did where the filesystem has no hard links', async () => {
    fsState.noLinks = true
    try {
      const path = join(shortDir(), LOCAL_SOCKET_NAME)
      const socket = await listenLocalSocket((_req, res) => res.end('renamed'), path)
      opened.push(socket)
      expect((await get(path, '/')).body).toBe('renamed')
      expect(statSync(path).mode & 0o777).toBe(0o600)
      expect(readdirSync(join(path, '..'))).toEqual([LOCAL_SOCKET_NAME])
    } finally {
      fsState.noLinks = false
    }
  })

  it('removes the socket file when it closes', async () => {
    const path = join(shortDir(), LOCAL_SOCKET_NAME)
    const socket = await listenLocalSocket((_req, res) => res.end(), path)
    await socket.close()
    expect(existsSync(path)).toBe(false)
    await expect(new Promise((resolve, reject) => {
      const c = connect(path, () => { c.end(); resolve(true) })
      c.on('error', reject)
    })).rejects.toThrow()

    const again = await listenLocalSocket((_req, res) => res.end(), path)
    again.closeSync()
    expect(existsSync(path)).toBe(false)
  })
})

describe('refuseServedDataFolder', () => {
  /** A daemon's answer to `GET /api/status`, as `harness start` gives it. */
  const status = (pid: number, corePid?: number) => (_req: unknown, res: { end(body: string): void }) =>
    res.end(JSON.stringify({ pid, ...(corePid === undefined ? {} : { corePid }) }))

  it('refuses only a data folder a daemon is serving right now, as the bind would', async () => {
    const dir = shortDir()
    const path = join(dir, LOCAL_SOCKET_NAME)
    // No socket at all, a crashed daemon's, a file that is not one, and no path where there is none.
    await expect(refuseServedDataFolder(path)).resolves.toBeUndefined()
    const crashed = await listenLocalSocket((_req, res) => res.end(), path)
    crashed.server.close()
    await expect(refuseServedDataFolder(path)).resolves.toBeUndefined()
    await expect(refuseServedDataFolder(null)).resolves.toBeUndefined()
    const plain = join(dir, 'plain')
    writeFileSync(plain, 'not a socket')
    await expect(refuseServedDataFolder(plain)).resolves.toBeUndefined()

    // A daemon with no master, and one whose master is this live process: refused at once.
    for (const answer of [status(process.pid), status(process.pid, process.ppid)]) {
      const running = await listenLocalSocket(answer as never, path)
      const startedAt = Date.now()
      const refused = await refuseServedDataFolder(path).catch((error: unknown) => error as NodeJS.ErrnoException)
      expect(refused).toMatchObject({ code: 'EADDRINUSE', message: `A Harness daemon is already serving ${path}` })
      expect(Date.now() - startedAt).toBeLessThan(2_000)
      await running.close()
    }
  })

  it('waits for the core of a master that is gone to leave, and starts once it has', async () => {
    // Under launchd or systemd a master that died is started again at once, while its old core still
    // serves until it notices. Refused, the new core exited for good and the daemon stayed down.
    const path = join(shortDir(), LOCAL_SOCKET_NAME)
    const orphan = await listenLocalSocket(status(2_000_000_000, process.pid) as never, path)
    const lines: string[] = []
    setTimeout(() => void orphan.close(), 600)
    await expect(refuseServedDataFolder(path, 1_000, {
      who: askDataFolderServer, alive: () => false, sleep: (ms) => new Promise((done) => setTimeout(done, ms)),
      now: () => performance.now(), log: (line) => lines.push(line),
    })).resolves.toBeUndefined()
    expect(lines).toEqual([
      `[cli] this data folder is still served by the core (pid ${process.pid}) of a master that is gone (pid 2000000000) — waiting for it to leave`,
      '[cli] the core whose master is gone has left — starting',
    ])
  })

  it('reads who serves: a daemon and its master, one from before harnessd as its own, and anything else as unknown', async () => {
    const path = join(shortDir(), LOCAL_SOCKET_NAME)
    expect(await askDataFolderServer(path, 500)).toBe('none')
    const answers: Array<[unknown, DataFolderServer]> = [
      [status(10, 20), { pid: 10, corePid: 20 }],
      [status(10), { pid: 10, corePid: 10 }],
      [status(0, 20), 'unknown'],
      [(_req: unknown, res: { end(body: string): void }) => res.end('not json'), 'unknown'],
    ]
    for (const [handler, expected] of answers) {
      const server = await listenLocalSocket(handler as never, path)
      expect(await askDataFolderServer(path, 500)).toEqual(expected)
      await server.close()
    }
    // One that takes the connection and never answers.
    const silent = await listenLocalSocket(() => {}, path)
    expect(await askDataFolderServer(path, 200)).toBe('unknown')
    await silent.close()
  })

  it('decides from who serves: waits on an orphan or a silence until it goes or the wait is over, refuses a live daemon at once', async () => {
    const run = async (answers: DataFolderServer[], alive: (pid: number) => boolean = () => false) => {
      let clock = 0
      const lines: string[] = []
      const deps: ServedFolderDeps = {
        who: async () => answers.length > 1 ? answers.shift()! : answers[0], alive,
        sleep: async (ms) => { clock += ms }, now: () => clock, log: (line) => lines.push(line),
      }
      const outcome = await refuseServedDataFolder('/data/daemon-1.sock', 1_000, deps).then(() => 'started', (error: NodeJS.ErrnoException) => error.code)
      return { outcome, waited: clock, lines }
    }
    expect(await run(['none'])).toEqual({ outcome: 'started', waited: 0, lines: [] })
    expect(await run([{ pid: 7, corePid: 8 }, { pid: 7, corePid: 8 }, 'none'])).toMatchObject({ outcome: 'started', waited: 500 })
    // A daemon that does not say who it is is busy or hung, not leaving: every release with this socket
    // says its pid. Refused at once, as before: a person waiting on a start never waits out the bound
    // for it (the fake daemon of cliCommand.spec.ts answered without a pid, and each start took 20 s).
    expect(await run(['unknown', 'none'])).toMatchObject({ outcome: 'EADDRINUSE', waited: 0, lines: [] })
    // The orphan itself may go quiet while it stops, once it has been seen to be one.
    const stopping = await run([{ pid: 7, corePid: 8 }, 'unknown', 'none'])
    expect(stopping).toMatchObject({ outcome: 'started', waited: 500 })
    expect(stopping.lines).toEqual([
      '[cli] this data folder is still served by the core (pid 8) of a master that is gone (pid 7) — waiting for it to leave',
      '[cli] the core whose master is gone has left — starting',
    ])
    // Its master alive, or no master at all: another daemon.
    expect(await run([{ pid: 7, corePid: 8 }], () => true)).toMatchObject({ outcome: 'EADDRINUSE', waited: 0 })
    expect(await run([{ pid: 8, corePid: 8 }])).toMatchObject({ outcome: 'EADDRINUSE', waited: 0 })
    // One that never leaves is refused once the wait is over.
    // Refused as the orphan it is, which its master starts again, never as another daemon (an exit for good).
    const lingering = await run([{ pid: 7, corePid: 8 }])
    expect(lingering).toMatchObject({ outcome: ORPHAN_STILL_SERVING, waited: ORPHAN_WAIT_MS })
    expect(lingering.lines).toHaveLength(1)
  })
})

/** A data folder for the token: /tmp's short path where sockets need one, the temp folder on Windows. */
function pipeDir(): string {
  if (process.platform !== 'win32') return shortDir()
  const dir = mkdtempSync(join(tmpdir(), 'hpipe-'))
  dirs.push(dir)
  return dir
}

describe('who serves a data folder, over the Windows pipe', () => {
  /** The daemon's pipe on Windows, its recorded process taken as running. */
  const live = { platform: 'win32' as const, pipe: (d: string, p: number) => daemonPipe(d, p, { alive: () => true }) }

  it('asks with the token, and takes only an answer that proves it', async () => {
    // On Windows these are real pipes (\\.\pipe\harness-<id>); elsewhere sockets named alike.
    const dir = pipeDir()
    const pipeName = (): string => (process.platform === 'win32' ? newPipePath() : join(dir, `harness-${randomBytes(16).toString('hex')}`))
    const token = ensureDaemonToken(dir)
    const path = pipeName()
    const status = { pid: 4242, corePid: 4243 }
    opened.push(await listenLocalSocket((_req, res) => res.end(JSON.stringify(status)), path, { token }))
    expect(await askDataFolderServer(path, 1_000, token)).toEqual(status)
    // Another token: a 401 without the proof, which is not this data folder's daemon.
    expect(await askDataFolderServer(path, 1_000, randomBytes(32))).toBe('none')
    // Whatever took a dead daemon's name: no proof, so nothing serves, and start-up goes on.
    const squatted = pipeName()
    const squatter = createServer((_req, res) => res.end(JSON.stringify(status)))
    await new Promise<void>((resolve) => squatter.listen(squatted, resolve))
    try {
      expect(await askDataFolderServer(squatted, 1_000, token)).toBe('none')
    } finally {
      squatter.close()
    }
    // A stale record: nothing listens there, so nothing serves. A listener that never answers may be a slow daemon: unknown, and start-up refuses.
    expect(await askDataFolderServer(pipeName(), 1_000, token)).toBe('none')
    const silent = pipeName()
    const mute = createServer(() => { /* never answers */ })
    await new Promise<void>((resolve) => mute.listen(silent, resolve))
    try {
      expect(await askDataFolderServer(silent, 200, token)).toBe('unknown')
    } finally {
      mute.closeAllConnections()
      mute.close()
    }
    // A name that is no Harness pipe is never dialled.
    expect(await askDataFolderServer(join(dir, 'other.sock'), 1_000, token)).toBe('none')
    expect(servedFolderDeps(dir, 18473, { platform: 'darwin' }).who).toBe(askDataFolderServer)
    writeDaemonRecord(dir, 18473, 24567, { pipe: path, pid: process.pid })
    expect(await servedFolderDeps(dir, 18473, live).who(path, 1_000)).toEqual(status)
    // No token in that folder: no daemon has started there.
    expect(await servedFolderDeps(pipeDir(), 18473, live).who(path, 1_000)).toBe('none')
  })

  it('takes a recorded daemon proven gone as serving nothing, without dialling its pipe', async () => {
    const dir = pipeDir(), port = 18473
    ensureDaemonToken(dir)
    // Whatever took the dead daemon's name, and hangs: dialled, it would be `unknown` and block every start.
    const pipe = process.platform === 'win32' ? newPipePath() : join(dir, `harness-${randomBytes(16).toString('hex')}`)
    let dialled = 0
    const squatter = createServer(() => { /* never answers */ })
    squatter.on('connection', () => { dialled++ })
    await new Promise<void>((resolve) => squatter.listen(pipe, resolve))
    try {
      writeDaemonRecord(dir, port, 24567, { pipe, pid: 4242 })
      const gone = { platform: 'win32' as const, pipe: (d: string, p: number) => daemonPipe(d, p, { alive: () => false }) }
      expect(await servedFolderDeps(dir, port, gone).who(pipe, 200)).toBe('none')
      expect(dialled).toBe(0)
      // Its process still there: the B2.9 ask, where a silence may be a slow daemon.
      expect(await servedFolderDeps(dir, port, live).who(pipe, 200)).toBe('unknown')
      expect(dialled).toBe(1)
    } finally {
      squatter.closeAllConnections()
      squatter.close()
    }
  })
})

describe('a data folder too long to hold a socket', () => {
  const long = `/data/${'x'.repeat(120)}`
  const hash = (folder: string): string => createHash('sha256').update(folder).digest('hex').slice(0, 16)

  it('keeps a short folder\'s socket where it is', () => {
    expect(socketPathIn('/d', 'daemon-1.sock', '/h')).toBe('/d/daemon-1.sock')
  })

  it('gets one under the home folder, the same each time and another for another folder', () => {
    const path = socketPathIn(long, 'daemon-1.sock', '/h')
    expect(path).toBe(`/h/.harness/s/${hash(long)}/daemon-1.sock`)
    expect(socketPathIn(long, 'daemon-1.sock', '/h')).toBe(path)
    expect(socketPathIn(`${long}y`, 'daemon-1.sock', '/h')).not.toBe(path)
  })

  it('has none when the home folder is too long as well: the one case left on TCP', () => {
    expect(socketPathIn(long, 'daemon-1.sock', `/${'h'.repeat(120)}`)).toBeNull()
  })

  it('pins the rule every client copies', () => {
    expect(socketPathIn(long, 'bridge.sock', '/h')).toBe(`/h/.harness/s/${hash(long)}/bridge.sock`)
    // Desktop's test pins the same hash (desktop/test/local_daemon_transport_test.dart).
    expect(hash(`/${'x'.repeat(100)}`)).toBe('e50e7828cbafcbee')
    expect(hash('/x')).toBe('b3d1db318671a024')
  })

  describe('listening', () => {
    let home: string, closers: Array<() => Promise<unknown>>
    beforeEach(() => { home = mkdtempSync(join('/tmp', 'ls-')); closers = [] })
    afterEach(async () => { for (const close of closers) await close(); rmSync(home, { recursive: true, force: true }) })

    it('makes the short folder 0700 and the socket 0600', async () => {
      const path = socketPathIn(long, 'daemon-1.sock', home)!
      const listening = await listenLocalSocket(() => {}, path)
      closers.push(listening.close)
      expect(lstatSync(dirname(path)).mode & 0o777).toBe(0o700)
      expect(lstatSync(join(home, '.harness', 's')).mode & 0o777).toBe(0o700)
      expect(lstatSync(path).mode & 0o777).toBe(0o600)
    })

    it('tightens a looser short folder before it listens', async () => {
      const path = socketPathIn(long, 'daemon-1.sock', home)!
      mkdirSync(dirname(path), { recursive: true, mode: 0o777 })
      chmodSync(dirname(path), 0o777)
      const listening = await listenLocalSocket(() => {}, path)
      closers.push(listening.close)
      expect(lstatSync(dirname(path)).mode & 0o777).toBe(0o700)
    })

    it('refuses a short folder that is a link', async () => {
      const path = socketPathIn(long, 'daemon-1.sock', home)!
      mkdirSync(dirname(dirname(path)), { recursive: true, mode: 0o700 })
      const elsewhere = mkdtempSync(join('/tmp', 'ls-other-'))
      closers.push(async () => rmSync(elsewhere, { recursive: true, force: true }))
      symlinkSync(elsewhere, dirname(path))
      await expect(listenLocalSocket(() => {}, path)).rejects.toThrow(/not private/)
    })
  })
})