存储网络通信【免费下载链接】js-ipfsIPFS implementation in JavaScript项目地址https://gitcode.com/gh_mirrors/js/js-ipfs点击查看免费下载导读本文以 js-IPFS 仓库中ipfs-message-port-client包的完整变更日志CHANGELOG.md为骨架系统梳理这个通过 MessagePort 访问 IPFS 节点的浏览器端客户端库从 0.1.0 到 0.15.1 的三年演进历程。你将掌握该库诞生的动机多标签页共享一个 IPFS 节点、核心 RPC 架构MessageTransport/Query/Service三层模型、大二进制数据跨线程传递时的transfer优化技巧以及每次破坏性变更ESM-only、multiformats v11、libp2p 0.40.x 等对 API 形态与使用方式造成的实际影响。文中所有结论均对照 src 源码、测试用例与 package.json 进行了验证。一、包定位为什么需要一个 message port 上的 IPFS 客户端ipfs-message-port-client的官方定位是IPFS client library for accessing IPFS node over message port见 README.md 与 package.json 的 description 字段。它是 js-IPFS 浏览器端多上下文方案中的客户端一半与ipfs-message-port-server、ipfs-message-port-protocol共同构成完整体系。1.1 核心设计动机该包最初诞生于 2020 年 8 月的 0.1.0 版本变更日志中明确记录其初始特性为share IPFS node between browser tabs在浏览器标签页之间共享 IPFS 节点。其典型部署模式是ipfs-message-port-server运行在一个 SharedWorker 中独占一个完整的 IPFS 节点实例页面中的每个标签页、iframe 则通过ipfs-message-port-client与该 SharedWorker 通信共享同一个节点避免每个标签页都启动一个重量级 IPFS 节点内存、CPU 与网络连接开销都非常可观。从源码结构看入口文件 导出的IPFSClient继承自CoreClient并在构造函数中组合了三个子客户端export class IPFSClient extends CoreClient { constructor (transport) { super(transport) this.transport transport this.dag new DAGClient(this.transport) this.files new FilesClient(this.transport) this.block new BlockClient(this.transport) } }因此客户端对外暴露的 API 子集为与 README 中列出的能力一致ipfs.dag——put/get/resolve见 dag.jsipfs.block——put/get/rm/stat见 block.jsipfs.files.stat见 files.jsipfs.add/ipfs.addAll/ipfs.cat/ipfs.ls由 core.js 提供从各子客户端的构造可以看出每个命名空间下的远端方法都遵循 namespace methods 的注册模式例如super(dag, [put, get, resolve], transport) // dag.js super(files, [stat], transport) // files.js super(block, [put, get, rm, stat], transport) // block.js super(core, [add, addAll, cat, ls], transport) // core.js1.2 两种实例化方式from 与 detachedclient.js 提供了两个静态工厂方法IPFSClient.from(port)从一个已有的MessagePort直接创建客户端适用于端口已经可用例如直接从new SharedWorker(url).port拿到端口的场景。IPFSClient.detached()创建游离客户端此时端口尚未拿到所有 API 调用会被排队缓存直到后续调用IPFSClient.attach(ipfs, port)连接后统一 flush。这在通过 iframe 的 postMessage 异步收到端口的场景下非常有用。游离客户端之所以能排队是因为底层MessageTransport在构造时可以不带端口所有查询先进入queries字典connect(port)之后统一投递详见下一节源码分析。二、传输层原理MessageTransport / Query / Service 三层 RPC 模型变更日志记录了大量 RPC 传输层相关的修复理解这套机制对解读这些变更至关重要。整个客户端的调用链是IPFSClient.add() → CoreClient.add() → this.remote.add() // Service 动态生成的远端方法 → transport.execute(query) // MessageTransport 投递 → port.postMessage(...) // 结构克隆/转移后发出2.1 Query一次远程调用的封装query.js 中的Query类封装了一次远程过程调用的全部要素namespace与method定位服务端的具体接口input调用参数toJSON()返回会被结构克隆的数据transfer()返回可转移对象集合SetTransferable这些对象将走Transferable 转移而非复制timeout/signal超时与中止支持timeout为null时视为Infinityresult一个 Promise由succeed/fail决议。2.2 MessageTransport请求路由与生命周期管理transport.js 的MessageTransport是传输核心职责包括唯一 ID 生成每个 transport 实例用Math.random().toString(32)生成随机前缀再拼接自增序号如id ${this.id}${this.nextID}。源码注释明确说明这是为了当多个标签页与 SharedWorker 中的服务端通信时保证 query.id 唯一——这正是多标签共享节点场景的关键设计。查询投递postQuery通过port.postMessage({ type: query, namespace, method, id, input }, query.transfer())发出消息第二参数即 Transferable 转移列表。超时与中止若query.timeout 0 query.timeout Infinity则启动定时器超时后删除 pending 查询、以TimeoutError拒绝并向服务端发送{ type: abort, id }取消消息。客户端AbortSignal触发时同理AbortError。连接与断连connect(port)会把此前积压的所有查询一次性投递disconnect()则以DisconnectError拒绝所有 pending 查询并关闭端口。源码注释强调一旦断连不可重连端口引用被保留以在重连时抛错。响应分发handleEvent按响应中的id找到对应Queryresult.ok时succeed否则用decodeError解码远端错误后fail。若查无此 ID例如客户端已中止但服务端响应恰好到达则直接忽略。2.3 Service按方法名动态生成远端 APIservice.js 中的Service根据构造时传入的methods列表在实例上动态挂载同名方法每个方法都执行transport.execute(new Query(namespace, method, input))。于是Client基类中的this.remote就拥有了与远端服务完全同形的调用面——这是整个客户端 API 得以与ipfs-core-types类型保持一致的基础。为什么变更日志里大量提到 types0.4.0 版本修复了 typedef 解析typedef resolution add examples that use types0.5.3 升级 aegir 构建工具0.6.0 中 all core api methods now have types。源码中遍布typedef {import(ipfs-core-types/src/root).APIMessagePortClientOptions} RootAPI这样的类型引用说明该包从早期就开始用 JSDoc 类型标注来对齐核心 API 类型面。三、性能关键结构化克隆 vs Transferable 转移变更日志在 0.4.3 版本记录了transfer unique set over message prort在消息端口上转移唯一集合的修复这正对应transfer机制的一个坑。README 的 Notes on Performance 一节对此有详尽说明3.1 为什么默认是拷贝客户端与服务端之间所有数据都经structured cloning algorithm结构化克隆算法传递这意味着大块二进制数据会被完整复制一份产生显著的性能损耗。为此所有 API 的 options 都被扩展了可选的transfer属性调用者可显式给出Transferable[]让这些底层缓冲如ArrayBuffer被转移而非复制。/** * param {Uint8Array} data - Large data chunk */ const example async (data) { // 传入 data.buffer 会把底层 ArrayBuffer 转移走 // 之后当前 JS 上下文中的 data 将被清空。 ipfs.add(data, { transfer: [data.buffer] }) }⚠️注意转移会清空发送方的数据。如果转移后再次使用原数据会出错所以transfer必须由调用者在确认安全时显式给出——这正是 0.4.3 修复transfer 唯一集合的原因Set 集合在转移过程中需要保证元素唯一性避免重复转移导致数据损坏。3.2 优先使用 Blob / FileREADME 强烈建议优先使用 Web 原生Blob/File实例因为大多数 Web API 都以它们为输入形式且Blob可以跨上下文传递而不复制底层内存const example async (url) { const request await fetch(url) const blob await request.blob() ipfs.add(blob) }在 core.js 的encodeAddInput/encodeAsyncIterableContent/encodeIterableContent实现中可以看到输入编码器按Blob → string → ArrayBuffer → ArrayBufferView → (async)Iterable → ReadableStream → FileObject的顺序做模式匹配其中Blob路径是最高效的分支if (input instanceof Blob) { return input // 直接透传无需编码底层内存不复制 } else if (typeof input string) { return input } else if (input instanceof ArrayBuffer) { return input } else if (ArrayBuffer.isView(input)) { // 注意这里不会自动把 input.buffer 加入 transfer 列表由用户决定 return input }3.3 progress 回调如何跨线程传输普通函数无法被结构化克隆因此add/addAll的progress回调在跨端口传输时必须做特殊编码core.js 中progressCallback options.progress ? encodeCallback(options.progress, transfer) : undefined随后把progress: undefined与progressCallback分别传出。CHANGELOG 0.4.0 记录的pass file name to add/addAll progress handler正是对这个回调通道的增强——从此进度处理器可以收到文件名。四、API 语义变更add / addAll / ls / get 的破坏性调整变更日志记录了多个直接影响使用者代码的 API 语义变更这些变更与 ipfs-core-types 的定义演进同步。4.1 0.10.0add 与 addAll 的输入校验收紧BREAKING CHANGES: errors will now be thrown if multiple items are passed to ipfs.add or single items to ipfs.addAll (n.b. you can still pass a list of a single item to ipfs.addAll)即ipfs.add只接受单个内容项传入多个项会抛错ipfs.addAll只接受可迭代的流把单个项直接传给它也会抛错但传[单个项]列表是允许的。这个语义在源码 core.js 的ensureIsByteStream中有直接体现它用it-peekable偷看流首元素若首元素不是整数/字节/字符串即流元素不是字节流则抛出errCode(new Error(Unexpected input: multiple items passed - if you are using ipfs.add, please use ipfs.addAll instead), ERR_UNEXPECTED_INPUT)。同时encodeIterableContent对typeof content number会抛TypeError(Iterable of numbers is not supported)。4.2 0.8.0ipfs.get 输出改为 tarballls 移除 recursiveBREAKING CHANGES: the output type of ipfs.get has changed and the recursive option has been removed from ipfs.ls since it was not supported everywhereipfs.get的输出类型改为 tarball 流ipfs.ls的recursive选项被移除。注意在测试文件 interface-message-port-client.js 中get、refs、refsLocal、addAll均被标记为 Not implemented 而跳过——说明该客户端在相当长一段时间内只实现了 README 所列的 API 子集这是使用者需要留意的能力边界。4.3 0.3.0新增 ipfs.ls 与类型检查0.3.0 实现了 message-port 上的ipfs.ls对应 core.js 中ls方法CID 会被encodeCID编码结果通过decodeLsEntry解码为含cid/type/name/path/mode/mtime/size的 IPFSEntry并引入type check generate defs from jsdoc——即从 JSDoc 生成类型定义这也是后续多个版本typedef 修复工作的起点。五、模块体系演进ESM-only 与构建工具链变迁5.1 0.12.0正式切到 ESM-onlyBREAKING CHANGES: This module is now ESM only and there return types of some methods have changed这一变更在 package.json 中得到印证type: module、exports: { .: { types: ./dist/src/index.d.ts, import: ./src/index.js } }且engines要求node 16.0.0、npm 7.0.0。源码统一使用import/export语法。5.2 0.9.0ESM/CJS 双发布过渡阶段BREAKING CHANGES: There are no default exports and everything is now dual published as ESM/CJS在彻底 ESM-only 之前0.9.0 先移除了默认导出IPFSClient改为具名导出并短暂采取 ESM/CJS 双发布策略。因此在使用上需注意从早期版本升级时的导入写法变化// 0.9.0 之后 import { IPFSClient } from ipfs-message-port-client5.3 0.6.0Node 最低版本提升到 14BREAKING CHANGES: Minimum supported node version is 140.6.0 将最低 Node 版本提升到 14同时all core api methods now have types, some method signatures have changed, named exports are now used by the http, grpc and ipfs client modules——类型面与命名导出的规范化在整个 js-IPFS 客户端家族http / grpc / message-port中同步进行。5.4 0.5.0ipfs-repo 升级触发仓库迁移到 v100.5.0 的破坏性变更为ipfs-repo upgrade requires repo migration to v10这与 0.11.0 中the repo is migrated to v12相呼应——底层仓库格式的迁移会随依赖升级自动触发使用者若保留旧版本地仓库升级后首次启动可能经历迁移过程。六、底层依赖升级multiformats、CID 与 libp2p 的连锁影响6.1 0.15.0multiformats v11 大版本升级BREAKING CHANGES: update multiformats to v11.x.x and related depenendciespackage.json 中multiformats: ^11.0.0与此对应。multiformats 是 CID 编解码、多哈希、多编解码的基础库其大版本升级意味着 CID 对象的行为可能变化。客户端在 CID 处理上有明确约定见 core.js / dag.js / block.js / files.js发送方用encodeCID把 CID 编码成可结构克隆的形态EncodedCID接收方用decodeCID还原为真正的 CID 实例对CID 字符串 vs CID 对象严格区分——测试用例中多处跳过原因写着Passing CID as strings is not supported、Passing CID as Uint8Array is not supported说明该客户端只接受 CID 对象不接受字符串或 Uint8Array 形式的 CID。6.2 0.8.5移除 CID 的 instanceof 判断0.8.5 的remove use of instanceof for CID class与 multiformats 生态的演进一致由于可能存在多个 multiformats 副本不同版本/不同包实例instanceof判断不可靠改为CID.asCID(input)形态检查。这在当前源码中随处可见例如const cid CID.asCID(inputPath) // core.js cat/ls const cid CID.asCID(pathOrCID) // files.js encodeLocationencodeLocation还演示了路径规范化若传入的是 CID 对象则拼接为/ipfs/${cid.toString()}否则直接使用字符串路径。6.3 0.7.0多格式演进 —— ipld-formats 让位于 multiformats BlockCodecsBREAKING CHANGES: ipld-formats no longer supported, use multiformat BlockCodecs instead0.7.0 同时实现了 dag import/exportimplement dag import/export并升级到新的 multiformats。不过测试文件显示.dag.export与.dag.import仍被标记为 Not implemented yet 跳过——核心 API 的类型面先就位具体实现与测试逐步跟进。6.4 libp2p 升级链0.13.0 → 0.14.0 → 0.12.0变更日志记录了连续的 libp2p 升级及其破坏性影响版本破坏性变更说明0.13.0update to libp2p0.38.x配置形态随 libp2p 0.38 变化0.14.0ipfs is now bundled with libp2p0.40.x which has different configlibp2p 0.40 配置方式不同0.12.0update to libp2p 0.37.xESM-only 同期升级这些变更对使用者的实际含义是如果通过配置文件定制节点的 libp2p 行为如传输、peer 发现、连接管理等升级 js-IPFS 后必须按新版本 libp2p 的配置格式调整否则节点可能无法按预期启动。0.11.0 的peerstore methods are now all async则是同一大方向上的配套变化libp2p 异步 peerstore。七、测试验证体系interface-ipfs-core 兼容性测试CHANGELOG 几乎每个版本都同步更新 devDependencies 中的interface-ipfs-core与ipfs-core、ipfs-message-port-server并在 package.json 中定义了专门脚本test:interface:message-port-client: aegir test -t browser --bail -f ./test/interface-message-port-client.js测试入口 interface-message-port-client.js 通过activate()创建客户端实例并把interface-ipfs-core的root、dag、block三组测试套件接入同时以skip列表声明当前未实现的能力例如rootaddAll、get、refs、refsLocal未实现ipfs.object.get未实现导致only-hashtrue相关用例跳过浏览器环境无process.hrtimeHTTP URL 拉取存在 [js-ipfs#3195] 已知问题dagCID 字符串入参不支持、dag-pb 节点不转为 DAGNode 实例、.dag.export/import未实现blockCID 字符串/Buffer 入参不支持、ipfs.pin与ipfs.refs.local未实现、若干删除用例因超时跳过。这份 skip 清单实际上是一份能力边界清单它精确划定了该客户端与完整 js-IPFS 核心 API 之间的差距是评估能否把 message-port 客户端接入现有业务的最直接依据。八、维护状态与迁移提示8.1 版本序列概览从 CHANGELOG 可还原出完整版本线0.1.02020-08-12跨标签页共享节点→ 0.2.0pins 存储迁移到 datastore→ 0.3.0ls 与类型定义→ 0.4.xtransfer 修复、typedef 修复→ 0.5.xrepo v10 迁移→ 0.6.0Node 14、全量类型→ 0.7.0dag import/export、multiformats 升级→ 0.8.xget 输出 tarball、CID instanceof 移除、ESM 双发布→ 0.9.0ESM/CJS 双发布、无默认导出→ 0.10.xadd/addAll 输入校验、transfer set 修复→ 0.11.0异步 peerstore、repo v12→ 0.12.0ESM-only、libp2p 0.37→ 0.13.xlibp2p 0.38→ 0.14.0libp2p 0.40→ 0.15.xmultiformats v11最终版本 0.15.12023-05-25。8.2 弃用声明README.md 顶部带有明确的弃用横幅js-IPFS 已被 Helia 取代继续使用本仓库将不再提供安全修复。因此对 0.15.1 之后的长期维护与新项目选型应评估迁移到 Helia 生态而对已运行在 js-IPFS 上的存量浏览器多标签共享节点场景本文梳理的 API 边界、transfer用法与升级破坏点仍然适用于当前仓库中的实现。8.3 安装与使用速查$ npm i ipfs-message-port-client典型用法SharedWorker 场景摘自 README.mdimport { IPFSClient } from ipfs-message-port-client // URL 指向包含 ipfs-message-port-server 的脚本 const IPFS_SERVER_URL /bundle/ipfs-worker.js const main async () { const worker new SharedWorker(IPFS_SERVER_URL) const ipfs IPFSClient.from(worker.port) const data ipfs.cat(/ipfs/QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n) for await (const chunk of data) { console.log(chunk) } }游离客户端模式端口通过 iframe 消息异步到达import { IPFSClient } from ipfs-message-port-client const ipfs IPFSClient.detached() window.onload main window.onmessage ({ ports }) { IPFSClient.attach(ipfs, ports[0]) // 连接后自动 flush 积压请求 }注意游离客户端会排队所有 API 调用直到 attach 后才真正执行除非期间超时或被中止。九、关键文件索引想要深入研读实现细节的读者可按以下路径继续探索当前仓库入口与工厂方法packages/ipfs-message-port-client/src/index.js传输层ID 生成、超时/中止、断连packages/ipfs-message-port-client/src/client/transport.jsRPC 查询封装packages/ipfs-message-port-client/src/client/query.js远端服务代理生成packages/ipfs-message-port-client/src/client/service.js核心 APIadd/addAll/cat/ls 的编解码packages/ipfs-message-port-client/src/core.jsDAG / Block / Files 子客户端dag.js、block.js、files.js协议层CID、错误、RPC 编码定义packages/ipfs-message-port-protocol/src服务端实现SharedWorker 内节点托管packages/ipfs-message-port-server/src兼容性测试与能力边界packages/ipfs-message-port-client/test/interface-message-port-client.js赞分享存储网络通信【免费下载链接】js-ipfsIPFS implementation in JavaScript项目地址https://gitcode.com/gh_mirrors/js/js-ipfs点击查看免费下载相关推荐Easy-Vibe AI 能力词典解读从模型选型到系统落地的全景能力地图Easy Vibe AI 能力词典解读从模型选型到系统落地的全景能力地图 在 Easy Vibe 教程的知识体系中 AI 能力词典 https://link存储网络通信OI-wiki 之 Vim 完全指南从模式入门到宏与批量编辑进阶OI wiki 之 Vim 完全指南从模式入门到宏与批量编辑进阶 Vim 是从 vi 发展而来的经典文本编辑器其代码补完、编译及错误跳转等编程功能极为丰富存储网络通信ZIO项目贡献指南从零开始参与开源贡献ZIO项目贡献指南从零开始参与开源贡献 前言 ZIO是一个专注于类型安全、可组合的并发和异步编程的Scala库。作为现代函数式编程的代表性项目ZIO拥有活跃存储网络通信上一篇3个关键问题OpenCore Legacy Patcher如何让老旧Mac重获新生下一篇5分钟掌握Switch注入Windows平台终极图形化解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
