ExternalRuntimeTransport.Transport behaviour (ExternalRuntimeTransport v0.1.0)

Behaviour for the raw subprocess transport layer.

In addition to the long-lived subscriber-driven transport API, the transport layer also owns synchronous non-PTY command execution through run/2.

Legacy subscribers receive bare transport tuples:

{:transport_message, line}
{:transport_data, chunk}
{:transport_error, %ExternalRuntimeTransport.Transport.Error{}}
{:transport_stderr, chunk}
{:transport_exit, %ExternalRuntimeTransport.ProcessExit{}}

Tagged subscribers receive:

{event_tag, ref, {:message, line}}
{event_tag, ref, {:data, chunk}}
{event_tag, ref, {:error, %ExternalRuntimeTransport.Transport.Error{}}}
{event_tag, ref, {:stderr, chunk}}
{event_tag, ref, {:exit, %ExternalRuntimeTransport.ProcessExit{}}}

When :replay_stderr_on_subscribe? is enabled at startup, newly attached subscribers also receive the retained stderr tail immediately after subscription. When :buffer_events_until_subscribe? is enabled, stdout, stderr, and error events emitted before the first subscriber attaches are replayed in order.

Summary

Types

event_tag()

The tagged event atom prefix.

extracted_event()

Normalized transport event payload extracted from a mailbox message.

message()

Transport events delivered to subscribers.

subscription_tag()

Legacy subscribers use :legacy; tagged subscribers use a reference.

surface_kind()

Generic execution-surface placement kind.

t()

Opaque transport reference.

Callbacks

close(t)

end_input(t)

force_close(t)

info(t)

interrupt(t)

run(t, keyword)

send(t, arg2)

start(keyword)

start_link(keyword)

status(t)

stderr(t)

subscribe(t, pid)

subscribe(t, pid, subscription_tag)

unsubscribe(t, pid)

Functions

close(transport)

Stops the transport.

delivery_info(transport)

Returns stable mailbox-delivery metadata for the current transport snapshot.

end_input(transport)

Closes stdin for EOF-driven CLIs.

extract_event(arg1)

Extracts a normalized transport event from a legacy mailbox message.

extract_event(message, ref)

Extracts a normalized transport event for a tagged subscriber reference.

force_close(transport)

Forces the subprocess down immediately.

info(transport)

Returns the current transport metadata snapshot.

interrupt(transport)

Sends SIGINT to the subprocess.

run(command, opts \\ [])

Runs a one-shot non-PTY command and captures exact stdout, stderr, and exit data.

send(transport, message)

Sends data to the subprocess stdin.

start(opts)

Starts the default raw transport implementation.

start_link(opts)

Starts the default raw transport implementation and links it to the caller.

status(transport)

Returns transport connectivity status.

stderr(transport)

Returns the stderr ring buffer tail.

subscribe(transport, pid)

Subscribes the caller in legacy mode.

subscribe(transport, pid, tag)

Subscribes a process with an explicit tag mode.

unsubscribe(transport, pid)

Removes a subscriber.

Types

event_tag()

@type event_tag() :: atom()

The tagged event atom prefix.

extracted_event()

@type extracted_event() ::
  {:message, binary()}
  | {:data, binary()}
  | {:error, ExternalRuntimeTransport.Transport.Error.t()}
  | {:stderr, binary()}
  | {:exit, ExternalRuntimeTransport.ProcessExit.t()}

Normalized transport event payload extracted from a mailbox message.

message()

@type message() ::
  {:transport_message, binary()}
  | {:transport_data, binary()}
  | {:transport_error, ExternalRuntimeTransport.Transport.Error.t()}
  | {:transport_stderr, binary()}
  | {:transport_exit, ExternalRuntimeTransport.ProcessExit.t()}
  | {event_tag(), reference(), {:message, binary()}}
  | {event_tag(), reference(), {:data, binary()}}
  | {event_tag(), reference(),
     {:error, ExternalRuntimeTransport.Transport.Error.t()}}
  | {event_tag(), reference(), {:stderr, binary()}}
  | {event_tag(), reference(),
     {:exit, ExternalRuntimeTransport.ProcessExit.t()}}

Transport events delivered to subscribers.

subscription_tag()

@type subscription_tag() :: :legacy | reference()

Legacy subscribers use :legacy; tagged subscribers use a reference.

surface_kind()

@type surface_kind() :: :local_subprocess | :ssh_exec | :guest_bridge

Generic execution-surface placement kind.

t()

@type t() :: pid()

Opaque transport reference.

Callbacks

close(t)

