# `MingaClaudeBridge.Transport.Port`
[🔗](https://github.com/jsmestad/minga-claude-bridge/blob/main/lib/minga_claude_bridge/transport/port.ex#L1)

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.

# `t`

```elixir
@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
}
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `os_pid`

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

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

# `workdir`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
