35 lines
3.1 KiB
Markdown
35 lines
3.1 KiB
Markdown
# Hyperswarm and Protomux teardown (booter)
|
|
|
|
[Reference index →](README.md)
|
|
|
|
The stock booter ([`packages/bare-os-booter/index.js`](../../packages/bare-os-booter/index.js)) constructs a **`Hyperswarm`** instance with optional caps from host env (**`BARE_OS_SWARM_MAX_PEERS`**, **`BARE_OS_SWARM_MAX_CLIENT_CONNECTIONS`**, **`BARE_OS_SWARM_MAX_SERVER_CONNECTIONS`**, **`BARE_OS_SWARM_MAX_PARALLEL`** — see **`bareOsHyperswarmOptsFromEnv`**). Each inbound connection is wrapped in **`Protomux`** and registered on **`SwarmDisk`** (`**disk.addPeer(mux, socket)`**).
|
|
|
|
## Shutdown ordering
|
|
|
|
[`teardownBareOsBootResources`](../../packages/bare-os-booter/lib/bare-os-lifecycle-manager.js) runs in a **`finally`** block after **`executeKernel`** completes or throws:
|
|
|
|
1. **`disk.hdmsController.deactivate()`** when present — stops HDMS-driven replication surfaces before closing drives.
|
|
2. **`swarm.destroy()`** — tears down Hyperswarm; closes live streams so Protomux sessions end before Hyperdrive teardown (avoids native heap issues under Pear when drives close mid-stream).
|
|
3. **`disk.personalDrive.close()`** / **`disk.drive.close()`** — closes Hyperdrive handles after the swarm is down.
|
|
4. **`store.close()`** — closes the boot **Corestore** last.
|
|
|
|
Replication and mux teardown **before** drive close is intentional: closing a Hyperdrive while Protomux-framed replication is still active can corrupt native heaps on some Pear/macOS combinations (documented in **`bare-os-lifecycle-manager.js`**).
|
|
|
|
## Retry and peer wait
|
|
|
|
Until **`BARE_OS_OFFLINE_LKG_BOOT`** is used with a valid **`BARE_OS_LKG_SYSTEM_KEY_HEX`**, the booter waits (polling **~400 ms**) until at least one swarm peer connects or **`BARE_OS_BOOT_TIMEOUT_MS`** elapses. There is no automatic exponential backoff beyond that loop; operators raise the timeout or enable offline LKG for air-gapped boots.
|
|
|
|
## P2P-first note
|
|
|
|
There is **no central broker**: topic membership and peer discovery follow Hyperswarm + HyperDHT semantics. Socket-level retry is owned by the Holepunch stack; the booter does not implement an additional application-level reconnect loop after initial boot beyond **`swarm.join(topic)`** and the peer-wait loop above.
|
|
|
|
## `disk.os` after initd
|
|
|
|
After **`bare-initd`** starts, the booter attaches **`disk.os`** (**`createBareOsDiskOsBridge`**) for **local** Hyperdrive search and whitelisted `**bare_os.*` `execRpc**` ( **`disk_os_hints`**, **`replication_operator_sketch`**, cap-gated **`replication_operator_intent`**, etc.). The same payloads are reachable via stock **`ctx.bareOsHrpcRequest`** routes **`bare_os.disk_os_hints`**, **`bare_os.replication_operator_sketch`**, and **`bare_os.replication_snapshot`** when **`disk.os`** is wired. Teardown still follows the ordering above: **swarm down before drives**, so in-flight **`execRpc`** / replication should finish or time out before **`teardownBareOsBootResources`**.
|
|
|
|
## See also
|
|
|
|
- [`PEAR-RUN.md`](../PEAR-RUN.md) — channels and env
|
|
- [`environment-and-posix-appendix.md`](environment-and-posix-appendix.md) — **`BARE_OS_SWARM_*`**
|
|
- [`docs/architecture/architecture-data-flow.md`](architecture-data-flow.md) — end-to-end replication sketch
|