# portals v0.1.0 - API Reference

## Modules

- [Portals.Handshake.Hello](Portals.Handshake.Hello.md): Decoded HELLO fields.
- [Portals.Stream.State](Portals.Stream.State.md): The per-stream credit and terminal-state machine, owned functionally
by `Portals.Connection` (like the pending-request table) rather than
by a process of its own.

- Calling workers
  - [Portals](Portals.md): Public API for invoking functions in a supervised external-language
worker (FR-2).
  - [Portals.Pool](Portals.Pool.md): A supervised, load-balanced set of workers running the same command
(FR-3). Maintains `size` base workers plus up to `max_overflow`
temporary overflow workers, created on demand and retired as soon as
they go idle.
  - [Portals.Request](Portals.Request.md): A reference to one in-flight or completed asynchronous call, returned by
`Portals.async/5` (or `Portals.Connection.async/5`). Pass it to
`Portals.await/2` and `Portals.cancel/1`.

  - [Portals.Stream](Portals.Stream.md): A handle on one bidirectional stream, plus the demand/credit and
terminal-state machine behind it (FR-5, Phase 6).

- Errors
  - [Portals.CallError](Portals.CallError.md): Raised by `Portals.call!/5` (and `Portals.Connection.call!/5`) on a failed call.
  - [Portals.Error](Portals.Error.md): The single failure representation returned to every Portals caller
(FR-4). All non-`{:ok, value}` outcomes are `{:error, %Portals.Error{}}`.

- Language packages
  - [Portals.SDK](Portals.SDK.md): The contract every `portals_<language>` package implements.

- Callbacks &amp; values
  - [Portals.Callback](Portals.Callback.md): Introspection helper for code running inside a callback handler
(invoked by `Portals.Connection` in response to a worker's `CALLBACK`
frame). See protocol/v1.md section 8 for the reentrancy-depth model.

  - [Portals.Codec.Bin](Portals.Codec.Bin.md): Explicit wrapper marking a value as the MessagePack `bin` type rather
than `str`. Plain Elixir binaries encode as UTF-8 strings by default;
wrap arbitrary byte payloads (image data, serialized blobs, and other
non-text binaries) in `%Portals.Codec.Bin{}` to force `bin` encoding.

- Conformance kit
  - [Portals.Conformance.Runner](Portals.Conformance.Runner.md): Black-box protocol conformance runner (FR-7 / Phase 1 exit criteria).
  - [Portals.Conformance.SDKSuite](Portals.Conformance.SDKSuite.md): The protocol conformance suite every worker SDK must pass.
  - [Portals.Conformance.WorkerSuite](Portals.Conformance.WorkerSuite.md): The shared black-box integration suite every worker SDK must pass.
  - [Portals.Fixtures.CallbackTarget](Portals.Fixtures.CallbackTarget.md): The BEAM-side callback target the shared conformance suites call back
into (as `Elixir.Portals.Fixtures.CallbackTarget`) from every SDK's
`bench_worker` fixture.

- Internals
  - [Portals.Codec](Portals.Codec.md): Behaviour implemented by every wire codec (`Portals.Codec.MessagePack` in
production, `Portals.Codec.ETFBench` for internal benchmarking only).
  - [Portals.Codec.MessagePack](Portals.Codec.MessagePack.md): The mandatory, portable 1.0 wire codec: MessagePack core types plus the
Portals Erlang-value extensions from `Portals.TermExtensions`.
  - [Portals.Connection](Portals.Connection.md): Owns one worker's socket, protocol state machine, and in-flight request
table (FR-1, FR-2). One `Portals.Connection` GenServer corresponds to
one launched worker process.
  - [Portals.Handshake](Portals.Handshake.md): Exact-version handshake rules shared by every SDK.
  - [Portals.Protocol](Portals.Protocol.md): Portals wire protocol v1: frame tags, default limits, and the frame
validation rules shared by every SDK implementation.
  - [Portals.SocketDir](Portals.SocketDir.md): Private per-worker runtime directory and Unix-domain socket path
management (FR-1). Every worker gets its own `0700` directory beneath a
shared Portals runtime root; stale sockets are removed deterministically
before a new listener binds to the same path.

  - [Portals.TermExtensions](Portals.TermExtensions.md): Erlang-specific value extensions layered on top of core MessagePack.
  - [Portals.Transport](Portals.Transport.md): Transport behaviour for moving framed bytes between the BEAM and a
worker. A transport does not know about frame contents; it only owns
byte delivery and must deliver received bytes as Erlang messages to the
owning process so a `Portals.Connection`-style GenServer can multiplex
transport I/O with call handling in its normal message loop.
  - [Portals.Transport.Stdio](Portals.Transport.Stdio.md): Length-framed stdin/stdout fallback transport, used automatically only
on platforms where Unix-domain sockets are unsupported. Experimental:
Linux (the only officially supported 1.0 platform) always uses
`Portals.Transport.Unix`.
  - [Portals.Transport.Unix](Portals.Transport.Unix.md): Default transport: one BEAM-created Unix-domain socket per worker.
  - [Portals.WorkerLifecycle.Port](Portals.WorkerLifecycle.Port.md): Launches and monitors the direct worker process through a BEAM Port
(FR-1). Owns only the direct child process — descendant processes the
worker itself spawns are not tracked or reaped; applications that need
process-tree ownership must wrap the worker in a container or process
group of their own.

## Mix Tasks

- [mix portals.sdk_path](Mix.Tasks.Portals.SdkPath.md): Prints the absolute path of the worker SDK bundled with a language
package, for configuring editors, type checkers, `go.mod` `replace`
directives or `javac -cp`