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.

17.4 KB
Raw Blame
import 'dart:async';
import 'dart:isolate';
import 'dart:typed_data';

import 'windows_pipe_kernel32.dart'
    if (dart.library.js_interop) 'windows_pipe_kernel32_web.dart';

/// One open connection to the daemon's pipe: bytes in, bytes out. One carries
/// one HTTP exchange or one WebSocket, as a Unix socket does on macOS.
abstract interface class PipeStream {
  /// What the daemon sends, until it closes its end.
  Stream<Uint8List> get input;

  /// Sends [bytes]. Ignored once the connection is closing.
  void add(List<int> bytes);

  /// Sends pending bytes for a bounded while, then closes the connection.
  Future<void> close();
}

/// Opens a [PipeStream] to the pipe at a path.
typedef PipeDialer = Future<PipeStream> Function(String pipePath);

/// Why the pipe could not be used. Every one of them means the same to a
/// trusted caller: there is no pipe to trust right now.
sealed class PipeFailure implements Exception {
  const PipeFailure(this.message);
  final String message;

  @override
  String toString() => message;
}

/// The data folder records no pipe (or one that is not a Harness pipe), or
/// has no token.
final class PipeRecordMissing extends PipeFailure {
  const PipeRecordMissing()
    : super('The Harness daemon on this computer records no private pipe.');
}

/// Nothing listens at the recorded name (`ERROR_FILE_NOT_FOUND`).
final class PipeAbsent extends PipeFailure {
  const PipeAbsent(this.pipePath)
    : super('The Harness daemon\'s private pipe is not open.');
  final String pipePath;
}

/// Every instance of the pipe stayed busy for as long as the app waited.
final class PipeBusy extends PipeFailure {
  const PipeBusy(this.pipePath)
    : super('The Harness daemon\'s private pipe stayed busy.');
  final String pipePath;
}

/// CreateFileW refused for another reason, by its Windows error [code].
final class PipeOpenFailed extends PipeFailure {
  const PipeOpenFailed(this.pipePath, this.code)
    : super('The Harness daemon\'s private pipe could not be opened.');
  final String pipePath;
  final int code;
}

/// The daemon closed its end while something was still to be written.
final class PipeBroken extends PipeFailure {
  const PipeBroken() : super('The Harness daemon closed its private pipe.');
}

/// A read or a write failed, by its Windows error [code] (or an NTSTATUS).
final class PipeIoFailed extends PipeFailure {
  const PipeIoFailed(this.code)
    : super('Reading or writing the Harness daemon\'s private pipe failed.');
  final int code;
}

/// Something answered on the pipe without the daemon's proof: not this
/// user's daemon (a process that took the name of a daemon that is gone).
final class PipeUnproven extends PipeFailure {
  const PipeUnproven(this.pipePath)
    : super('Something other than Harness answered on its private pipe.');
  final String pipePath;
}

/// The answer was not the HTTP the daemon speaks, or it came too late.
final class PipeProtocolError extends PipeFailure {
  const PipeProtocolError(super.message);
}

// The Windows errors the pipe can report (winerror.h).
const errorFileNotFound = 2;
const errorBrokenPipe = 109;
const errorPipeBusy = 231;
const errorNoData = 232;
const errorPipeNotConnected = 233;
const errorMoreData = 234;
const errorOperationAborted = 995;
const errorIoPending = 997;

/// `INVALID_HANDLE_VALUE`.
const invalidPipeHandle = -1;

/// The most one read takes and one write gives.
const pipeChunkBytes = 64 * 1024;

/// How long an open waits, in all, while every instance of the pipe is busy.
const defaultPipeBusyWait = Duration(seconds: 2);

/// The kernel32 calls a pipe connection makes, behind an interface so the
/// state machine below runs anywhere against a fake. Every call returns what
/// it did and, when it failed, the Windows error (0 on success). Reads and
/// writes block their isolate until they complete.
abstract interface class PipeIo {
  /// CreateFileW on [path]: a handle, or [invalidPipeHandle] and the error.
  ({int handle, int error}) create(String path);

  /// WaitNamedPipeW: whether an instance came free within [timeoutMs].
  bool waitFree(String path, int timeoutMs);

  /// One read of at most [max] bytes: what came, or the error that ended it.
  ({Uint8List bytes, int error}) read(int handle, int max);

  /// One write of [bytes] from [offset]: how many went, or the error.
  ({int count, int error}) write(int handle, Uint8List bytes, int offset);

  /// Aborts a read blocked on [handle] in another isolate (CancelIoEx).
  void cancel(int handle);

