@bolloon/bolloon-agent 0.4.23 → 0.4.25

package/dist/ios/mobile-orbit.js

@@ -0,0 +1,268 @@
+/**
+ * 手机端 OrbitDB 本地副本 (库级复制 + 双向 merge)
+ *
+ *   电脑端跑 helia + OrbitDB (@orbitdb/core), 手机端(WebView)跑不了完整 libp2p 栈,
+ *   故手机端维护**同一批 store 的本地副本**:
+ *     - 拉: GET 电脑端 store 全量条目 → 按确定性 LWW 规则合并进本地副本
+ *     - 推: 本地独有的 / 本地胜出的条目 → POST 回电脑端 → 电脑端 put 进 OrbitDB
+ *           (OrbitDB keyvalue 本身是 op-log 上的 LWW, 写穿后由它负责跨设备传播)
+ *
+ *   合并规则 (确定性, 两端各自算必得同一结果 → 收敛):
+ *     ① 两边内容哈希相同 → 无变化
+ *     ② 值内时间戳 (updatedAt/timestamp/ts) 大者胜
+ *     ③ 时间戳相同 → 内容哈希字典序大者胜
+ *
+ *   本地副本是**离线可用**的: 断网也能读上次同步下来的全部数据.
+ */
+const PREFIX = 'bolloon_orbit_replica:';
+const URL_KEY = 'bolloon_desktop_base_url';
+function ls() {
+    try {
+        return typeof localStorage !== 'undefined' ? localStorage : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ============ 纯函数: 规范化 / 哈希 / 时间戳 ============
+/** 递归键排序的稳定 JSON (同内容必得同串) */
+export function stableJson(v) {
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v ?? null);
+    if (Array.isArray(v))
+        return '[' + v.map(stableJson).join(',') + ']';
+    const keys = Object.keys(v).sort();
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + stableJson(v[k])).join(',') + '}';
+}
+/** 内容哈希 (djb2, 手机端自足; 只用于同端两值比较 → 不需要跨端一致) */
+export function hashValue(v) {
+    const s = stableJson(v);
+    let h = 5381;
+    for (let i = 0; i < s.length; i++)
+        h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+    return (h >>> 0).toString(16) + ':' + s.length.toString(16);
+}
+/** 值内时间戳 (没有 → 0, 交给哈希序兜底) */
+export function valueTs(v) {
+    if (!v || typeof v !== 'object')
+        return 0;
+    const c = [v.updatedAt, v.timestamp, v.ts, v.createdAt];
+    for (const x of c) {
+        if (typeof x === 'number' && isFinite(x))
+            return x;
+        if (typeof x === 'string') {
+            const t = Date.parse(x);
+            if (!isNaN(t))
+                return t;
+        }
+    }
+    return 0;
+}
+/** 确定性胜负: 远端内容是否该覆盖本地 */
+export function remoteWins(local, remoteValue, remoteHash) {
+    if (local.hash === remoteHash)
+        return false;
+    const rTs = valueTs(remoteValue);
+    if (rTs !== local.ts)
+        return rTs > local.ts;
+    return remoteHash > local.hash;
+}
+/**
+ * 合并一个 store: 本地副本 + 远端条目 → 新副本 / 需推回的条目 / 统计.
+ * 纯函数 (不改入参) — 两端各自调用必得同一结果.
+ */
+export function mergeStore(local, remote, origin = 'desktop') {
+    const merged = {};
+    for (const [k, e] of Object.entries(local || {}))
+        merged[k] = { ...e };
+    let applied = 0;
+    let kept = 0;
+    const remoteHash = new Map();
+    for (const r of remote || []) {
+        if (!r || typeof r.key !== 'string')
+            continue;
+        const h = hashValue(r.value);
+        remoteHash.set(r.key, h);
+        const cur = merged[r.key];
+        if (!cur) {
+            merged[r.key] = { value: r.value, hash: h, ts: valueTs(r.value) || Date.now(), origin };
+            applied++;
+            continue;
+        }
+        if (remoteWins(cur, r.value, h)) {
+            merged[r.key] = { value: r.value, hash: h, ts: valueTs(r.value) || Date.now(), origin };
+            applied++;
+        }
+        else if (cur.hash !== h)
+            kept++;
+    }
+    // 本地独有 / 本地胜出 → 推回电脑端
+    const pushed = [];
+    for (const [k, e] of Object.entries(merged)) {
+        const rh = remoteHash.get(k);
+        if (rh === undefined || rh !== e.hash)
+            pushed.push({ key: k, value: e.value });
+    }
+    return { merged, pushed, applied, kept };
+}
+// ============ 本地副本读写 ============
+export function getReplica(name) {
+    try {
+        const raw = ls()?.getItem(PREFIX + name);
+        if (!raw)
+            return { name, entries: {}, lastSyncTs: 0 };
+        const r = JSON.parse(raw);
+        return { name, address: r.address, entries: r.entries || {}, lastSyncTs: r.lastSyncTs || 0 };
+    }
+    catch {
+        return { name, entries: {}, lastSyncTs: 0 };
+    }
+}
+export function saveReplica(r) {
+    try {
+        ls()?.setItem(PREFIX + r.name, JSON.stringify(r));
+    }
+    catch { /* 存储满 → 忽略 */ }
+}
+/** 手机端本地写 (离线可写): 时间戳取当前 → 同步时胜出并推回电脑端 */
+export function replicaPut(name, key, value) {
+    const r = getReplica(name);
+    r.entries[key] = { value, hash: hashValue(value), ts: Date.now(), origin: 'phone' };
+    saveReplica(r);
+    return r;
+}
+export function replicaAll(name) {
+    const r = getReplica(name);
+    return Object.entries(r.entries).map(([key, e]) => ({ key, value: e.value, hash: e.hash }));
+}
+export function replicaGet(name, key) {
+    const e = getReplica(name).entries[key];
+    return e ? e.value : null;
+}
+/** 已复制的 store 名列表 (记住曾经同步过的) */
+export function replicaNames() {
+    const out = [];
+    try {
+        const s = ls();
+        if (!s)
+            return out;
+        for (let i = 0; i < s.length; i++) {
+            const k = s.key(i);
+            if (k && k.startsWith(PREFIX))
+                out.push(k.slice(PREFIX.length));
+        }
+    }
+    catch { /* 忽略 */ }
+    return out;
+}
+export function replicaStats() {
+    const names = replicaNames();
+    let entries = 0;
+    let lastSyncTs = 0;
+    for (const n of names) {
+        const r = getReplica(n);
+        entries += Object.keys(r.entries).length;
+        lastSyncTs = Math.max(lastSyncTs, r.lastSyncTs || 0);
+    }
+    return { stores: names.length, entries, lastSyncTs, names };
+}
+// ============ 与电脑端复制 ============
+function baseUrlOf(baseUrl) {
+    try {
+        return String(baseUrl || ls()?.getItem(URL_KEY) || '').trim().replace(/\/+$/, '');
+    }
+    catch {
+        return '';
+    }
+}
+/** 列出电脑端可复制的 store */
+export async function listDesktopStores(opts = {}) {
+    const base = baseUrlOf(opts.baseUrl);
+    if (!base)
+        return { ok: false, stores: [], error: '未配置电脑端地址' };
+    const f = opts.fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+    if (!f)
+        return { ok: false, stores: [], error: '当前环境无 fetch' };
+    try {
+        const r = await f(`${base}/api/orbitdb/stores`);
+        if (!r.ok)
+            return { ok: false, stores: [], error: `电脑端返回 ${r.status}` };
+        const j = await r.json();
+        return { ok: true, stores: (j && j.stores) || [] };
+    }
+    catch (e) {
+        return { ok: false, stores: [], error: e?.message || String(e) };
+    }
+}
+/** 复制单个 store: 拉 → 合并 → 推回. 幂等, 反复调用安全. */
+export async function replicateStore(name, opts = {}) {
+    const base = baseUrlOf(opts.baseUrl);
+    if (!base)
+        return { ok: false, store: name, error: '未配置电脑端地址' };
+    const f = opts.fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+    if (!f)
+        return { ok: false, store: name, error: '当前环境无 fetch' };
+    try {
+        // ① 拉电脑端全量
+        const gr = await f(`${base}/api/orbitdb/entries?name=${encodeURIComponent(name)}`);
+        if (!gr.ok)
+            return { ok: false, store: name, error: `电脑端返回 ${gr.status}` };
+        const gj = await gr.json();
+        if (!gj || gj.ok === false)
+            return { ok: false, store: name, error: (gj && gj.error) || '读取失败' };
+        const remote = Array.isArray(gj.entries) ? gj.entries : [];
+        // ② 合并进本地副本
+        const local = getReplica(name);
+        const { merged, pushed, applied, kept } = mergeStore(local.entries, remote);
+        const next = { name, address: gj.address || local.address, entries: merged, lastSyncTs: Date.now() };
+        saveReplica(next);
+        // ③ 推回本地胜出/独有条目 (电脑端 put → OrbitDB 负责后续跨设备传播)
+        let pushedN = 0;
+        if (pushed.length) {
+            const pr = await f(`${base}/api/orbitdb/merge`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ name, entries: pushed }),
+            });
+            if (!pr.ok)
+                return { ok: false, store: name, error: `推回失败 ${pr.status}`, pulled: remote.length, applied, kept };
+            pushedN = pushed.length;
+        }
+        return { ok: true, store: name, pulled: remote.length, pushed: pushedN, applied, kept, total: Object.keys(merged).length };
+    }
+    catch (e) {
+        return { ok: false, store: name, error: e?.message || String(e) };
+    }
+}
+/** 复制电脑端全部 store (登录后自动 / 手动同步走这里) */
+export async function replicateAll(opts = {}) {
+    const detail = [];
+    let names = opts.stores;
+    if (!names) {
+        const l = await listDesktopStores(opts);
+        if (!l.ok)
+            return { ok: false, stores: 0, pulled: 0, pushed: 0, entries: 0, error: l.error, detail };
+        names = l.stores.map((s) => s.name).filter(Boolean);
+    }
+    // 本地已有副本的 store 也要同步 (电脑端列表可能暂时读不到 → 保守保留)
+    const all = Array.from(new Set([...(names || []), ...replicaNames()]));
+    let pulled = 0;
+    let pushed = 0;
+    let entries = 0;
+    for (const n of all) {
+        const r = await replicateStore(n, opts);
+        detail.push(r);
+        if (r.ok) {
+            pulled += r.pulled || 0;
+            pushed += r.pushed || 0;
+            entries += r.total || 0;
+        }
+    }
+    const ok = detail.some((d) => d.ok);
+    return { ok, stores: all.length, pulled, pushed, entries, error: ok ? undefined : (detail[0] && detail[0].error), detail };
+}
+export default {
+    stableJson, hashValue, valueTs, remoteWins, mergeStore,
+    getReplica, saveReplica, replicaPut, replicaAll, replicaGet, replicaNames, replicaStats,
+    listDesktopStores, replicateStore, replicateAll,
+};