@callback close(t()) :: :ok

end_input(t)

@callback end_input(t()) ::
  :ok | {:error, {:transport, ExternalRuntimeTransport.Transport.Error.t()}}

force_close(t)

@callback force_close(t()) ::
  :ok | {:error, {:transport, ExternalRuntimeTransport.Transport.Error.t()}}

info(t)

@callback info(t()) :: ExternalRuntimeTransport.Transport.Info.t()

interrupt(t)

@callback interrupt(t()) ::
  :ok | {:error, {:transport, ExternalRuntimeTransport.Transport.Error.t()}}

run(t, keyword)

@callback run(
  ExternalRuntimeTransport.Command.t(),
  keyword()
) ::
  {:ok, ExternalRuntimeTransport.Transport.RunResult.t()}
  | {:error, {:transport, ExternalRuntimeTransport.Transport.Error.t()}}

send(t, arg2)

@callback send(t(), iodata() | map() | list()) ::
  :ok | {:error, {:transport, ExternalRuntimeTransport.Transport.Error.t()}}

start(keyword)

@callback start(keyword()) ::
  {:ok, t()}
  | {:error, {:transport, ExternalRuntimeTransport.Transport.Error.t()}}

start_link(keyword)

@callback start_link(keyword()) ::
  {:ok, t()}
  | {:error, {:transport, ExternalRuntimeTransport.Transport.Error.t()}}

status(t)

@callback status(t()) :: :connected | :disconnected | :error

stderr(t)

@callback stderr(t()) :: binary()

unsubscribe(t, pid)

@callback unsubscribe(t(), pid()) :: :ok

Functions

close(transport)

@spec close(t()) :: :ok

Stops the transport.

delivery_info(transport)

@spec delivery_info(t()) :: ExternalRuntimeTransport.Transport.Delivery.t()

Returns stable mailbox-delivery metadata for the current transport snapshot.

end_input(transport)

@spec end_input(t()) ::
  :ok | {:error, {:transport, ExternalRuntimeTransport.Transport.Error.t()}}

Closes stdin for EOF-driven CLIs.

Pipe-backed transports send :eof; PTY-backed transports send the terminal EOF byte (Ctrl-D).

extract_event(arg1)

@spec extract_event(term()) :: {:ok, extracted_event()} | :error

Extracts a normalized transport event from a legacy mailbox message.

Tagged subscribers should use extract_event/2 so their code does not depend on a specific outer event tag.

extract_event(message, ref)

@spec extract_event(term(), reference()) :: {:ok, extracted_event()} | :error

Extracts a normalized transport event for a tagged subscriber reference.

This is the stable core-owned way for adapters to consume tagged transport delivery without hard-coding the configured outer event atom.

force_close(transport)

@spec force_close(t()) ::
  :ok | {:error, {:transport, ExternalRuntimeTransport.Transport.Error.t()}}

Forces the subprocess down immediately.

info(transport)

@spec info(t()) :: ExternalRuntimeTransport.Transport.Info.t()

Returns the current transport metadata snapshot.

interrupt(transport)

@spec interrupt(t()) ::
  :ok | {:error, {:transport, ExternalRuntimeTransport.Transport.Error.t()}}

Sends SIGINT to the subprocess.

run(command, opts \\ [])

@spec run(
  ExternalRuntimeTransport.Command.t(),
  keyword()
) ::
  {:ok, ExternalRuntimeTransport.Transport.RunResult.t()}
  | {:error, {:transport, ExternalRuntimeTransport.Transport.Error.t()}}

Runs a one-shot non-PTY command and captures exact stdout, stderr, and exit data.

send(transport, message)

@spec send(t(), iodata() | map() | list()) ::
  :ok | {:error, {:transport, ExternalRuntimeTransport.Transport.Error.t()}}

Sends data to the subprocess stdin.

start(opts)

@spec start(keyword()) ::
  {:ok, t()}
  | {:error, {:transport, ExternalRuntimeTransport.Transport.Error.t()}}

Starts the default raw transport implementation.

start_link(opts)

@spec start_link(keyword()) ::
  {:ok, t()}
  | {:error, {:transport, ExternalRuntimeTransport.Transport.Error.t()}}

Starts the default raw transport implementation and links it to the caller.

status(transport)

@spec status(t()) :: :connected | :disconnected | :error

Returns transport connectivity status.

stderr(transport)

@spec stderr(t()) :: binary()

Returns the stderr ring buffer tail.

unsubscribe(transport, pid)

@spec unsubscribe(t(), pid()) :: :ok

Removes a subscriber.