用途:当需要为 CocoIndex 新建目标连接器,将声明式目标状态系统接入外部系统(数据库、文件系统、云存储、API 等)时使用。连接器通过比较期望状态与历史跟踪记录,判断变化并应用到外部系统。
主要能力:实现 TargetHandler 的 reconcile(),实现 TargetActionSink 执行动作,维护 TrackingRecord 做变更检测;支持根目标状态与嵌套的子目标状态;通过 child_invalidation 处理容器级失效(destructive 或 lossy)。
使用方式:定义 Key、Spec、TrackingRecord、Action 类型;实现 TargetHandler(reconcile() 必须非阻塞,仅比较状态并返回动作);用 TargetActionSink.from_fn() 或 from_async_fn() 创建 sink,回调第一个位置参数为 context_provider: ContextProvider;调用 register_root_target_states_provider(name, handler) 注册;再用 declare_target_state() 或 declare_target_state_with_child() 声明目标状态。
适用场景:数据库表/行两级同步、文件系统目录与嵌套文件、云存储与 API 集成等。
限制与要求:动作应幂等;prev_possible_records 可能包含多条记录;外部资源身份建议用 ContextKey 字符串而非连接参数,以保证键稳定;构建查询须防注入;需补充可选依赖、文档与测试。资料完整实现细节与附件提供方请参见随附文档与参考实现。