  /// CloseHandle.
  void close(int handle);

  /// Frees what this instance allocated.
  void dispose();
}

/// Opens [path] through [io]. While every instance of the pipe is busy it
/// waits for one (WaitNamedPipeW), for at most [busyWaitMs] in all; then
/// [PipeBusy]. A name nobody listens on is [PipeAbsent]: the pipe is gone.
int openPipeHandle(
  PipeIo io,
  String path, {
  required int busyWaitMs,
  int Function()? clockMs,
}) {
  final now = clockMs ?? () => DateTime.now().millisecondsSinceEpoch;
  final deadline = now() + busyWaitMs;
  for (;;) {
    final opened = io.create(path);
    if (opened.error == 0 && opened.handle != invalidPipeHandle) {
      return opened.handle;
    }
    switch (opened.error) {
      case errorFileNotFound:
        throw PipeAbsent(path);
      case errorPipeBusy:
        final left = deadline - now();
        if (left <= 0) throw PipeBusy(path);
        // Whatever the wait says, CreateFileW is asked again: it alone says
        // reliably what is there now (the pipe may have gone meanwhile).
        io.waitFree(path, left);
      default:
        throw PipeOpenFailed(path, opened.error);
    }
  }
}

/// How a read loop ended.
enum PipeEnd {
  /// The daemon closed its end: the end of the stream.
  closedByPeer,

  /// This side cancelled the read, closing the connection.
  cancelled,
}

/// Reads [handle] until the daemon closes its end or the read is cancelled,
/// handing every chunk to [onData]. Any other failure is [PipeIoFailed].
PipeEnd pumpPipe(PipeIo io, int handle, void Function(Uint8List chunk) onData) {
  for (;;) {
    final got = io.read(handle, pipeChunkBytes);
    switch (got.error) {
      case 0:
        if (got.bytes.isNotEmpty) onData(got.bytes);
      case errorBrokenPipe || errorPipeNotConnected || errorNoData:
        return PipeEnd.closedByPeer;
      case errorOperationAborted:
        return PipeEnd.cancelled;
      default:
        throw PipeIoFailed(got.error);
    }
  }
}

/// Writes all of [bytes] to [handle], however many writes that takes. A daemon
/// that closed its end is [PipeBroken].
void writeAllToPipe(PipeIo io, int handle, Uint8List bytes) {
  var offset = 0;
  while (offset < bytes.length) {
    final wrote = io.write(handle, bytes, offset);
    switch (wrote.error) {
      case 0 when wrote.count > 0:
        offset += wrote.count;
      case errorBrokenPipe || errorNoData || errorPipeNotConnected:
        throw const PipeBroken();
      default:
        throw PipeIoFailed(wrote.error);
    }
  }
}

/// The daemon's Windows pipe as a [PipeStream] (spec §1.6), through kernel32
/// on two background isolates: their calls block, and the UI isolate never
/// may. One reads, blocked until bytes come; the other writes what [add] sends
/// it through a SendPort. The handle is overlapped, because a synchronous one
/// serialises a read and a write on it: a WebSocket waiting for the daemon
/// would hold up every keystroke.
class WindowsPipeConnection implements PipeStream {
  WindowsPipeConnection._(this.pipePath, this._factory) {
    // Awaited later, maybe after they failed: handled from the start.
    _opened.future.ignore();
    _writerReady.future.ignore();
  }

  final String pipePath;
  final PipeIo Function() _factory;
  final _input = StreamController<Uint8List>();
  final _fromReader = ReceivePort('harness pipe reader');
  final _fromWriter = ReceivePort('harness pipe writer');
  final _opened = Completer<void>();
  final _writerReady = Completer<void>();
  final _readerDone = Completer<void>();
  final _writerDone = Completer<void>();
  final _drains = <int, Completer<void>>{};
  var _nextDrain = 0;
  int? _handle;
  SendPort? _toWriter;
  PipeFailure? _writeFailed;
  Future<void>? _closing;
  PipeIo? _mainIo;
  var _starting = true;
  var _readerSpawned = false;
  var _writerSpawned = false;
  var _readEnded = false;
  var _cancelling = false;
  var _cleaned = false;
  Timer? _cancelTimer;

  @override
  Stream<Uint8List> get input => _input.stream;

