sergio
d962fe4601
- README.md en crates/modules/shipote/ como entry point. - docs/ARCHITECTURE.md — 11 crates, capas, decisiones (O_CLOEXEC, dirty AtomicBool, pipeline restart entero, etc.) + snapshot versioning. - docs/CLI.md — referencia comando por comando, flags, env vars. - docs/RECIPES.md — specs TOML para workspaces y pipelines típicos. - docs/DEVELOPMENT.md — compilar, correr daemon/shell/CLI, tests, smoke E2E manual, debugging FDs. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
74 lines
3.7 KiB
Markdown
74 lines
3.7 KiB
Markdown
# shipote
|
|
|
|
**Runtime de espacios aislados con flujo tipado** dentro del fractal brahman.
|
|
|
|
shipote no es un shell POSIX. Es un daemon long-running que:
|
|
|
|
- Aísla procesos en **Workspaces** (cada uno con su `SomaSpec`: namespaces, cgroup, rlimits).
|
|
- Encadena comandos en **Pipelines** (DAG con fan-out, fan-in, taps, replay buffer).
|
|
- **Discierne contenido** sobre cada flow (detecta `application/json`, `text/markdown`, magic bytes, hasta `brahman:card`).
|
|
- Expone **data plane** real: subscribers externos se conectan a Unix sockets y reciben los bytes del stream.
|
|
- Se integra al ecosistema vía `brahman-sidecar` (anuncia Cards al broker).
|
|
|
|
```
|
|
┌─────────────┐
|
|
│ shipote │ daemon long-running
|
|
│ -daemon │ $XDG_RUNTIME_DIR/shipote.sock
|
|
└──────┬──────┘
|
|
│ admin protocol (postcard)
|
|
┌─────────────────┼─────────────────┐
|
|
│ │ │
|
|
┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
|
|
│ shipote │ │ shipote- │ │ HTTP / │
|
|
│ (CLI) │ │ shell │ │ custom │
|
|
│ │ │ (GUI) │ │ (futuro) │
|
|
└───────────┘ └───────────┘ └───────────┘
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```sh
|
|
# 1. Compilar
|
|
cargo build -p shipote-daemon -p shipote-cli
|
|
|
|
# 2. Arrancar daemon (en una terminal):
|
|
SHIPOTE_LOG=info ./target/debug/shipote-daemon
|
|
|
|
# 3. En otra terminal:
|
|
./target/debug/shipote health
|
|
./target/debug/shipote workspace create demo.toml
|
|
./target/debug/shipote run -w <ws-id> /bin/echo -- hola
|
|
```
|
|
|
|
## Estado actual
|
|
|
|
- **11 crates** en el monorepo. Ver [ARCHITECTURE.md](docs/ARCHITECTURE.md).
|
|
- **85 tests** pasando.
|
|
- Compatible con cualquier supervisor (`ente-incarnate` es reusable — no requiere ser PID 1).
|
|
|
|
## Documentación
|
|
|
|
- [**ARCHITECTURE.md**](docs/ARCHITECTURE.md) — qué crates lo componen, cómo se conectan, decisiones clave.
|
|
- [**CLI.md**](docs/CLI.md) — referencia de comandos del binario `shipote`.
|
|
- [**RECIPES.md**](docs/RECIPES.md) — specs TOML de workspaces y pipelines con casos prácticos.
|
|
- [**DEVELOPMENT.md**](docs/DEVELOPMENT.md) — cómo correr daemon, GUI, tests, snapshot.
|
|
|
|
## Acoplamiento con el resto del monorepo
|
|
|
|
| Reusa | Propósito |
|
|
|---|---|
|
|
| `ente-incarnate` (extraído de `ente-soma` en Fase 0) | clone(2) + namespaces + cgroup + rlimits |
|
|
| `brahman-card` | tipos `Card`, `SomaSpec`, `Flow`, `TypeRef` |
|
|
| `brahman-sidecar` + `brahman-handshake` | anuncio al broker |
|
|
| `ente-snapshot` filosofía | persistencia (shipote tiene su propio `ShipoteSnapshot` v4) |
|
|
| `yahweh-launcher` + widgets | GUI `shipote-shell` |
|
|
| `shipote-discern` ← usado por | `yahweh-provider-fs` (mime per archivo) y `nouser-core::cluster::pick_lens` |
|
|
|
|
## Limitaciones declaradas
|
|
|
|
- **`mount/pid/net/uts/ipc/cgroup` namespaces** requieren `CAP_SYS_ADMIN` o combo con `CLONE_NEWUSER`.
|
|
- **`user` namespace** puede estar bloqueado por sysctl o LSM (apparmor/selinux).
|
|
- **`cgroup` v2 limits** (memory.max, pids.max) requieren delegation. Sin delegation, accounting funciona pero el kernel no enforce.
|
|
- **Pipeline restart** preserva spec pero **no ULIDs** del pipeline_id (cada relaunch genera uno nuevo).
|
|
- **Replay buffer broadcast**: subscribers tarde reciben el snapshot del replay (cap configurable por bytes o chunks), pero pueden perder chunks intermedios si el ring rota antes de conectarse.
|