package/dist/ios/mobile-p2p.js

@@ -21,9 +21,16 @@ import { gossipsub } from '@libp2p/gossipsub';
 import { circuitRelayTransport } from '@libp2p/circuit-relay-v2';
 import { ping } from '@libp2p/ping';
 import { multiaddr as createMultiaddr } from '@multiformats/multiaddr';
+/**
+ * 2026-09-11: relay v2 的 hop 协议 —— 中继在 identify 里广播它。
+ * 客户端认证「对端是中继」就靠这个协议名 (@libp2p/circuit-relay-v2 RELAY_V2_HOP_CODEC)。
+ */
+export const RELAY_HOP_PROTOCOL = '/libp2p/circuit/relay/0.2.0/hop';
 let node = null;
 let state = { connected: false, peerCount: 0, peerIds: [] };
 const msgHandlers = [];
+/** 中继预约结果 (最近一次) */
+let relayReservationResults = [];
 /** 持久化好友地址 (localStorage), 供 addMobilePeer 写入 + startMobileP2P 自动重连 */
 let peerAddrs = [];
 function loadPeerAddrs() {
@@ -46,7 +53,18 @@ export async function startMobileP2P(cfg = {}) {
     if (node)
         return state;
     try {
+        // 已知的中继 → 直接作为「configured」listen 地址 (传输层在 start 里就会预约,
+        // 不依赖 identify → relay discovery 拓扑的时机)。
+        const relayListen = (cfg.relayAddrs || [])
+            .map((a) => (a || '').trim().replace(/\/p2p-circuit\/?$/, ''))
+            .filter((a) => /\/p2p\/[^/]+$/.test(a))
+            .map((a) => `${a}/p2p-circuit`);
         node = await createLibp2p({
+            // 2026-09-11: 手机唯一的「可被拨入」途径 = 向中继预约。
+            // listen /p2p-circuit 会在传输层 reserveRelay() 一个待预约名额; 之后只要连上
+            // 一个广播了 hop 协议的中继, 就会自动预约并拿到 <relay>/p2p-circuit/p2p/<本机>。
+            // (WebView 不能 listen ip4/ip6 → 只有这一类 listen 项是有意义的。)
+            addresses: { listen: ['/p2p-circuit', ...relayListen] },
             transports: [webSockets(), circuitRelayTransport()],
             connectionEncrypters: [noise()],
             streamMuxers: [yamux()],
@@ -108,6 +126,20 @@ export async function startMobileP2P(cfg = {}) {
                 console.warn(`[mobile-p2p] failed to dial saved ${addr}:`, String(e).slice(0, 100));
             }
         }
+        // 中继预约 (手机唯一的入站途径): 拨上中继还不够 —— 必须真的预约到名额,
+        // 才会有 <relay>/p2p-circuit/p2p/<本机> 这个可拨入地址。
+        // relayAddrs 已在 createLibp2p 的 addresses.listen 里作为 configured 中继 → start 时
+        // 传输层已经预约; 这里只对「还没拿到地址」的中继再补一次运行时预约 (兜底)。
+        for (const addr of cfg.relayAddrs || []) {
+            if (getMobileCircuitAddrs().length > 0)
+                break;
+            const r = await reserveMobileRelay(addr);
+            console.log(`[mobile-p2p] relay reserve ${addr} → ok=${r.ok} circuitAddrs=${r.circuitAddrs.length}` +
+                (r.error ? ` err=${String(r.error).slice(0, 140)}` : ''));
+        }
+        if (getMobileCircuitAddrs().length > 0) {
+            console.log(`[mobile-p2p] 可拨入地址: ${getMobileCircuitAddrs().join(' , ')}`);
+        }
         refreshState();
         return state;
     }
@@ -214,6 +246,97 @@ export function getMobileP2PConnections() {
 export function listMobilePeerAddrs() {
     return [...peerAddrs];
 }
+// ─────────────────── 2026-09-11: 中继预约 (手机唯一的入站途径) ───────────────────
+/** 手机只能拨 ws/wss → 可拨入地址里带 ws 段的排前面 (UI 只展示第一条) */
+const wsFirstRank = (a) => {
+    const parts = a.split('/');
+    return parts.includes('ws') || parts.includes('wss') ? 0 : 1;
+};
+/**
+ * 本机**可拨入地址** —— getMultiaddrs() 里带 `/p2p-circuit` 的项。
+ * 形如 `/ip4/192.168.1.5/tcp/8765/ws/p2p/<中继PeerId>/p2p-circuit/p2p/<本机PeerId>`。
+ * 没有可用中继时返回 `[]` —— 这是**正常**的 (只代表暂时不能被别人拨入), 不是失败。
+ * ws/wss 地址排在前面 (WebView 拨不了裸 tcp)。
+ */
+export function getMobileCircuitAddrs() {
+    if (!node)
+        return [];
+    try {
+        return (node.getMultiaddrs() || [])
+            .map((a) => (typeof a?.toString === 'function' ? a.toString() : String(a)))
+            .filter((a) => a.includes('/p2p-circuit'))
+            .sort((a, b) => wsFirstRank(a) - wsFirstRank(b));
+    }
+    catch {
+        return [];
+    }
+}
+/** 已经预约上的中继 PeerId 列表 (从 /p2p-circuit 地址里解析中继那一段) */
+export function getMobileRelays() {
+    const out = [];
+    for (const a of getMobileCircuitAddrs()) {
+        const head = a.split('/p2p-circuit')[0] || '';
+        const ids = head.match(/\/p2p\/([^/]+)/g) || [];
+        const last = ids[ids.length - 1];
+        const relay = last ? last.slice('/p2p/'.length) : '';
+        if (relay && !out.includes(relay))
+            out.push(relay);
+    }
+    return out;
+}
+/** 最近一次各中继地址的预约结果 (UI 用来显示「预约失败: 原因」) */
+export function getMobileRelayReservations() {
+    return relayReservationResults.map((r) => ({ ...r }));
+}
+/**
+ * 显式向一个中继预约 (circuit relay v2 reservation)。
+ *
+ * ⚠️ 血的教训 (2026-09-11, 实测): **js-libp2p 3.x 的 node 上没有 `listen()` 方法**
+ * (`libp2p.d.ts` 只有 dial/start/stop/…; listen 地址只能在 createLibp2p 的
+ * `addresses.listen` 里给)。所以运行时新增中继的正确 API 是
+ * `node.components.transportManager.listen([ma])` —— 这正是 circuit-relay 传输
+ * 自己在 `onStop` 里用的那一层 (内部但公开, interface-internal 的 TransportManager)。
+ *
+ * 地址必须带 `/p2p/<中继PeerId>` (预约要知道中继是谁); 不带直接报错, 不静默失败。
+ * 更稳的做法是在 `startMobileP2P({ relayAddrs })` 时就把它放进 `addresses.listen`
+ * (那边走的是 'configured' 预约路径, 与连接时机无关)。
+ */
+export async function reserveMobileRelay(relayAddr) {
+    const raw = (relayAddr || '').trim();
+    if (!node)
+        return { ok: false, circuitAddrs: [], error: 'P2P 节点未启动' };
+    if (!raw)
+        return { ok: false, circuitAddrs: [], error: '中继地址为空' };
+    const base = raw.replace(/\/p2p-circuit\/?$/, '');
+    if (!/\/p2p\/[^/]+$/.test(base)) {
+        const err = '中继地址必须带 /p2p/<中继PeerId> (没有 PeerId 无法预约)';
+        relayReservationResults.push({ addr: raw, ok: false, error: err });
+        return { ok: false, circuitAddrs: [], error: err };
+    }
+    try {
+        const listenAddr = createMultiaddr(`${base}/p2p-circuit`);
+        if (typeof node.listen === 'function') {
+            // 老/新版本有 node.listen 就直接用
+            await node.listen(listenAddr);
+        }
+        else if (node.components?.transportManager?.listen) {
+            await node.components.transportManager.listen([listenAddr]);
+        }
+        else {
+            throw new Error('本版本 libp2p 既无 node.listen() 也无 components.transportManager.listen() —— 中继地址必须在 createLibp2p 的 addresses.listen 里给');
+        }
+        const circuitAddrs = getMobileCircuitAddrs();
+        const relay = getMobileRelays().slice(-1)[0];
+        relayReservationResults.push({ addr: raw, ok: circuitAddrs.length > 0, relay, error: circuitAddrs.length ? undefined : '预约返回但未拿到 /p2p-circuit 地址' });
+        return { ok: circuitAddrs.length > 0, circuitAddrs };
+    }
+    catch (e) {
+        const err = String(e?.message || e).slice(0, 240);
+        relayReservationResults.push({ addr: raw, ok: false, error: err });
+        console.warn('[mobile-p2p] relay reservation failed:', err);
+        return { ok: false, circuitAddrs: getMobileCircuitAddrs(), error: err };
+    }
+}
 /**
  * 添加 P2P 好友 (按 multiaddr 地址 dial 连接)。
  * 校验 → 记录到 localStorage (startMobileP2P 会自动重连) → 若节点已启动则立即 dial。
@@ -245,6 +368,12 @@ export async function addMobilePeer(addr) {
     }
 }
 // 暴露同步状态读取 (mobile-core.network.status 用)
+// 2026-09-11: 带上中继可观测项 —— circuitAddrs = 本机可被拨入的地址, relays = 已预约的中继
 if (typeof globalThis !== 'undefined') {
-    globalThis.__mobileP2PStateSync = () => ({ ...state });
+    globalThis.__mobileP2PStateSync = () => ({
+        ...state,
+        circuitAddrs: getMobileCircuitAddrs(),
+        relays: getMobileRelays(),
+        relayReservations: getMobileRelayReservations(),
+    });
 }