  /// Opens the pipe at [pipePath]: [PipeAbsent] when nothing listens there,
  /// [PipeBusy] after [busyWait] of busy instances. [io] makes each isolate's
  /// kernel32 calls; it is sent to them, so it must be sendable between isolates.
  static Future<WindowsPipeConnection> open(
    String pipePath, {
    PipeIo Function()? io,
    Duration busyWait = defaultPipeBusyWait,
  }) async {
    final connection = WindowsPipeConnection._(pipePath, io ?? kernel32PipeIo);
    try {
      await connection._start(busyWait);
    } catch (_) {
      await connection.close();
      rethrow;
    }
    return connection;
  }

  Future<void> _start(Duration busyWait) async {
    _fromReader.listen(_onReader);
    _fromWriter.listen(_onWriter);
    try {
      await Isolate.spawn(
        _readerMain,
        (_fromReader.sendPort, pipePath, _factory, busyWait.inMilliseconds),
        debugName: 'harness pipe reader',
        onError: _fromReader.sendPort,
        onExit: _fromReader.sendPort,
      );
      _readerSpawned = true;
      await _opened.future;
      // A peer can close as soon as CreateFileW returns. Do not launch a new
      // handle user after shutdown has already begun.
      if (_readEnded) return;
      await Isolate.spawn(
        _writerMain,
        (_fromWriter.sendPort, _handle!, _factory),
        debugName: 'harness pipe writer',
        onError: _fromWriter.sendPort,
        onExit: _fromWriter.sendPort,
      );
      _writerSpawned = true;
      await _writerReady.future;
    } finally {
      _starting = false;
      if (_readEnded || _writeFailed != null) unawaited(close());
    }
  }

  void _onReader(Object? message) {
    switch (message) {
      case ('opened', final int handle):
        _handle = handle;
        _opened.complete();
      case ('data', final TransferableTypedData bytes):
        if (!_input.isClosed) _input.add(bytes.materialize().asUint8List());
      case ('failed', final String kind, final int code):
        final failure = switch (kind) {
          'absent' => PipeAbsent(pipePath),
          'busy' => PipeBusy(pipePath),
          'open' => PipeOpenFailed(pipePath, code),
          _ => PipeIoFailed(code),
        };
        _readerEnded(failure);
      case ('end', _):
        _readerEnded(null);
      case [_, _]:
        // An uncaught error in the reader (onError): its exit follows.
        _readerEnded(const PipeIoFailed(-1));
      case null:
        // The reader isolate has exited.
        _readerEnded(const PipeIoFailed(-1));
        if (!_readerDone.isCompleted) _readerDone.complete();
        _tryCleanup();
    }
  }

  /// The read loop is over: the stream ends, with [failure] first if any. A
  /// connection that was open closes itself, since nothing more will come.
  void _readerEnded(PipeFailure? failure) {
    if (_readEnded) return;
    _readEnded = true;
    if (!_opened.isCompleted) {
      _opened.completeError(failure ?? const PipeIoFailed(-1));
    } else if (!_input.isClosed) {
      if (failure != null && _closing == null) _input.addError(failure);
      unawaited(_input.close());
    }
    if (!_starting) unawaited(close());
  }

  void _onWriter(Object? message) {
    switch (message) {
      case ('ready', final SendPort port):
        _toWriter = port;
        _writerReady.complete();
      case ('drained', final int id):
        _drains.remove(id)?.complete();
      case ('failed', final int code):
        _writerFailed(
          code == errorBrokenPipe ? const PipeBroken() : PipeIoFailed(code),
        );
      case [_, _]:
        _writerFailed(const PipeIoFailed(-1));
      case null:
        if (!_writerReady.isCompleted) {
          _writerReady.completeError(const PipeIoFailed(-1));
        } else if (_closing == null && _writeFailed == null) {
          _writerFailed(const PipeIoFailed(-1));
        }
        _settleDrains();
        if (!_writerDone.isCompleted) _writerDone.complete();
        _tryCleanup();
    }
  }

  void _writerFailed(PipeFailure failure) {
    if (_writeFailed != null) return;
    _writeFailed = failure;
    if (!_writerReady.isCompleted) {
      _writerReady.completeError(failure);
    } else {
      if (!_input.isClosed && _closing == null) _input.addError(failure);
      if (!_starting) unawaited(close());
    }
    _settleDrains();
  }

  void _settleDrains() {
    for (final drain in _drains.values) {
      if (!drain.isCompleted) drain.complete();
    }
    _drains.clear();
  }

  @override
  void add(List<int> bytes) {
    final port = _toWriter;
    if (port == null || _closing != null || bytes.isEmpty) return;
    final chunk = bytes is Uint8List ? bytes : Uint8List.fromList(bytes);
    port.send(('write', TransferableTypedData.fromList([chunk])));
  }

