Crate nasaga_runtime_core

Expand description

Saga backend 中立状态机与 wrapper 共享的进程级运行状态。

Orchestrator、Participant、timer、补偿、恢复与 fencing 裁决只在本 crate 保留一份，MySQL 与 PostgreSQL wrapper 只注入 nasaga_backend::SagaBackend。数据库事实由各 backend 读取；transport、配额与管理动作指标全进程只计一次。

Re-exports§

pub use envelope::derive_result_event_id;
pub use envelope::SagaCommandEnvelope;
pub use envelope::SagaResultEnvelope;
pub use envelope::VerifiedIdentity;
pub use envelope::COMMAND_EVENT_TYPE;
pub use envelope::RESULT_EVENT_TYPE;
pub use envelope::SAGA_AGGREGATE_TYPE;

Structs§

AuthenticatedParticipantRuntime: 业务作用：表示已命中至少一条 Participant 信任投影的 command producer 能力。
CapabilityDescriptor: 业务作用：声明参与方当前可执行步骤的协议和逐实例地址事实。
CapabilityReceipt: 业务作用：返回服务端接受的 capability 租约与幂等摘要。
CommandDeliveryPolicy: 业务作用：限制同一 command 的普通瞬态重试次数，不影响结果不确定分支的持续收敛。
DefinitionActivationGate: 业务作用：冻结一次 definition 激活必须满足的集群快照与数据面路由合同。
DefinitionArtifact: 业务作用：承载 workflow owner 发布的完整、有序且带 seal 的流程合同。
DefinitionLifecycleOperation: 业务作用：把人工 definition 生命周期动作的 CAS、幂等身份与审计原因冻结为一个持久裁决输入。
DefinitionRecord: 业务作用：返回持久 Catalog 中 definition 的内容与当前 generation。
DefinitionRegistry: 业务作用：持有本进程可驱动的全部 workflow definition，按 (名称, 定义版本) 索引。
DefinitionStepArtifact: 业务作用：完整描述 definition 中一个有序步骤的业务和失败语义。
DynamicCatalogSnapshot: 业务作用：把同一数据库 generation 的 definition 与有效 capability 形成不可拆分加载结果。
Orchestrator: 业务作用：Saga Orchestrator——所有推进都以数据库 CAS 与单一本地事务落库。
OrchestratorConfig: 业务作用：Orchestrator 的运行参数；全部预算有界，自动状态不允许无限滞留。
ParticipantCommandTrust: 业务作用：冻结一个 workflow definition 可向本 Participant 发命令的逻辑 Orchestrator。
ParticipantRuntime: 业务作用：参与方运行时——持有 store/inbox/outbox 句柄与本服务的 Inbox consumer 名。
RegisteredCapability: 业务作用：保存能力目录中一个仍在租约内的逐实例 route。
ResultDeliveryPolicy: 业务作用：限制 result 普通瞬态重试次数，同时保留暂停与事务不确定的无限收敛语义。
SagaAuditPage: 业务作用：返回单一有界审计记录流及继续读取所需的稳定游标。
SagaAuditPageCursor: 业务作用：携带最后已交付的全局审计事件序号，支持跨类别追加与断线续读。
SagaAuditTrail: 业务作用：聚合一次有界管理查询返回的 attempt、迁移、控制、人工恢复与冲突事实。
SagaCommandEnvelope: 业务作用：Orchestrator 发往参与方的 execute/cancel/compensate/resolve 命令 envelope。
SagaHttpCredentials: 业务作用：保存当前出站 HMAC 与仅在重叠窗口内允许入站验签的历史材料。
SagaHttpMessageAuthError: 业务作用：携带可观测但不含凭据的内部认证失败分类，同时保持统一对外错误文本。
SagaHttpMessageAuthenticator: 业务作用：绑定单条 transport 信任边的凭据来源与允许时钟偏差。
SagaHttpReplayGuard: 业务作用：在 HMAC 时间窗内原子拒绝已经验真的 nonce，防止认证请求被原样重放。
SagaHttpReplayMetricAggregate: 业务作用：聚合同一 transport 平面内互相隔离的 replay guards，同时保留最拥挤单边水位。
SagaHttpReplayMetrics: 业务作用：导出单条 HTTP 信任边的低基数 replay 防护快照，区分攻击、重放与容量配置问题。
SagaHttpSignedMessage: 业务作用：封装接收端实际观察到的签名字段，保证验签与 replay claim 消费同一份字节。
SagaLatencySnapshot: 业务作用：表达一个固定阶段的非累积直方图快照，供 Prometheus 与 OTLP 共用。
SagaManagementContext: 业务作用：携带认证主体、操作原因和冻结权限集，是全部人工控制入口的强制参数。
SagaManagementExpectation: 业务作用：冻结调用方观察到的 Saga 状态与控制版本，使管理动作在同一事务内拒绝过期快照。
SagaOperationalMetrics: 业务作用：聚合 Saga 已提交状态与当前进程 Kafka transport 指标。
SagaPayload: 业务作用：在 API、Outbox 与参与方之间保留正文的精确字节和 schema 身份。
SagaPayloadContract: 业务作用：把媒体类型与 schema 身份绑定到步骤定义，禁止端点轮换改变正文解释规则。
SagaPayloadError: 正文解释合同或编码不合法的稳定拒绝，不包含业务正文。
SagaProcessMetrics: 业务作用：保存同一进程内只允许存在一份的 Saga transport 与治理计数快照。
SagaResultEnvelope: 业务作用：参与方发回 Orchestrator 的结果 envelope。
SagaStepDescriptor: 业务作用：#[saga] 为每个本地步骤生成的静态合同投影。
SagaWorkflowDescriptor: 业务作用：描述一个由 #[saga_workflow] 登记的只读流程定义工厂。
ScheduledBatchReport: 业务作用：一次批次发起的低基数结果，供任务层指标与告警。
ScheduledBatchSpec: 业务作用：描述一次名义调度时刻批次的固定输入与有界预算。
ScheduledItem: 业务作用：批次内单个业务对象的发起输入。
StartSagaRequest: 业务作用：描述一次 Saga 创建请求。
TenantActionRate: 业务作用：单租户变更类管理动作的固定窗口速率上限。
VerifiedIdentity: 业务作用：envelope 通过身份复验后的强类型视图，业务路径只消费本类型。

