bare-stow-host-python

Host side of the bare-stow lifecycle for Python. The Python counterpart of bare-stow-host: it multiplexes a control channel and a user data channel over a byte transport to a stowed bundle, and layers readiness, termination, and exit reporting on top. Harnesses generated by bare-stow import it to drive the bundles they boot.

pip install bare-stow-host

Usage

import signal

from bare_sidecar import spawn
from bare_stow_host import wrap


async def main():
    sidecar = await spawn("index.bundle")

    ipc = wrap(sidecar, kill=lambda: sidecar.kill(signal.SIGKILL))

    await ipc.ready

    await ipc.write(b"hello")

    code = await ipc.terminate()

Any object with async read(), returning b"" once the transport has ended, and async write(data) can be wrapped, such as a Sidecar from bare-sidecar-python.

Whoever wraps a transport must call ipc.exited(code, signal) once the worker exits, such as when the process of a sidecar exits. A transport that ends without the worker saying why is held back until then, so that reads and ready fail with the exit code or signal instead of ending cleanly. A transport that fails waits up to grace for the exit in the same way, and the worker is killed if it doesn't come.

Protocol

Every frame is a 4-byte little-endian length followed by that many bytes: A 1-byte tag and the payload. The tag is 0x00 for a control frame, whose payload is a UTF-8 JSON object carrying its type, and 0x01 for a user data frame. See bare-stow-protocol for the control frames.

License

Apache-2.0