Metadata-Version: 2.5
Name: bare-stow-host
Version: 0.2.1
Summary: Host side of the bare-stow lifecycle for Python
Project-URL: Homepage, https://github.com/holepunchto/bare-stow-host-python
Project-URL: Repository, https://github.com/holepunchto/bare-stow-host-python
Project-URL: Issues, https://github.com/holepunchto/bare-stow-host-python/issues
Author: Holepunch
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# bare-stow-host-python

Host side of the [bare-stow](https://github.com/holepunchto/bare-stow) lifecycle for Python. The Python counterpart of [bare-stow-host](https://github.com/holepunchto/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.

```sh
pip install bare-stow-host
```

## Usage

```python
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](https://github.com/holepunchto/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](https://github.com/holepunchto/bare-stow-protocol) for the control frames.

## License

Apache-2.0
