@abele/sync-sdk (英语)

安装目标 : npm install @abele/sync-sdk。 。 。 .

import { open, parseKey } from "@abele/sync-sdk";
const key = process.env.SYNC_KEY;
parseKey(key); // local validation
const client = await open({ key, dir: "./mirror" });
try {
  await client.syncOnce();
  console.log(await client.replica.list());
} finally {
  await client.close();
}

API 和业务

SDK 0.3.17 批次将保留物移入耐用组群。 本地 V2 主机可以 选择使用 onRemovalCohort 和借来的 cohort.retain 处理; 有 onRemoval 主持人继续工作. 公共群体援助人员可通过 核心导出。 所有权和召回合同见移民清单. 这件装饰品不是出版物或部署.

自定义主机必须跟随 0.3.0 移徙清单。 。 。 . pause() 财务报告和审定财务报表 stop() 中断活动同步 。 中断 syncOnce() 拒绝 导出 SyncCancelled; 在检查前将其作为有意注销处理 继承 offline 代码。 取消显示没有出错事件或下线重试 .

要求节点.js 22+和无害环境管理。 SDK 0.3.17 有核心、节点和协议的对 0.5.0 (单位:千美元),带有服务器目标 0.3.3 (中文(简体) ) 财务报告和审定财务报表 0.5.0 (单位:千美元) (单位:千美元)compat.json议定书2 需要; 仅它的号码并不能保证与每个服务器的兼容性 建设。 匹配的核心,节点适配器和协议被捆绑在这个包内.

打开和适配器

parseKey(key) 在本地验证和解码时没有网络访问. 结果 包含符号地址和遗留范围或v2项目预览;将其作为证书处理. open(options) 检查能力和活动连接,然后打开本地 状态和完成恢复。 打电话 syncOnce() 明确用于当前服务器数据.

client.scope 报告服务器连接的文件夹、组或文件范围。 路径是 相对于预计的复制品。 没有SDK组管理 API. client.readOnly ; 没有本地只读选项. 来电同步仍然可以写入本地文件 。 使用服务器权限防止上传.

选择其中之一 { key, dir, stateDir? } 用于SDK拥有的节点适配器,或 { key, files, state } 为呼叫者拥有的适配器. FileSystem 财务报告和审定财务报表 StateStore 是导出的核心接口,而不是构建器。 供应自定义适配器和 不将它们与目录选项合并。 他们的耐久性,观看和最后 处理属于呼叫者; 关闭 SDK 不处理它们.

可选 transport.fetch 财务报告和审定财务报表 transport.WebSocket 替换全域节点. clock: () => number 以毫秒计的供给引擎时间,而不是文件系统 锁/恢复时钟. logger: (line: string) => void 接受一般活动 备注. backoffMs: [min, max] 财务报告和审定财务报表 fallbackMs 配置重试和周期 同步延迟以毫秒计 . deleteGuard 财务报告和审定财务报表 defer 控制决定如下.

项目集(服务器:0.5.0)

import { ItemClient, AccessClient, open } from "@abele/sync-sdk";

const owner = ItemClient.fromToken(ownerKey, { fetch });
if (await owner.supportsItems()) {
  const added = await owner.addItem(targetTokenId, {
    kind: "file",
    id: fileId,
  });
  const recipient = ItemClient.fromToken(recipientKey, { fetch });
  const inventory = await recipient.items();
  const client = await open({
    key: recipientKey,
    item: added.id,
    files,
    state,
  });
  try {
    await client.syncOnce();
  } finally {
    await client.close();
  }
  await owner.removeItem(targetTokenId, added.id); // detach access, keep content
}

items() 列出调用密钥的项目,包括已删除的条目. ItemClient.tokenItems(tokenId) 财务报告和审定财务报表 AccessClient.tokenItems(tokenId) 列表 a 拥有的密钥项目没有它的收件人秘密. AccessClient.tokens() 包含 选项 item_count 值; 旧服务器省略. ./protocol 出口 V2TokenItemsResponseSchema 财务报告和审定财务报表 V2TokenItemsResponse 用于所有者库存回复.

项目清单、预览、总数和项目清点被过滤到呼叫者范围. 隐藏的子项目被省略; 直接预览一个返回 HTTP 403. 组 overlap_count 包括未披露的股票,因此可能超过 overlaps.length 甚至低于响应上限。 未披露的重叠没有 数组条目、路径或标识符;不要推断空数组不存在. 重叠-详细方案不变:披露的条目仍有所有字段. ItemClient 表面为 403 AbeleError 与 code: "forbidden" 财务报告和审定财务报表 status: 403,匹配服务器错误信封 AccessClient两者 AbeleError 财务报告和审定财务报表 HttpError 以 SDK 根导出( 非信封) 可拒绝访问 HttpError 与 status: 403) (中文(简体) ). 这将项目Client 403处理从 HttpError/ protocol 更改为 AbeleError/ forbidden . 消费者必须处理被省略的项目和部分总数,而不加以处理 作为完整的密钥库存或全库删除效果.

