Forcola.Shim (forcola v0.3.0)

Locates and speaks to the forcola_shim binary.

The shim is a Rust port program (source under native/forcola_shim). Release builds are published per target to GitHub Releases and fetched at compile time with SHA256 verification, so consumers need no Rust toolchain; a locally built binary in priv/ takes precedence during development.

Wire protocol (BEAM <-> shim), v0, documented in full in native/forcola_shim/src/main.rs:

Frames are {:packet, 4}-style: a 4-byte big-endian length prefix (handled by the Erlang port itself), then a 1-byte tag, then the payload. This module owns the tag constants and the JSON payload shapes for SPAWN/EXIT/ERROR; Forcola.run/2 drives the protocol.

Summary

Functions

decode_contained(payload)

Decodes the contained flag from an EXIT frame payload.

decode_error(payload)

Decodes an ERROR frame payload into its reason string.

decode_exit(payload)

Decodes an EXIT frame payload into {status_or_signal, timed_out}.

encode_credit(bytes)

Encodes a CREDIT frame payload: an 8-byte big-endian byte count.

encode_spawn(argv, opts)

Encodes a SPAWN frame payload from Forcola.run/2 options.

open()

Opens the shim binary as a port, framed with {:packet, 4}.

path()

Absolute path to the shim binary for the current target.

send_frame(port, tag, payload \\ "")

Sends a tagged frame to the shim port.

Functions

decode_contained(payload)

@spec decode_contained(binary()) :: boolean()

Decodes the contained flag from an EXIT frame payload.

true when Linux cgroup v2 containment was actually active for the run; false on the default path, on fallback (macOS, no cgroup v2, or no delegated subtree), and whenever the field is absent (older shim). Reports which kill mechanism was used.

decode_error(payload)

@spec decode_error(binary()) :: String.t()

Decodes an ERROR frame payload into its reason string.

decode_exit(payload)

@spec decode_exit(binary()) ::
  {non_neg_integer() | {:signal, non_neg_integer()}, boolean()}

Decodes an EXIT frame payload into {status_or_signal, timed_out}.

encode_credit(bytes)

@spec encode_credit(non_neg_integer()) :: binary()

Encodes a CREDIT frame payload: an 8-byte big-endian byte count.

Grants the shim's stdout pump that many more bytes of read budget under backpressure. Only sent when the stream opted into backpressure via :window_bytes; see Forcola.Stream.lines/2.

encode_spawn(argv, opts)

@spec encode_spawn(
  term(),
  keyword()
) :: binary()

Encodes a SPAWN frame payload from Forcola.run/2 options.

Shared by all four modes. Besides :cd/:env/:merge_stderr/:timeout_ms/ :kill_grace_ms and the pty options, it threads :user and :group (each a string name or an integer id) through to the shim so the child can be run as a different user; see Forcola.run/2 for the semantics.

:cgroup opts into Linux cgroup v2 containment. Only added to the payload when truthy, so the default SPAWN payload is unchanged; the shim defaults it to false when the key is absent. See Forcola.run/2 for the Linux-only, delegation-required, graceful-fallback semantics.

:window_bytes opts into demand-driven backpressure on the child's stdout (see Forcola.Stream.lines/2). Only added to the payload when present, so the default SPAWN payload is unchanged; the shim gates its stdout pump when the field is present and reads eagerly otherwise.

open()

@spec open() :: {:ok, port()} | {:error, :not_found}

Opens the shim binary as a port, framed with {:packet, 4}.

The caller owns the returned port: send it SPAWN/STDIN/EOF/KILL frames via send_frame/2 and receive {port, {:data, <<tag, payload::binary>>}} messages for STDOUT/STDERR/EXIT/ERROR frames.

path()

@spec path() :: {:ok, Path.t()} | {:error, :not_found}

Absolute path to the shim binary for the current target.

Returns {:error, :not_found} if no binary has been built or downloaded yet.

send_frame(port, tag, payload \\ "")

@spec send_frame(port(), non_neg_integer(), iodata()) :: true

Sends a tagged frame to the shim port.