Skip to content
Ekrooh

P2P Folder Stack

The p2p stack is already decided — see research/p2p-folder-stack.md in the framework repo for the full analysis. Summary:

  • Hyperdrive on one Corestore per app. A folder is a hyperdrive: drive.key is the share key, drive.discoveryKey is the Hyperswarm topic, and the single-worklet-per-app model maps 1:1 onto “one Corestore per application”.
  • Incremental sync. Hyperdrive splits blobs into 64 KB blocks; sparse replication pulls only requested ranges (drive.createReadStream(start, end)); drive.watch / drive.diff for incremental metadata; mirror-drive for whole-folder diffing.
  • v1 is single-writer. The folder’s creator owns the writer keypair and the write keys; invited members are readers who also seed. “Everyone can add” later uses the documented group pattern: each member has their own drive and the creator mounts it into the folder drive (my-group/userA/docs).
  • Storage layout. One Corestore dir per app — metadata bee core + content blobs core, all in RocksDB-backed storage.

Wiring it into a worklet entry

Section titled “Wiring it into a worklet entry”
import {
  createWorkletRuntime,
  resolveWorkletConfig,
} from '@ekrooh/bare/runtime';
import Corestore from 'corestore';
import Hyperdrive from 'hyperdrive';
import Hyperswarm from 'hyperswarm';


const runtime = createWorkletRuntime(resolveWorkletConfig());
const { storage } = runtime.config;


if (storage) {
  const store = new Corestore(storage);
  const drive = new Hyperdrive(store); // creator: keys from drive.key
  const swarm = new Hyperswarm();
  swarm.join(drive.discoveryKey);
  swarm.on('connection', (conn) => store.replicate(conn));
}

Known gaps (from the research doc)

Section titled “Known gaps (from the research doc)”
  • RocksDB weight on mobile; Android backgrounding (the worklet pauses when the app does); iOS sockets for Hyperswarm. These are flagged in research/p2p-folder-stack.md — no duplicate findings here.

Verify the stack on a target

Section titled “Verify the stack on a target”

The framework repo ships core/p2p-verify.core.ts — a worklet that boots and exercises Corestore, Hyperdrive, and Hyperswarm end-to-end (run on the iOS simulator via P2PVerifyTest, on an Android emulator via the reference app’s P2PVerifyTest instrumentation test in mode=self, or locally via npm run smoke:p2p). Since issue #28 the smoke performs a real connect: it brings up a local ephemeral DHT bootstrap, joins two in-process swarms on one topic, completes the Noise secret-stream handshake, and asserts an encrypted message round-trip — peers=0-style “works in theory” false positives are no longer possible. Since issue #41 it also replicates a peer’s drive: a creator announces its drive and serves it; a reader joins the topic client-only, opens the drive by key, ready()s it, and reads a photo — the exact flow the on-device photo app timed out on. A green run on a runtime proves that platform can do peer reads; a red run reproduces the timeout. The full peer-drive gate runs on the macOS smoke and the iOS simulator; the Android emulator instrumentation test uses mode=self (self-reads) because real DHT peer discovery is not a stable gate under the software-rendered x86_64 CI emulator.