semtech/mu-delta-notifier

Delta Notifier

镜像概述和主要用途

该组件接收来自mu-authorization的原始delta消息，并将其转发给感兴趣的实体，是mu.semte.ch微服务架构中实现变更通知传递的关键组件。

核心功能和特性

• 消息转发：接收mu-authorization发送的delta变更消息并转发至指定服务
• 灵活配置：支持通过规则文件自定义匹配模式和转发目标
• 多格式支持：提供多种delta消息格式，适配不同服务需求
• 调试能力：通过环境变量启用详细日志，便于排查配置和通信问题

使用场景和适用范围

适用于mu.semte.ch微服务生态系统中需感知数据变更的场景：

• 跨服务数据同步触发
• 业务事件通知（如资源创建/修改/删除）
• 分布式系统状态一致性维护

使用方法和配置说明

在mu-semtech栈中连接mu-delta-notifier

delta-notifier需接收mu-authorization的消息并发送至其他服务。因直接使用docker-compose的link选项会形成循环依赖（some-service -> mu-authorization -> delta-notifier -> some-service），建议在docker-compose注释中记录消费delta服务的服务，确保应用流程清晰。

配置mu-authorization与mu-delta-notifier的详细信息见mu-authorization文档。当前可在mu-authorization的配置目录（通常为config/authorization/）添加delta.ex文件，内容如下：

elixir
defmodule Delta.Config do
  def targets do
    [ "http://deltanotifier" ]
  end
end

将delta-notifier包含到你的栈中

docker-compose中默认包含delta-notifier的配置如下：

yml
  deltanotifier:
    image: semtech/mu-delta-notifier
    volumes:
      - ./config/delta:/config

接收delta通知

接收服务需通过config/delta/rules.js配置。该文件格式可能迭代，但核心目标是使消费服务能一致接收特定格式消息，通过resourceFormat键选择格式。

配置示例

以下是连接资源服务的config/delta/rules.js示例：

js
export default [
  {
    match: {
      // 元素格式为 {subject,predicate,object}
      // predicate: { type: "uri", value: "http://www.semanticdesktop.org/ontologies/2007/03/22/nmo#isPartOf" }
    },
    callback: {
      url: "http://resource/.mu/delta", method: "POST"
    },
    options: {
      resourceFormat: "v0.0.0-genesis",
      gracePeriod: 1000,
      ignoreFromSelf: true
    }
  }
]

配置参数说明

导出的数组包含多个规则定义，每个定义包含：

• match：消息匹配规则（指定键需匹配，未指定键忽略）
  • subject：匹配主语（可指定type和value）
  • predicate：匹配谓语（可指定type和value）
  • object：匹配宾语（可指定type和value）
• callback：通知目标配置
  • url：接收通知的服务URL
  • method：发送通知的HTTP方法
• options：转发选项
  • resourceFormat：消息格式版本（不可删除字段，可按需过滤）
  • gracePeriod：延迟发送时间（毫秒），用于合并短时间内的变更
  • ignoreFromSelf：是否忽略目标服务自身发起的变更（基于主机名判断）

Delta格式

通过options.resourceFormat指定消息格式，版本需完全匹配字符串。

v0.0.1

最新格式，未来可能扩展授权等功能。值编码遵循json-sparql规范RDF术语编码。示例：

json
[
  { 
    "inserts": [
      {
        "subject": { "type": "uri", "value": "http://mu.semte.ch/" },
        "predicate": { "type": "uri", "value": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type" },
        "object": { "type": "uri", "value": "https://schema.org/Project" }
      },
      {
        "subject": { "type": "uri", "value": "http://mu.semte.ch/" },
        "predicate": { "type": "uri", "value": "http://purl.org/dc/terms/modified" },
        "object": { "type": "literal", "value": "https://schema.org/Project", "datatype": "http://www.w3.org/2001/XMLSchema#dateTime" }
      }
    ],
    "deletes": [] 
  }
]

v0.0.0-genesis

初始PoC格式，示例：

json
{ 
  "delta": {
    "inserts": [
      {
        "s": "http://mu.semte.ch/",
        "p": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
        "o": "https://schema.org/Project"
      }
    ],
    "deletes": [] 
  }
}

false或undefined

任何假值不会向消费服务发送变更三元组，适用于仅需触发数据库状态检查的场景。

调试

通过设置环境变量启用调试日志：

• DEBUG_DELTA_SEND：记录发送给客户端的所有delta消息
• DEBUG_DELTA_MATCH：记录每个目标块的检查事件
• DEBUG_TRIPLE_MATCHES_SPEC：详细记录匹配规则的三元组，排查请求未发送问题

扩展

鼓励社区贡献以完善服务功能。可Fork仓库进行实验，通过issue或PR分享结果；如需讨论扩展方向，欢迎提交issue。