  /// Stops accepting writes and waits at most two seconds for their drain,
  /// then at most two more for cancellation. Handle/resource cleanup continues
  /// after that bound if either isolate is still finishing its kernel call.
  @override
  Future<void> close() => _closing ??= _shutdown();

  Future<void> _shutdown() async {
    final port = _toWriter;
    if (port != null) {
      // What add() was given reaches the pipe first, for a bounded while.
      if (_writeFailed == null) {
        final id = _nextDrain++;
        final drained = _drains[id] = Completer<void>();
        port.send(('drain', id));
        await drained.future.timeout(_settle, onTimeout: () {});
      }
      port.send(('stop',));
    }
    // Cancellation is a request, not completion. Keep observing both isolates
    // after close's bounded wait, and retry a cancel that landed between reads.
    _cancelling = true;
    _cancelPending();
    _tryCleanup();
    if (!_cleaned) {
      _cancelTimer = Timer.periodic(const Duration(milliseconds: 100), (_) {
        _cancelPending();
        _tryCleanup();
      });
      await Future.wait<void>([
        if (_readerSpawned) _readerDone.future,
        if (_writerSpawned) _writerDone.future,
      ]).timeout(_settle, onTimeout: () => <void>[]);
      _tryCleanup();
    }
    // A delayed driver must not hold up callers or stream completion. Its
    // handle, ports and allocations stay owned until the real exits arrive.
    if (!_input.isClosed) unawaited(_input.close());
  }

  void _cancelPending() {
    final handle = _handle;
    if (handle != null && !_cleaned) {
      (_mainIo ??= _factory()).cancel(handle);
    }
  }

  void _tryCleanup() {
    if (_cleaned || !_cancelling || _starting) return;
    if (_readerSpawned && !_readerDone.isCompleted) return;
    if (_writerSpawned && !_writerDone.isCompleted) return;
    _cleaned = true;
    _cancelTimer?.cancel();
    // Neither isolate can ever use this numeric handle again. Windows may
    // recycle it immediately after CloseHandle.
    final handle = _handle;
    if (handle != null) (_mainIo ??= _factory()).close(handle);
    _fromReader.close();
    _fromWriter.close();
    _settleDrains();
    if (!_input.isClosed) unawaited(_input.close());
    _mainIo?.dispose();
  }

  static const _settle = Duration(seconds: 2);
}

/// The reader isolate: opens the pipe, says so, then reads until the end.
void _readerMain((SendPort, String, PipeIo Function(), int) start) {
  final (main, path, factory, busyWaitMs) = start;
  final io = factory();
  try {
    final int handle;
    try {
      handle = openPipeHandle(io, path, busyWaitMs: busyWaitMs);
    } on PipeAbsent {
      main.send(('failed', 'absent', errorFileNotFound));
      return;
    } on PipeBusy {
      main.send(('failed', 'busy', errorPipeBusy));
      return;
    } on PipeOpenFailed catch (failure) {
      main.send(('failed', 'open', failure.code));
      return;
    }
    main.send(('opened', handle));
    try {
      final end = pumpPipe(io, handle, (chunk) {
        main.send(('data', TransferableTypedData.fromList([chunk])));
      });
      main.send(('end', end.name));
    } on PipeIoFailed catch (failure) {
      main.send(('failed', 'io', failure.code));
    }
  } finally {
    io.dispose();
  }
}

/// The writer isolate: writes each chunk it is sent, in order, until stopped.
void _writerMain((SendPort, int, PipeIo Function()) start) {
  final (main, handle, factory) = start;
  final io = factory();
  final inbox = ReceivePort('harness pipe writes');
  var failed = false;
  inbox.listen((message) {
    switch (message) {
      case ('write', final TransferableTypedData bytes):
        if (failed) return;
        try {
          writeAllToPipe(io, handle, bytes.materialize().asUint8List());
        } on PipeBroken {
          failed = true;
          main.send(('failed', errorBrokenPipe));
        } on PipeIoFailed catch (failure) {
          failed = true;
          main.send(('failed', failure.code));
        } catch (_) {
          // Keep the inbox alive for stop so even an unexpected failure frees
          // this isolate's event/OVERLAPPED storage before its exit is observed.
          failed = true;
          main.send(('failed', -1));
        }
      case ('drain', final int id):
        main.send(('drained', id));
      case ('stop',):
        inbox.close();
        io.dispose();
    }
  });
  main.send(('ready', inbox.sendPort));
}