MingaClaudeBridge.Transport.Port (minga_claude_bridge v0.1.0)

Copy Markdown View Source

The MingaClaudeBridge.Transport that runs the real claude executable through an Erlang Port.

Each transport is a process linked to its owner (the session). It resolves the executable to an absolute path (MingaClaudeBridge.Binary), builds the arguments (MingaClaudeBridge.Launch) and the environment (MingaClaudeBridge.Env), creates an empty private working directory (MingaClaudeBridge.Workdir), and opens the Port with :spawn_executable, so no shell runs.

Lines

The Port delivers stdout in {:line, 65_536} fragments. MingaClaudeBridge.LineBuffer joins them into whole lines up to :max_line_bytes (32 MiB by default). A longer line sends {:error, :line_too_long} to the owner and stops the child.

Stopping the child

The child never outlives its transport. When the transport stops for any reason (stop/2, owner exit, a line that is too long, or a crash in this process), terminate/2 closes the Port, which closes the child's stdin, then sends SIGTERM to the OS pid, waits up to :kill_grace_ms (500 ms by default), and sends SIGKILL if the process is still there. The working directory is then removed.

Options

Besides the :owner, :ref, and :launch options every transport gets:

  • :executable - an absolute path to run instead of resolving claude.
  • :binary - extra options for MingaClaudeBridge.Binary.resolve/1, for tests.
  • :parent_env - the environment to start from. Defaults to System.get_env/0.
  • :credential_env - the route credential's env map. Defaults to %{}.
  • :session_key - names the working directory; use a stable key per conversation so --resume finds its session. Defaults to a random key.
  • :workdir_base - the private base directory. Defaults to MingaClaudeBridge.Workdir.base_path/0.
  • :max_line_bytes, :kill_grace_ms - see above.
  • :debug - write raw line logs (MingaClaudeBridge.DebugLog). Defaults to CLAUDE_BRIDGE_DEBUG=1 in the parent environment.

Summary

Functions

Returns a specification to start this module under a supervisor.

Returns the OS pid of the child, or nil after it exited. For diagnostics and tests.

Returns the child's working directory. For diagnostics and tests.

Types

t()

@type t() :: %MingaClaudeBridge.Transport.Port{
  buffer: MingaClaudeBridge.LineBuffer.t(),
  debug: MingaClaudeBridge.DebugLog.t(),
  kill_grace_ms: non_neg_integer(),
  os_pid: pos_integer() | nil,
  owner: pid(),
  port: port() | nil,
  ref: reference(),
  workdir: Path.t() | nil
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

os_pid(pid)

@spec os_pid(pid()) :: pos_integer() | nil

Returns the OS pid of the child, or nil after it exited. For diagnostics and tests.

workdir(pid)

@spec workdir(pid()) :: Path.t() | nil

Returns the child's working directory. For diagnostics and tests.