CMDCGateway.TaskStore (cmdc_gateway v0.4.1)

Copy Markdown View Source

A2A Task 状态短期缓存 — Phase 12M v0.4.1 (12M.4)。

对应 ADP Ch.15 A2A 协议的「兜底查询」要求 — 当 webhook 派发失败 / 客户端漏接收时，可通过 GET /v1/a2a/tasks/:id 主动拉取最近一次 task 状态。

设计

  • ETS 表 :cmdc_gateway_task_store 按 task_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

Types

entry()
status()
task_id()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

delete(task_id)

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

gc_now()

强制运行一次 GC（清理所有过期条目），主要用于测试。

get(task_id)

查询 task 状态。

list_recent(limit \\ 50)

列出最近 N 个 task（按 updated_at_ms 倒序），用于运维查看。

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

写入 / 更新 task 状态。

start_link(opts \\ [])

启动 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__