87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# Chapter 3 — Protocol, MBR, and SwarmDisk
|
||
|
||
Here we connect **bare-os-protocol** to what **seeder** and **booter** actually do on the wire and in RAM.
|
||
|
||
---
|
||
|
||
## Seeder lifecycle
|
||
|
||
1. Resolve **kernel root** (`BARE_OS_KERNEL_ROOT` or vendored `kernel/`).
|
||
2. Optionally **rebuild coreutils** when running under Node (`file:` URL) — skipped under Pear.
|
||
3. Open **Corestore** + **Hyperdrive**, **`stageKernelTree`**:
|
||
- `init.js` → `/boot/init.js`
|
||
- `bin/*` → `/bin/*`
|
||
- `etc/*` → `/etc/*`
|
||
4. Build **MBR** with `buildMbr(drive.key)` and store block **0** in a **`Map`** (`localRAM`).
|
||
5. **Hyperswarm** `join(topicKey())` and `join(drive.discoveryKey)`.
|
||
6. On each connection: **Protomux** + **`setupSeedChannel`**, which:
|
||
- Answers **read index** requests from `localRAM` (index `0` → MBR)
|
||
- Attaches **`drive.replicate(stream)`**
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant S as Seeder
|
||
participant W as Hyperswarm
|
||
participant B as Booter
|
||
S->>W: join topic + discoveryKey
|
||
B->>W: join topic
|
||
B->>S: mux connection
|
||
Note over B,S: Protomux bare-os-v1
|
||
B->>S: read block 0
|
||
S-->>B: MBR 512 bytes
|
||
B->>S: hyperdrive replicate
|
||
```
|
||
|
||
---
|
||
|
||
## Booter: from peers to Hyperdrive
|
||
|
||
**`SwarmDisk`** (booter) mirrors the seeder’s channel handlers:
|
||
|
||
- **`read(index)`** — if not local RAM, broadcast **msg 0** to peers, await **msg 1** (timeout).
|
||
- **`addPeer`** — open channel, replicate **system** (and later **personal**) drives on the mux stream.
|
||
|
||
**Boot path:**
|
||
|
||
1. Wait until **`disk.peers.size > 0`** or **boot timeout**.
|
||
2. **`parseMbr(await disk.read(0))`** → list of 32-byte keys.
|
||
3. For each key, try `Hyperdrive(store, key)` + replicate until **`/boot/init.js`** exists.
|
||
4. Initialize **personal drive** namespace and join its discovery key.
|
||
5. Hand off to **`executeKernel`**.
|
||
|
||
There is **intentionally** no “use my checkout’s `kernel/` if the network fails” path—the project forces you to think about **availability** of the swarm.
|
||
|
||
---
|
||
|
||
## Message IDs (reference)
|
||
|
||
Aligned with `packages/bare-os-protocol/lib/channel.js` and `swarm-disk.js`:
|
||
|
||
| ID | Direction | Purpose |
|
||
| ----- | -------------- | -------------------- |
|
||
| 0 | Client → peers | Read block by index |
|
||
| 1 | Peer → client | Data payload |
|
||
| 2 | Gossip stub | Bitfield buffer |
|
||
| 3 / 4 | Search req/res | Stub (empty matches) |
|
||
| 5 / 6 | RPC req/res | **`bare_os.version`** implemented; other methods return “not implemented” |
|
||
|
||
The **important** path for boot is **0/1** + **Hyperdrive replication** on the same socket.
|
||
|
||
---
|
||
|
||
## Personal drive replication
|
||
|
||
`SwarmDisk.initPersonalDrive` creates a **separate** Hyperdrive under a stable Corestore namespace and **`swarm.join(personalDrive.discoveryKey)`**. Your `$HOME` tree can therefore sync across **your** devices if peers share that discovery key—orthogonal to the **system** image key from the MBR.
|
||
|
||
---
|
||
|
||
## Failure modes you will see in the wild
|
||
|
||
- **Boot timeout** — no peer answered the topic (seeder not running, firewall, wrong network).
|
||
- **Invalid MBR** — corrupt block 0 or wrong magic; `parseMbr` throws.
|
||
- **Drive never completes** — replication stalled; check peer count and discovery key joins.
|
||
|
||
---
|
||
|
||
[← Blueprints](02-blueprints.md) · [Handbook home](README.md) · [Next: Booter runtime →](04-the-booter-runtime.md)
|