49 lines
3.0 KiB
Markdown
49 lines
3.0 KiB
Markdown
# bare-os-protocol
|
||
|
||
Shared **wire format and constants** for the Bare operating system monorepo: Hyperswarm topic, 512-byte MBR layout, and Protomux **bare-os-v1** seed-channel message shapes.
|
||
|
||
**When to use:** depend on this package when building a **compatible seeder or booter**, fuzz-testing **MBR/topic** stability, or reusing **kernel feature bit** masks in tooling.
|
||
|
||
**Documentation:** [Concepts — P2P](../../docs/concepts/p2p-swarm-and-protomux.md) · [Protocol reference](../../docs/reference/package-bare-os-protocol.md) · [Handbook ch.3](../../handbook/03-protocol-and-disk.md) · [Kernel extensions](../../docs/reference/kernel-extensions.md).
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
T[bare-os-v1 topic]
|
||
C[Protomux channel]
|
||
M[MBR block 0]
|
||
T --> C
|
||
M --> H[Hyperdrive keys]
|
||
```
|
||
|
||
## What it provides
|
||
|
||
- **`PROTOCOL_NAME`, `TOPIC_STRING`** — Protomux channel name and swarm topic input string (`bare-os-v1`)
|
||
- **`topicKey()`** — 32-byte topic for `swarm.join()`
|
||
- **`BLOCK_SIZE`, `MBR_MAGIC`** — 512-byte MBR, magic `BIOS` at offset 0
|
||
- **`buildMbr` / `parseMbr`** — Pack/unpack primary + optional failover Hyperdrive keys
|
||
- **`setupSeedChannel`** — Wire Protomux messages 0–6 for RAM block reads, gossip bitfield, manifest path **search**, **RPC** (incl. `bare_os.capabilities` with **`bits`** … **`bits11`** when non-zero, typed errors for unknown RPC methods, `bare_os.replication_status`, `bare_os.replication_queue`, extended RPC short names in **`seed-rpc-methods.js`**, `bare_os.gossip`), and `drive.replicate`. Message 0/1 is role-agnostic: any peer with `localRAM` block `0` can answer MBR reads.
|
||
|
||
Subpath exports: `bare-os-protocol/constants.js`, `bare-os-protocol/messages` (compact-encoding schemas), `bare-os-protocol/kernel-feature-bits.js` (documented booter capability words **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_*`**; **`BARE_OS_KERNEL_FEATURE_BITS_DOC`** — see source; surfaced in **`/proc/bare_os_features`** and **`/proc/bare_os/`**), `bare-os-protocol/lib/seed-rpc-methods.js` (authoritative **`bare_os.*`** RPC name list for **`kernel_info`**), `bare-os-protocol/protocol-meta.js` (**`BARE_OS_PROTOCOL_PACKAGE_VERSION`** for the seed handshake).
|
||
|
||
## Consumers
|
||
|
||
- **[bare-os-seeder](../bare-os-seeder)** — builds MBR, serves block 0 over the channel, replicates the system Hyperdrive.
|
||
- **[bare-os-booter](../bare-os-booter)** — parses MBR from `SwarmDisk`, opens system drives, uses the same channel on the client side, and can mirror block `0` plus captured seed RPC snapshots after successful boot and eligibility checks.
|
||
|
||
## Tests
|
||
|
||
```bash
|
||
npm test -w bare-os-protocol
|
||
```
|
||
|
||
Runs `brittle-bare` against `test.js` (topic stability, MBR roundtrip, encodings).
|
||
|
||
## Dependencies
|
||
|
||
`b4a`, `compact-encoding`, `hypercore-crypto` (via constants/topic). No Hyperdrive or Hyperswarm here — this package stays small and testable.
|
||
|
||
## See also
|
||
|
||
- Repo root [README.md](../../README.md) and [protocol reference](../../docs/reference/package-bare-os-protocol.md) §10.
|
||
- [Handbook — Blueprints § protocol](../../handbook/02-blueprints.md) (high-level).
|