5.0 KiB
Tech choices
Recommendations for collection, streaming, visualization, and reusable libraries.
Transport & identity
| Choice | Why |
|---|---|
| HyperDHT | Same peer identity + hole-punching model as PearDock |
| protomux-rpc | Multiplexed request/response + server push events |
| compact-encoding JSON | Fast enough for control + 1s metric batches; shared with template |
| Ed25519 seeds | Agent address = pubkey; admin proof via HMAC from seed |
Streaming metrics
MVP uses protomux-rpc event pushes (push:metrics) with per-session subscribe + throttle.
If fleet scale demands it later:
- Dedicated protomux channel with binary packs (Float64 arrays)
- Hypercore / Hyperbee for durable streams a parent can replicate
- Extract a shared
pearrpcpackage (session middleware + hot-path helpers) from this template
For MVP, JSON pushes keep the stack simple and debuggable.
Bare / Pear runtime (no Node builtins)
Pear’s native runtime is Bare. Do not rely on Node core modules existing at runtime.
| Pattern | Use |
|---|---|
package.json imports map |
fs / os / path / crypto / events / http / … → bare-* under "bare" condition (same idea as PearDock / pear-docs node-compat) |
bare-node-runtime/global |
Loaded first in Bare entrypoints (bin/peardata-server.mjs, index.js) for process / Buffer / fetch |
b4a |
Buffers in shared/ and wire code (prefer over Node Buffer) |
Direct bare-* |
Optional for new Bare-first modules |
Keep bare-safe: shared/, client/, Pear app.js / index.js / ui/.
Agent (server/): may keep Node-style import names; under Bare they resolve via the imports map. Boot via bin/peardata-server.mjs.
Do not use if (isBare) require('bare-fs') else require('fs') branches for packable apps — Bare’s packer walks both sides. Prefer import maps.
Collection
| Option | Verdict |
|---|---|
os + /proc via bare-os / bare-fs (chosen) |
Hybrid Node+Bare; low overhead |
node-os-utils |
Convenient but extra dep / less control |
Native bindings (systeminformation, etc.) |
Higher fidelity; consider Phase 2 for Windows depth |
Shell out to vmstat/iostat |
Avoid on hot path |
Linux: /proc/meminfo, /proc/loadavg, /proc/net/dev, /proc/diskstats
macOS/Windows: os fallbacks (CPU%, freemem, loadavg where available); I/O/net rates may be zero until platform collectors land.
Target overhead: single timer, no child processes per tick, ring buffers only.
Storage
| Tier | Implementation |
|---|---|
| Hot | In-memory ring (server/services/store.js) |
| Warm | HyperDB + Corestore (+ optional Hyperswarm) — see STORAGE-HYPERDB.md |
| Policy | Data Manager (retention.json, default 1y warm age, auto-prune) — server/services/retention.js |
| HA / multi-writer parents | Autobase with HyperDB view (extension: false) |
| Avoid | SQLite as primary P2P store; copying corestore folders as “backup” |
HyperDB engines
| Engine | Sync | Use |
|---|---|---|
HyperDB.bee(core, spec) |
P2P via Hypercore | Agent meta + warm history + linked peers |
HyperDB.rocks(path, spec) |
Local only | Fast local index / desktop cache (pear-hyperdb style) |
Visualization (desktop)
| Option | Verdict |
|---|---|
| Canvas sparklines (chosen MVP) | No extra deps inside Pear; snappy for 1s updates |
| uPlot | Best next step for interactive charts (tiny, fast) |
| Chart.js / ECharts | Heavier; fine for secondary views |
| Grafana via REST | External; use /api/v3/data + Prometheus export |
REST
http module (no Express) — under Bare this is bare-http1 via import maps. Small attack surface for agent-style GET APIs. Default bind 127.0.0.1:18888 (PEARDATA_REST_PORT).
Packaging
| Piece | Approach |
|---|---|
| Agent | Node 20+ or Bare (bin/peardata-server.mjs), systemd unit deploy/peardata.service |
| Desktop | Pear (pear-electron + pear-bridge) with Bare-ready imports |
| Invites | pd1. tokens (PearDock-style) |
| Installer | scripts/install.sh (rolling binaries; journal + Docker socket when detected; see RELEASE.md) |
Reusable library extraction (recommended later)
From this codebase / PearDock patterns:
| Package | Contents |
|---|---|
@pear/rpc-session or pearrpc |
PeerSession middleware, ACL, rate limit, audit hooks |
pear-metrics-wire |
Context/chart catalog types + query args |
pear-invite |
pd1. encode/decode + capability HMAC |
PearData is AGPL-3.0-only (same family as PearDock). Prefer composing via public APIs rather than vendoring third-party AGPL trees wholesale unless intentionally unifying under AGPL.
Integration seams
| Ecosystem | Seam |
|---|---|
| PearDock | Container chart plugin reading dock RPC |
| PearVirt | VM CPU/mem contexts |
| HoneyPeer | Optional agent directory announcements |
| BareOS | Bare-compatible collector build |
| Holesail | Tunnel REST or future agent web UI |