Enums§

CommandDeliveryDisposition: 业务作用：把 Participant command 失败收敛为 transport 可执行的保留、持续收敛或隔离动作。
DefinitionCancelMode: 业务作用：声明步骤的取消屏障形态。
DefinitionCatalogError: 业务作用：封闭 Definition Catalog 可由协议层安全公开的确定性拒绝类别。
DefinitionCompensation: 业务作用：声明步骤的补偿能力。
DefinitionLifecycle: 业务作用：表示 Catalog 中不可变 definition 的生命周期。
DefinitionPublishDisposition: 业务作用：表达定义发布的幂等裁决，调用方无需解析错误文本。
DefinitionResolution: 业务作用：表达禁止未知结果或为未知结果配置有界解决通道。
DefinitionResolutionMode: 业务作用：声明未知结果的解决通道。
DefinitionTimeoutPolicy: 业务作用：声明步骤超时后的迟到成功裁决。
HandleOutcome: 业务作用：区分结果处理的两种可 ACK 结论。
ParticipantHandled: 业务作用：参与方命令处理的可 ACK 结论。
ResultDeliveryDisposition: 业务作用：把 Orchestrator 结果处理失败收敛为 transport 可执行动作。
SagaAuditRecord: 业务作用：用封闭类别承载统一审计页中的一条事实，不向协议层暴露数据库表选择逻辑。
SagaCommandProcessingError: 业务作用：用封闭类型标记 Saga command 的不可恢复投递错误。
SagaConcurrencyError: 业务作用：保留状态迁移 CAS 未生效的确定性并发裁决，禁止协议层解析错误文本。
SagaHttpMessageAuthFailure: 业务作用：表示 Saga HTTP 收据拒绝的内部稳定分类，外部响应仍必须统一脱敏。
SagaHttpReplayPlane: 业务作用：限定 replay 指标允许使用的低基数平面名，禁止把 producer/path 等用户维度写入时序。
SagaManagementError: 业务作用：封闭管理上下文、查询与写动作的确定性拒绝，供协议层稳定映射状态。
SagaManagementPermission: 业务作用：定义 Saga 管理操作的最小授权单元，避免用单一 admin 布尔值放大权限。
SagaResultProcessingError: 业务作用：用封闭类型标记 Saga result 的可信投递分类。
SagaTransactionError: 业务作用：保留 Saga 本地事务的封闭失败阶段，使 transport 不解析错误文本决定 ACK。
StartOutcome: 业务作用：区分创建入口的两种结果；AlreadyExists 表示业务幂等键命中，无新副作用。
StartSagaError: 业务作用：封闭 Saga 创建的确定性拒绝原因，供协议适配器按类型映射稳定状态。
TimerOutcome: 业务作用：区分单个 timer 的处理结论，驱动领取循环决定交还还是继续。