两个客户都曝光了 previewTokenItem(tokenId, itemId, { limit? }) 财务报告和审定财务报表 previewToken(tokenId, { limit? }) 用于所有者授权的删除效果预览. 它们返回完整的文件/字节总和,封顶的文件路径和组交叉键重叠; 文件/文件夹预览有空重叠列表。 密钥总计 。 可选文件限制默认为 100,上限为500;重叠名单上限为20. 这些只读 预览,而不是删除授权或快照保证. ./protocol 出口 V2ContentPreviewQuerySchema, (中文(简体) ), V2ItemContentPreviewSchema, (中文(简体) ), V2TokenContentPreviewSchema,其反应类型 V2ItemContentPreview 财务报告和审定财务报表 V2TokenContentPreview,则 V2_PREVIEW_FILE_LIMIT 财务报告和审定财务报表 V2_PREVIEW_OVERLAP_LIMIT 常数。 发行人或 整个所有者使用 addItem(tokenId, selector) 财务报告和审定财务报表 removeItem(tokenId, itemId) 用于管理目标密钥。 选择器支持 folder, (中文(简体) ), group 财务报告和审定财务报表 file;他们的ID识别服务器对象,而不是路径. 使用 AccessClient.fromToken(key, { fetch }) 发出/列出/撤消密钥 V2EngineClient 从根或 ./core 用于低级引擎操作.

deleteItem(itemId, idempotencyKey) 删除选中项目的服务器内容 在服务器所有权检查下。 它可以瞄准自有收件人的密钥项目. 在重新试验这种破坏行动时,坚持并再利用同样的同能键. 删除访问和删除内容是单独的操作.

supportsItems() 探测已认证的库存路径, 因为服务器 不在物品能力旗上作广告。 它在404上变回了假,扔了 关于认证、连接、错误反应和其他服务器错误. 服务器0.3.3只支持遗留密钥. open({ item }) 检查项目支持 打开内容连接前; 省略 item 保留主镜行为. 每个项目都需要单独的文件和状态. 节点复制品在其中坚持选择 连接身份并拒绝在已有状态目录中切换项目.

parseKey 接受遗留的有效载荷v1(scope)和有效载荷v2(items 预览). 用工会的 v 字段来缩小它。 预览是提示; 服务器连接 和库存提供当前权威. ./protocol 导出 v2 令牌, a. 项目、选择器、连接和删除计划以及现有有效载荷类型; 根也输出 ScopeItem, (中文(简体) ), ScopeItemsResponse, (中文(简体) ), V2AccessToken, (中文(简体) ), V2Scope, (中文(简体) ), V2Selector, (中文(简体) ), V2Connection 和核心数据 ClientOptions 类型.

国家、锁和复原

默认 dir/.abele-sync 存储配置(包括证书), SQLite状态和恢复证据. 保持它私密 并远离其他同步工具. stateDir 可以命名一个外部目录,或者确切的默认状态路径; 复制品内的其他路径,包括同名异名,都被拒绝.

外部状态将证书和分类账移到复制品之外,但本地 安装中转和瞬时目录锁仍在使用 dir/.abele-sync 用于原子文件系统操作。 活动时不要删除它 .

重新打开同一目录、 密钥和状态目录以恢复 。 分类账是 与它的联系; 外部状态也与cononical复制品相连 目录。 拒绝为另一个目录或密钥重用 。 用一对新鲜的 对于不同的复制; 不编辑配置以绕过绑定检查.

节点适配器使用本地 better-sqlite3: 安装需要二进制 节点 ABI/ 平面,或者如果不存在预建的二进制,则使用本地构建的工具链. 安装/进口失败并不意味着服务器不兼容.

只有一个过程可能拥有一个复制品. 锁定获取可等待检查 a 上一个所有者; 不删除一个锁以强制另一个写入 。 等着 close() 改为 释放SQLite和锁. 中断后重开同一状态以恢复 日记和待写在正常同步前. RecoveryRequiredError (代码) RECOVERY_REQUIRED)意味着恢复需要注意;其信息没有本地信息 路径或基础错误细节。 以原始状态目录重新打开 。 若为 拒绝寻回,保存文档,并声明调查. 两个都退后 客户端关闭时.

同步和交付

syncOnce() 返回核心 SyncReport数字 : pull, (中文(简体) ), push, (中文(简体) ), secondPull, (中文(简体) ), collisions, (中文(简体) ), deferred, (中文(简体) ), joined。成功并不一定意味着每个传输的文件: 结算文件、所持有的删除和所推迟的更改可能需要再次通过/操作. 同步是双向的.

