bacommon.msg package

Public message protocol definitions.

Effectively-public message types that travel across trust boundaries (e.g. basn↔sandbox). Co-located with the rest of bacommon because anything the sandbox can see is by definition public.

Submodules

bacommon.msg.basntosandbox module

Communication from basn to one of its sandboxed tasks.

class bacommon.msg.basntosandbox.ShutdownMessage

Bases: Message

Request the sandboxed task to gracefully shut itself down.

The (empty default) response acts as the ack — basn’s send_async resolves only after the sandbox’s handler returns, so the response IS the “shutdown complete” signal. basn awaits the response with a timeout; on timeout, falls through to the runsc kill SIGTERM ladder.

bacommon.msg.basntosandbox.get_protocol() → MessageProtocol

Get the protocol used in this communication.

basn sends these messages into a sandboxed task. The sandbox is NOT trusted with basn-side error tracebacks (could leak internals to untrusted code). Remember to run ‘make codegen’ after changes here.

bacommon.msg.sandboxtobasn module

Communication from a sandboxed task to its owning basn process.

class bacommon.msg.sandboxtobasn.LogBatchMessage(entries: list[LogEntry])

Bases: Message

Batched log entries from the sandboxed task.

Reuses efro.logging.LogEntry so basn-side handler can hand entries straight to its existing log routing.

entries: list[LogEntry]

class bacommon.msg.sandboxtobasn.ProbeResultMessage(name: str, result: ProbeResultType, detail: str = '')

Bases: Message

Structured result of one boundary probe run during sandbox startup.

Sent before ReadyMessage as the test-app’s startup phase runs. CI asserts directly against (name, result) pairs.

detail: str = ''

name: str

result: ProbeResultType

class bacommon.msg.sandboxtobasn.ProbeResultType(*values)

Bases: Enum

Outcome of a single boundary probe.

ALLOWED = 'a'

BLOCKED = 'b'

INFO = 'i'

class bacommon.msg.sandboxtobasn.ReadyMessage

Bases: Message

Sandbox has finished init and is ready for real traffic.

Single bootstrap signal; basn advances its state machine from CONNECTED to READY on first receipt. Duplicates dropped.

class bacommon.msg.sandboxtobasn.ShutdownReason(*values)

Bases: Enum

Why the sandboxed task is shutting itself down.

CLEAN_EXIT = 'c'

ERROR = 'e'

class bacommon.msg.sandboxtobasn.ShuttingDownMessage(reason: ShutdownReason, detail: str = '')

Bases: Message

Sandbox is shutting itself down (not in response to a basn request).

Lets basn distinguish clean self-shutdown from error/crash exits.

detail: str = ''

reason: ShutdownReason

class bacommon.msg.sandboxtobasn.StatBatchMessage(updates: list[StatUpdate])

Bases: Message

Batched stat updates.

updates: list[StatUpdate]

class bacommon.msg.sandboxtobasn.StatUpdate(name: str, value: float)

Bases: object

A single counter or gauge update from the sandbox.

name: str

value: float

bacommon.msg.sandboxtobasn.get_protocol() → MessageProtocol

Get the protocol used in this communication.

Sandbox payloads send these messages to the owning basn process. basn is trusted to see sandbox-side error tracebacks (helpful for debugging mod failures). Remember to run ‘make codegen’ after changes here.