Constants§

CATALOG_OBJECT_KEY_MAX_LEN: capability 审计对象键的最大字符数：tenant、四个结构性身份、u32 十进制版本和五个分隔符。
COMMAND_EVENT_TYPE: command envelope 的 Outbox event type；下游按此路由到 command topic。
KIND_CANCEL_TIMEOUT: 取消命令有界重发 timer：预算耗尽升级人工介入，自动状态不允许无限滞留。
KIND_COMPENSATE_TIMEOUT: 补偿命令有界重发 timer：预算耗尽升级人工介入，不伪造 COMPENSATED。
KIND_COMPENSATION_RESOLUTION_BUDGET: 补偿 Unknown 的解决预算 timer：与正向预算隔离自然键，避免已取消行阻断后续补偿查询。
KIND_FORWARD_RESOLUTION_BUDGET: 正向 Unknown 的解决预算 timer：超期升级人工介入，绝不自动降级为 Rejected。
KIND_INSTANCE_DEADLINE: 实例级业务 deadline timer：到期按实例所处阶段执行固定裁决。
KIND_RESOLUTION_BUDGET: 旧版未区分方向的 Unknown 解决预算 timer；仅用于滚动升级期间消费既有行。
KIND_RESOLVE_TIMEOUT: 解决查询有界重发 timer：在解决预算内按 attempt 重发 resolve 命令。
KIND_STEP_TIMEOUT: 步骤 execute 超时 timer：到期进入取消屏障，绝不直接补偿。
RESULT_EVENT_TYPE: result envelope 的 Outbox event type；下游按此路由到 result topic。
SAGA_AGGREGATE_TYPE: Saga 事件的聚合类型；aggregate_id = saga_id 兼作 Kafka partition key—— 顺序只是优化，正确性只依赖状态机、Inbox 与 CAS。
SAGA_COMMAND_DEAD_LETTER_REASONS: command DLT 接收端可信的全部稳定原因码。
SAGA_LATENCY_BUCKETS: 阶段耗时的秒单位桶边界；最后一个桶包含超过最大边界的样本。

Statics§

COLLECTED_SAGA_STEPS: 当前 binary 内 #[saga] 收集到的全部本地步骤合同。
COLLECTED_SAGA_WORKFLOWS: 当前二进制内 #[saga_workflow] 收集到的全部流程定义工厂。

Traits§

SagaCommandService: 业务作用：抽象宏生成的类型化步骤分发入口，供 hosted command consumer 绑定具体 Service。
SagaHttpCredentialSource: 业务作用：让所有入站和出站认证器从同一受信配置快照读取当前凭据。

