@ godspideai/ cognate- events
科格纳特的耐久状态平面合同: Cononical event 信封, the DurableStore 端口每个商店工具, 以及一个发件箱调度器, 用于执行后的工作 。 这个包件定义了合同——它没有运送储存.
何时使用此软件包 : 您正在执行一个持久的商店, 在事件日志上构建工具, 或者亲自发送发件箱。 应用程序通过工作商店
@godspeedai/cognate-store-sqlite
或者说 @godspeedai/cognate-store-memory, (中文(简体) ),
两者均执行本合同.
安装
bun add @godspeedai/cognate-events
要求数 阿宝 >= 1.4.0.
那个信封
NewEvent 是决定提出的。 店铺指定 eventId, (中文(简体) ), streamId, (中文(简体) ), streamSequence (每条溪流无差距), position (全店承诺令),以及 recordedAt顺序和位置是命令当局—— occurredAt 是源头声称的来源 从来没有命令事件.
validateNewEvent 写入任何文件前执行信封: 需要的字段存在, 小写点 eventType正整数 schemaVersion,ISO-8601 标准 occurredAt,1米B范围内的JSON载荷(MAX_PAYLOAD_BYTES) (中文(简体) ). 失败投出 EnvelopeValidationError 列出每个问题.
fingerprint 计算JSON请求中一个稳定,按键顺序独立的SHA-256——除了不同的请求外,用何来表示回放.
快开始
import { fingerprint, validateNewEvent } from "@godspeedai/cognate-events";
const placed = {
eventType: "order.placed",
schemaVersion: 1,
occurredAt: new Date().toISOString(),
tenant: "tenant-a",
correlationId: "corr-1",
causationId: null,
runId: null,
scopeId: "root",
payload: { sku: "widget", quantity: 2 },
};
validateNewEvent(placed);
const commit = {
idempotency: { scope: "alice:order", key: "order-1", fingerprint: fingerprint(placed.payload) },
appends: [{ streamId: "order-1", expectedVersion: 0, events: [placed] }],
result: { placed: true },
};
手 commit 对任意 DurableStore 这里的记忆之一:
import { createMemoryStore } from "@godspeedai/cognate-store-memory";
const store = createMemoryStore();
const outcome = await store.commit(commit);
// { kind: "committed", events: [...], records: [], result: { placed: true } }
再次提交同一请求返回 { kind: "duplicate", result: { placed: true } } ——原收录的结果,没有写出新的事实. 为不同的请求重用密钥 IdempotencyMismatchError。 。 。 .
什麽 DurableStore 覆盖
一个原子 commit - 全部或无:
- 由预期版本保护的流式附件( 丢弃的比赛)
ConcurrencyError; 重读并重试, 永不覆盖 ; - 比较和扫描记录写道(
RecordConflictError(三); - 犯罪后工作意图;
- 与裁决一起记录的一能结果.
超越 commit数字 : readStream编号 :readAll 页面顺序和位置顺序, getRecord编号 :listRecords 读取版本记录, onCommitted 订阅事件(仅在交易完成后才使用),投影检查点按投影状态进行解剖,blobs被处理内容(sha256:<hex>),以及 erasePayload 移除事件的有效载荷,同时保留其信封,并将墓碑事件附在 $erasures 流线.
提供外包服务
OutboxDispatcher 声称有犯罪意图,并至少交付一次,有限度的指数反射:
import { OutboxDispatcher } from "@godspeedai/cognate-events";
const dispatcher = new OutboxDispatcher(store, {
topic: "email",
backoff: { baseMs: 100, maxMs: 5_000, maxAttempts: 10 },
deliver: async (item) => {
await sendEmail(item.payload);
return { accepted: item.id };
},
});
const report = await dispatcher.drain();
// { delivered: [...], retried: [{ id, retryAt }], poisoned: [...] }
掷出 PermanentDeliveryError 从 deliver 立即下毒,而不是重试。 有毒物品通过 store.listOutbox({ status: "poisoned" }) 直到操作员打电话 store.requeueOutbox. 交付目标必须通过 item.id ——一接一送,是指重试可以送出两次.
已建成的商店也提供可选的栅栏索赔方法(claimOutboxLeased, (中文(简体) ), renewOutboxLease,以及 settleOutboxLease) (中文(简体) ). 它们将续约和定居与业主联系在一起,并且单调增加一代人,因此,租期已过或重新排队的工人不能承认以后提出的索偿要求. OutboxDispatcher 可用时使用这些方法,心跳活性地交付,失去主张后中止工作. 内容 concurrency 选项默认为1;1以上值需要栅栏租赁支持。 年长的适配器通过现有方法保持相容性,但不提供Stale-Worker保护;只用一个过程运行他们的调度器. 见 租赁合同 时间和交货限制.
存储执行者的合规包
执行存储意味着正确执行; 在测试套件中不改变运行套件:
import { storeConformance } from "@godspeedai/cognate-events/conformance";
storeConformance("my-store", myStoreFactory, { persistent: true, fencedOutbox: true });
过 persistent: false (c) 对长期储存的商店进行额外测试,以保持每一项承诺的决定贯穿其中。 参考执行情况: @godspeedai/cognate-store-memory 财务报告和审定财务报表 @godspeedai/cognate-store-sqlite。 。 。 .
限制
- 这里没有存储:
DurableStore接口是产品。 选择一个执行或写一个. - 事件有效载荷被封装在一米B;更大的含量属于一个blob.
- 顺序由序列号和位置来定义,从来不用时间戳来定义.
相关软件包
@godspeedai/cognate-store-sqlite——持久地SQLite执行本合同.@godspeedai/cognate-store-memory测试和电流运行时间的模拟执行.@godspeedai/cognate-projections——通过本套件所定义的日志检查衍生出.@godspeedai/cognate-runtime-bun——通过本合同使用商店的参考运行时间.@godspeedai/cognateSDK伞.
许可证
阿帕奇 - 2.0