start() 允许监视、事件锁定和回落触发. pause() 中断 活动运行并暂停自动触发; 手动同步仍然有效, 除非 授权已经停止。 中断 syncOnce() 拒绝方式 SyncCancelled, (中文(简体) ), 没有错误事件或离线重试. resume() 清除暂停/ 授权停止并提示同步 . stop() 等着 进行中的工作并释放出自动资源;在重新启动之前等待. 暂停和授权停止 生存停止/启动. close() 也拥有的释放 适配器,为同位素,并永久关闭客户端. 使用 finally 财务报告和审定财务报表 处理 SIGINT/ SIGTERM , 如文件夹- 镜像样.

on(event, listener) 返回未订阅的函数。 听者同步运行; 抛出例外是孤立的。 处理你自己的反弹.

应用更改通知可以在崩溃回放时重复. 事件是现场的, 不是一个持久的队列或完全的一次性订阅。 冲突事件涉及 最后的推动响应,不是所有的历史批次。 建设一能消费者 通过重读复制品和通过路径更新衍生记录,而不是 按通知附上一项行动。 与 list() 启动到 覆盖丢失的通知。 外部副作用需要自身的持久性, 原子分解;内相集无法活出碰撞.

阅读、历史和决定

replica.list(prefix?), (中文(简体) ), read(path) 财务报告和审定财务报表 readText(path) 读取本地数据, 包括未符号编辑。 列表按排序、递归和字面前缀排列: Notes/ 选择后代; Notes 也匹配 Notes-old.md条目 path字节 size, (中文(简体) ), mtime和可选分类账 fileId。文本为 UTF-8. 国家道路被排除在外;绝对的、逆向的和反向的路径被拒绝.

history(path, { limit?, before? }?) 读取服务器版本. restore(path, versionId) 使用引擎的序列还原操作. trash() 列出已删除的文件; restoreDeleted(pathOrId) 恢复列出的路径 或文件编号。 恢复返回核心承诺结果; 拒绝丢出历史错误 . 之后同步以获取恢复的内容 。 服务器保留和权限适用.

默认删除的守护符有50个删除, 或至少10个构成一个季度 同步条目。 最近的删除数为默认的 15分钟窗口 . deleteGuard: { count, floor, share, windowMs? } 超过阈值; deleteGuard: false 禁用保护. heldDeletes() 列表路径/文件ID对. 将经审查的身份证传递给 decideDeletes({ kind: "confirm" | "restore", fileIds })。 。 。 . 确认发送删除; 恢复从活服务器获取缺失的本地文件 复制,不是垃圾。 结果是 { decided, report }。决定开始同步 除非暂停/吸入, 等待同步恢复.

defer: (wirePath) => boolean 匹配远程更改而不是写入 他们在当地. deferred() 列出分阶段的更改; applyDeferred(versionIds?) 通过引擎应用所选版本。 启用所有当前 ID 分阶段更改; 通过经过审查的ID以避免隐形替换。 这是数据 推迟,不是代码批准/执行设施.

disconnect() 停止,忘记本地连接状态/证书和关闭, 保存用户文件。 自定义元数据存储需要 metadataKeys 财务报告和审定财务报表 setMeta 用于完全忘记,否则将丢出 HistoryError(“ 不支持”) . revoke() 撤销此连接的服务器令牌并停止同步、 保留 当地州。 自发客户端无法启动/ 恢复; 关闭或断开 分别.

错误

关于导出类和代码的分支, 不是消息文本 .

无效的适配器/ 路径可以丢入 TypeError; 生命周期误用可以丢出普通 错误。 有点 open() 保留运输和本地文件系统/SQLite/锁故障 此版本的上游错误形状 。 不记录任意错误/ 原因或 连接证书。 SDK事件/历史出错和同步故障被消毒.

许可证

仅限GPL-3.0;见LICENSE. 连接此软件包或组合衍生工具 应用程序要求GPLv3遵守,包括适用的源、通知和 许可证义务。 私人修改和使用不需要公布; 仅网络访问无法创建 AGPL 风格的源报价 。 分发他人 即使在私人或商业场合,也仍然承担着GPL的义务.

包含注释解析器和类型

任务和说明分析包括:

import { taskFromFrontmatter, noteFromMarkdown } from "@abele/sync-sdk/notes";
const task = taskFromFrontmatter({ groups: ["work"] });

使用 @abele/sync-sdk/core 财务报告和审定财务报表 @abele/sync-sdk/protocol 核心项目 公共SDK API参考的协议类型,包括适配器合同 并解码连接符. 不需要单独的Abele软件包.

核心、协议和节点适配器代码来自 abele- sync 源码。 。 。 . 见NOTICE和包括上游许可证。 注释解析器从 此仓库 。 需要公开的 YAML 助手声明 @types/js-yaml, (中文(简体) ), 被作为附属物列入.