Functions§

classify_command_delivery_error: 业务作用：为 hosted command consumer 形成不依赖错误文本的重试与隔离分类。
classify_result_delivery_error: 业务作用：为 hosted result consumer 形成不依赖错误文本的重试、延后与隔离分类。
collect_workflow_definitions: 业务作用：调用当前二进制内全部流程工厂，并构造不可变、按定义键去重的注册表快照。
command_dead_letter_reason: 业务作用：从 command 错误链提取可安全跨 transport 传播的封闭 DLT 原因码。
derive_result_event_id: 业务作用：从命令身份确定性派生 result 事件身份，使参与方崩溃重试不产生第二个结果事件身份。
derive_scheduled_business_key: 业务作用：从“任务名 + 名义调度时刻 + 对象稳定身份“确定性派生批次内业务幂等键。
derive_timer_id: 业务作用：由作用域与种类确定性派生 timer 身份，使调度重试跨进程幂等。
process_metrics_snapshot: 业务作用：读取 MySQL 与 PostgreSQL wrapper 共同维护的 process metrics 快照。
record_action_rate_rejection: 业务作用：累计一次按租户频率拒绝的变更类管理动作。
record_kafka_ack: 业务作用：记录 Saga result 在本地提交后完成 ACK，并区分 Inbox 重复吸收。
record_kafka_command_ack: 业务作用：记录 Saga command 在参与方提交后完成 ACK，并区分 Inbox 重复吸收。
record_kafka_command_dlt_requested: 业务作用：记录 Saga command 已请求进入 durability-first DLT。
record_kafka_command_processing: 业务作用：记录一次 Kafka Saga command handler 的单调耗时。
record_kafka_command_retry: 业务作用：记录 Saga command 因参与方事务未提交而保留 offset 重投。
record_kafka_dlt_requested: 业务作用：记录 Saga result 已请求进入 durability-first DLT。
record_kafka_processing: 业务作用：记录一次 Kafka Saga result handler 的单调耗时。
record_kafka_retry: 业务作用：记录 Saga result 因本地事务未提交而保留 offset 重投。
record_quota_rejection: 业务作用：累计一次按租户配额拒绝的创建请求。
render_saga_http_command_dlt_metric: 业务作用：渲染 HTTP command 确定性协议拒绝已持久化到 DLT 的低基数总量。
render_saga_latency_metrics: 业务作用：将固定阶段耗时渲染为可聚合直方图，支持 histogram_quantile 查询。
saga_latency_snapshot: 业务作用：读取全部阶段的同一时刻快照，不清零累计值。
select_capability_route: 业务作用：从有效能力快照中按完整步骤身份选择唯一数据面 route，避免同租户同名 endpoint 的无关能力替代目标 descriptor 参与地址政策裁决。
select_capability_routes: 业务作用：取得同一步骤的完整逐实例直接路由集合，允许 HTTP/gRPC 副本使用独立 endpoint。参数说明：capabilities 是仍在租期内的同代快照；transport、tenant、definition、step 共同限定步骤合同。返回：合法 HTTP/gRPC 路由按 endpoint 与副本身份排序；消息代理仍要求唯一目标，非法或同副本冲突时拒绝。
validate_capability_route_contract: 业务作用：按 command transport 复验 capability 的完整可发布 route 合同，确保目录准入、 candidate 激活与实际 publisher 对同一 descriptor 得出一致结论。
validate_redis_stream_route: 业务作用：按 Redis Cluster 实际选 slot 的规则校验 stream 名与运行配置的同槽合同。
verify_descriptors: 业务作用：在 Ready 前复验本地步骤合同唯一且与 definition 一致。

Crate nasaga_runtime_core

Crate nasaga_runtime_core Copy item path

Re-exports§

Structs§

Enums§

Constants§

Statics§

Traits§

Functions§

Crate nasaga_runtime_core