CMDCGateway.TaskStore (cmdc_gateway v0.4.2)

Copy Markdown View Source

A2A Task 状态短期缓存。

A2A 协议「兜底查询」机制 — 当 webhook 派发失败 / 客户端漏接收时,可通过 GET /v1/a2a/tasks/:id 主动拉取最近一次 task 状态。

设计

  • ETS 表 :cmdc_gateway_task_storetask_id 索引,存放最近 10 分钟 内的 task 状态快照
  • 每次 webhook 派发时(无论成功失败)由 A2A.start_with_webhook/3 内部 dispatch_webhook/5 同步 update 一次状态
  • GenServer 后台定时 GC,默认每 60s 扫一遍清理过期条目
  • 不持久化(重启即丢,仅做"短期兜底",与 12M.1 dead-letter 长期 持久化职责正交)

公共 API

TaskStore.put(task_id, status_atom, payload, opts \ [])
TaskStore.get(task_id) :: {:ok, map} | {:error, :not_found}
TaskStore.delete(task_id)
TaskStore.list_recent(limit \ 50)

ETS 行格式

{task_id, %{
  task_id: String.t(),
  status: :accepted | :working | :completed | :failed,
  last_event: :accepted | :status_update | :artifact_update
            | :completed | :failed,
  payload: map(),
  updated_at_ms: integer(),
  ttl_until_ms: integer()
}}

Summary

Functions

Returns a specification to start this module under a supervisor.

删除指定 task_id 的条目,主要用于测试 / 手动清理。

强制运行一次 GC(清理所有过期条目),主要用于测试。

查询 task 状态。

列出最近 N 个 task(按 updated_at_ms 倒序),用于运维查看。

写入 / 更新 task 状态。

启动 TaskStore GenServer + ETS 表。

Types

entry()

@type entry() :: %{
  task_id: task_id(),
  status: status(),
  last_event: atom(),
  payload: map(),
  updated_at_ms: integer(),
  ttl_until_ms: integer()
}

status()

@type status() :: :accepted | :working | :completed | :failed

task_id()

@type task_id() :: String.t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

delete(task_id)

@spec delete(task_id()) :: :ok

删除指定 task_id 的条目,主要用于测试 / 手动清理。

gc_now()

@spec gc_now() :: non_neg_integer()

强制运行一次 GC(清理所有过期条目),主要用于测试。

get(task_id)

@spec get(task_id()) :: {:ok, entry()} | {:error, :not_found}

查询 task 状态。

返回 {:ok, entry},或在 task 未知 / 已过期时返回 {:error, :not_found}

list_recent(limit \\ 50)

@spec list_recent(pos_integer()) :: [entry()]

列出最近 N 个 task(按 updated_at_ms 倒序),用于运维查看。

put(task_id, event, payload, opts \\ [])

@spec put(task_id(), atom(), map(), keyword()) :: :ok

写入 / 更新 task 状态。

选项

  • :status — 显式覆盖;默认从 event 推导(accepted/status_update→working/ artifact_update→working/completed/failed)
  • :ttl_ms — 自定义 TTL;默认 600_000 (10 分钟)

start_link(opts \\ [])

启动 TaskStore GenServer + ETS 表。

选项

  • :gc_interval_ms — GC 触发间隔;默认 60_000 (1 分钟)
  • :default_ttl_ms — 单条 TTL;默认 600_000 (10 分钟)
  • :name — 进程名;默认 __MODULE__