CliSubprocessCore.RawSession (CliSubprocessCore v0.1.0)

Provider-agnostic handle for long-lived raw subprocess sessions.

ExternalRuntimeTransport.Transport owns the subprocess lifecycle itself. This module provides a higher-level contract for consumers that need a stable raw session handle, exact-byte stdin/stdout defaults, optional PTY startup, and normalized result collection without re-implementing lifecycle rules in provider repos.

Summary

Types

info_t()

t()

Functions

close_input(raw_session)

Closes stdin for EOF-driven subprocesses.

collect(session, timeout_ms \\ 30000)

Collects session output until the subprocess exits.

delivery_info(session)

Returns stable mailbox-delivery metadata for the raw session.

force_close(raw_session)

Forces the subprocess down immediately.

info(session)

Returns the latest raw session metadata snapshot.

interrupt(raw_session)

Interrupts the subprocess according to the configured transport contract.

send_input(raw_session, data)

Sends exact input bytes through the session transport.

start(invocation)

Starts an unlinked raw subprocess session from a prebuilt invocation.

start(arg1, arg2)

Starts an unlinked raw subprocess session from either an executable and argv list or a prebuilt invocation plus options.

start(command, args, opts)

start_link(invocation)

Starts a linked raw subprocess session from a prebuilt invocation.

start_link(arg1, arg2)

Starts a linked raw subprocess session from either an executable and argv list or a prebuilt invocation plus options.

start_link(command, args, opts)

status(raw_session)

Returns the transport status for the raw session.

stderr(raw_session)

Returns the stderr tail retained by the underlying transport.

stop(raw_session)

Stops the subprocess transport.

Types

info_t()

@type info_t() :: %{
  delivery: CliSubprocessCore.RawSession.Delivery.t(),
  invocation: CliSubprocessCore.Command.t(),
  receiver: pid(),
  transport_ref: reference(),
  event_tag: atom(),
  stdout_mode: :line | :raw,
  stdin_mode: :line | :raw,
  interrupt_mode: :signal | {:stdin, binary()},
  pty?: boolean(),
  stdin?: boolean(),
  transport: term()
}

t()

@type t() :: %CliSubprocessCore.RawSession{
  event_tag: atom(),
  interrupt_mode: :signal | {:stdin, binary()},
  invocation: CliSubprocessCore.Command.t(),
  pty?: boolean(),
  receiver: pid(),
  stdin?: boolean(),
  stdin_mode: :line | :raw,
  stdout_mode: :line | :raw,
  transport: pid(),
  transport_api: module(),
  transport_ref: reference()
}

Functions

close_input(raw_session)

@spec close_input(t()) :: :ok | {:error, term()}

Closes stdin for EOF-driven subprocesses.

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

collect(session, timeout_ms \\ 30000)

@spec collect(t(), timeout()) ::
  {:ok, ExternalRuntimeTransport.Transport.RunResult.t()} | {:error, term()}

Collects session output until the subprocess exits.

The configured receiver must be the calling process so the core can consume its own transport events deterministically.

delivery_info(session)

@spec delivery_info(t()) :: CliSubprocessCore.RawSession.Delivery.t()

Returns stable mailbox-delivery metadata for the raw session.

force_close(raw_session)

@spec force_close(t()) :: :ok | {:error, term()}

Forces the subprocess down immediately.

info(session)

@spec info(t()) :: info_t()

Returns the latest raw session metadata snapshot.

interrupt(raw_session)

@spec interrupt(t()) :: :ok | {:error, term()}

Interrupts the subprocess according to the configured transport contract.

send_input(raw_session, data)

@spec send_input(t(), iodata()) :: :ok | {:error, term()}

Sends exact input bytes through the session transport.

start(invocation)

@spec start(CliSubprocessCore.Command.t()) :: {:ok, t()} | {:error, term()}

Starts an unlinked raw subprocess session from a prebuilt invocation.

start(arg1, arg2)

@spec start(String.t(), [String.t()]) :: {:ok, t()} | {:error, term()}

@spec start(
  CliSubprocessCore.Command.t(),
  keyword()
) :: {:ok, t()} | {:error, term()}

Starts an unlinked raw subprocess session from either an executable and argv list or a prebuilt invocation plus options.

start(command, args, opts)

@spec start(String.t(), [String.t()], keyword()) :: {:ok, t()} | {:error, term()}

start_link(invocation)

@spec start_link(CliSubprocessCore.Command.t()) :: {:ok, t()} | {:error, term()}

Starts a linked raw subprocess session from a prebuilt invocation.

start_link(arg1, arg2)

@spec start_link(String.t(), [String.t()]) :: {:ok, t()} | {:error, term()}

@spec start_link(
  CliSubprocessCore.Command.t(),
  keyword()
) :: {:ok, t()} | {:error, term()}

Starts a linked raw subprocess session from either an executable and argv list or a prebuilt invocation plus options.

start_link(command, args, opts)

@spec start_link(String.t(), [String.t()], keyword()) :: {:ok, t()} | {:error, term()}

status(raw_session)

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

Returns the transport status for the raw session.

stderr(raw_session)

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

Returns the stderr tail retained by the underlying transport.

stop(raw_session)

@spec stop(t()) :: :ok

Stops the subprocess transport.