Sync Invoker

​

职责与边界

• 接收 Invoke / DebugInvoke，执行已注册函数（function_id）或临时源码（inline_source），返回 result_json / Failure、execution_duration_ms、queue_wait_ms。
• admission：在 N 个 executor × K 个 context 槽位里选一个负载最低的 executor 派发；打满时返回 RESOURCE_EXHAUSTED。
• deadline：到点只发软 CancelCall，然后等 executor 的真实终态（协作 cancel / SIGALRM）或兜底 sweep（wedge / 心跳超时）收敛。
• subcall：父函数发起的子调用在同一个 executor 上派发，父子共享一个 deadline、一个 code epoch 和一个 IO scope。
• Precheck：对源码只做静态审计，不执行；返回 pass + findings。
• 执行归因：execution_duration_ms = 整棵 subcall tree 的 effective CPU + 本 call 的 IO backend 时长；EXECUTOR_LOST 一律计 0 且 retryable。
• 失败来源标注：每个失败带 FailureOrigin（USER / SYSTEM / CAPACITY / UNKNOWN），准入层失败通过 google.rpc.ErrorInfo.metadata 携带。

• 鉴权、API Key、限流、计费、业务级并发控制（网关侧）。
• 任何写路径：HandleIO 拒绝 mode == "write"；不接 BlockDB writer / Event Writer / ResultHandler。
• task 编排：没有 readyQueue、fairness、失败重试、call result cache、callbuilder / writer plugin。
• 服务端重试：一个 call 至多进一次 EXECUTING，retry 由 SDK 发新 call。

• 终态不可逆：core.Registry.Finish 是唯一终态门，每个 call 只放行一次；迟到的 executor / IO / subcall 结果丢弃。
• 一个 call 至多进一次 EXECUTING（Registry.Bind 只接受 ACCEPTED）。
• 每次 sync-call（含 inline）在 ACCEPTED 时 pin 当前 FCV epoch，随 ExecuteCallPayload.TaskCodeEpoch 下发，子调用继承。
• 计量数字只来自 executor 的真实终态 payload，或在 EXECUTOR_LOST 时明确为 0；不从心跳快照推断。
• 配置约束：MaxCallDeadlineMs + heartbeat_interval < SchedulerStallTimeoutMs，否则进程启动时拒绝（cmd/syncinvoker/main.go）。
• [reg.Bind → SendExecuteCall]、deadline / client-gone 的 subtree 清理、executor-lost fan-out 三者共享 Service.dispatchMu，两两互斥。

​

代码位置

​

核心类型与接口

​

core（Sans-IO）

• core.CallState（internal/syncinvoker/core/call.go）：ACCEPTED / EXECUTING + 六个终态；IsTerminal()。
• core.FailureCode / core.FailureOrigin / core.Failure：与 proto 枚举同值但不依赖 proto；FailureTerminal(f) 按 code 选终态并用 defaultFailureOrigin 补 origin。
• core.Terminal：交给等待者的最终结果，带 EffectiveDurationUs、QueueWaitUs、IOBackendDurationMs、Debug。
• core.Registry：Accept / AcceptSubcall / Bind / Finish / Drop / Subtree / CallsByRoot / InflightCount / MarkTerminating / ObserveSnapshot。executor 健康只有 HealthReady / HealthTerminating，用 attach generation 区分 replacement 与被杀进程的残影。
• core.CallMeta：accept 时 pin 的 Epoch、CacheKey（环检测）、DeadlineMs、Root。
• core.PickExecutor(loads, maxInflight) / core.RankExecutors(loads, maxInflight, shuffle)（admission.go）：默认策略与 admit-spread 策略。

​

adapters

• adapters.ServiceConfig（service.go）：DefaultDeadlineMs、ExecutorMaxInflight、MaxCallDeadlineMs、MaxAcceptedDeadlineMs、SchedulerStallTimeoutMs、AdmitSpread。
• adapters.Service：NewService(cfg, exec, codeView) 构造时就把回调挂到 executor adapter 上（wireExecutorCallbacks）。主要方法：

func (s *Service) Invoke(ctx context.Context, in InvokeInput) (InvokeOutput, error)
func (s *Service) Precheck(ctx context.Context, in PrecheckInput) (PrecheckOutput, error)
func (s *Service) HandleIO(ctx context.Context, taskID, callID string, req *executor.IORequest) (any, error)
func (s *Service) HandleSubcall(ctx context.Context, executorID, parentCallID, requestID, functionID string, argsJSON json.RawMessage, ancestry []string, _ int64) error
func (s *Service) CheckWedgedExecutors()

• adapters.ExecutorAdapter（exec_adapter.go）：Bind / BindSubcall / Unbind / MarkDraining / SendExecuteCall / SendResumeCall / SendCancelCall / Snapshots + SetCallbacks / SetExecutorLostCallback / SetIOHandler / SetSubcallHandler。测试注入 stub，生产传 *executor.Adapter。
• adapters.FunctionCodeView：CurrentEpoch() + Fetch(functionID, epoch)，fccore.SnapshotStore 直接满足。可为 nil（只支持 inline）。
• adapters.GRPCServer（grpc_server.go）：Invoke / DebugInvoke / Precheck 三个 handler；准入失败时 mirrorCallID 把 call_id 写进 trailer x-blockx-sync-call-id。
• callScope（service.go，未导出）：按 sync-call 建的 iocore.TaskIOScope + cancel + in-flight IO 计数；整棵 subcall tree 共用 root 的 scope。

​

协议（api/grpc/syncinvoker/sync_invoker.proto）

​

数据流 / 执行流程

​

状态与生命周期

1. 对 Subtree 和 root 只发软 SendCancelCall，都不 Finish；quiesceCallScope 停新 IO。
2. 有界等 w.ch，窗口 deadlineEscalationWindow = max(5s, 2×SchedulerStallTimeoutMs + 2s)。四条路径都会送信号：executor 协作 cancel 或 SIGALRM 自愈发真实终态；CheckWedgedExecutors 检测 scheduler 冻结超过 SchedulerStallTimeoutMs 且 RunningCallId 已过 deadline → reapExecutorCause("wedge_sweep")；心跳超时 → adapter 的 executor-lost 回调 → reapExecutor；超窗 → reapExecutorCause("deadline_escalation") 强制收敛。
3. 收到终态后用 CallsByRoot 清掉 grace 期间新加的 subcall，最终 Failure 统一覆盖为 TIMED_OUT（origin UNKNOWN）。

​

与 Worker 的差异

• internal/worker/adapters/executor：Adapter（UDS server、Bind / BindSubcall / Unbind / MarkDraining、心跳、Snapshots）、PoolManager（fork N 个 Python executor、崩溃拉起、KillExecutor）、IOHandler / SubcallHandler / IORequest 接口。
• internal/worker/core：只用 ExecutorSnapshot。
• internal/worker/devstub：StubBackendAdapter，未配置外部后端时的 IO stub。
• internal/functioncode/*：SnapshotStore、Redis / BlockDB syncer、audit.Pool。
• internal/io/core、internal/io/assembly、internal/io/adaptive：WorkerIOScope / TaskIOScope、backend 装配、AIMD admission。
• internal/sdk/*：blockdb / noderpc / localtestservice / router 客户端。
• api/uds：ExecuteCallPayload / CallCompletedPayload / CallFailedPayload / ResumeCallPayload。

​

Precheck 与 audit gate

• FUNCTION_CODE_AUDIT_MODE 只管 Invoke gate：SetAuditGateOff(true)（off）/ SetAuditDark(true)（dark）/ 都不设（enforce）。
• Precheck 无视 mode 与 space allowlist，固定按 _ entry 审计，返回真实判定。审计不过是 OK + pass=false + findings；只有产不出判定才 non-OK：FAILED_PRECONDITION（无 auditor）、UNAVAILABLE（auditor 宕机）、INVALID_ARGUMENT（空源码）、CANCELED / DEADLINE_EXCEEDED（调用方 ctx 取消，单独计数）。
• enforce 模式下 auditor 启动失败进程拒绝启动；off / dark 降级为无 auditor（Invoke 不 gate，Precheck 返回 FAILED_PRECONDITION）。

​

失败分类与归因

• classifyFailure：execute_call_rejected → CODE_LOAD_FAILED；runtime_error / cancelled → CALL_FAILED；deadline_exceeded → TIMED_OUT；transport_lost / resume_send_failed / terminal_decode_failed → EXECUTOR_LOST；executor_capacity_exhausted → EXECUTOR_CAPACITY_EXHAUSTED；IO classifier 的 system_error / retryable_io / param_error / non_retryable / timeout / scope_closed → IO_PROXY_FAILED。
• failureRetryable：EXECUTOR_LOST / EXECUTOR_CAPACITY_EXHAUSTED 恒 true；IO_PROXY_FAILED 尊重 payload 的 retryable；其余 false。
• classifyFailureOrigin：按 ErrorKind + 内部 DetailCode（如 grpc:NotFound → USER，syncinvoker:io_not_configured → SYSTEM）+ ChildOrigin（subcall_failed 继承子调用 origin）；deadline_exceeded 归 UNKNOWN。完整表见 docs/specs/sync-invoker-failure-origin.md。
• 准入层：denyAdmission → withCallID 把 call_id 与 failure_origin 写进 ErrorInfo.metadata，classifyAdmissionOrigin 按 reason / gRPC code 定 origin。

​

配置

​

观测

• blockx_syncinvoke_calls_total{status, failure_code}：执行层终态计数（不含准入拒绝）。
• blockx_syncinvoke_admission_denied_total{reason}：dispatch 前拒绝。
• blockx_syncinvoke_call_duration_milliseconds / blockx_syncinvoke_billed_duration_milliseconds / blockx_syncinvoke_queue_wait_milliseconds：端到端墙钟、归因时长、排队。
• blockx_syncinvoke_deadline_overruns_total{resolved_by}：超 deadline 的 call 由哪一层收敛（completed_late / cooperative_cancel / in_process_timeout / executor_reaped / escalation_reap）。
• blockx_syncinvoke_executor_reaps_total{cause} / blockx_syncinvoke_executor_lost_victims_total{cause}：hard kill 频率与连坐量，健康时应为 0。
• blockx_syncinvoke_precheck_total{result}。

​

部署形态

​

扩展点

• 新增失败分类：改 classifyFailure / failureRetryable / classifyFailureOrigin（service.go），若要新 code 需同步 core.FailureCode、proto FailureCode、failureCodeToProto、failureCodeLabel。
• 新增 admission 策略：在 core/admission.go 加纯函数，在 Service.admit 里按 ServiceConfig 开关切换；只依赖 ExecutorLoad。
• 新增只读 IO backend：在 cmd/syncinvoker/io.go 的 ioBackendModules 追加一个 assembly.Module，与 cmd/worker 保持同款注册。
• 新增 FCV 来源：在 cmd/syncinvoker/function_code.go 的 setupFunctionCodeView 增加分支，返回 functionCodeSetup{view, start, close, desc, devstub}。
• 新增 RPC：改 api/grpc/syncinvoker/sync_invoker.proto → make proto → GRPCServer 加 handler → Service 加传输无关的 XxxInput / XxxOutput。
• 新增配置项：Config 字段 + DefaultConfig + LoadConfigFromEnvChecked 里的 envXxx，需要时透传到 ServiceConfig。

​

测试

# 首次或 python/uv.lock 变更后
uv sync --project python

# core / adapters 单元测试（stub executor，不起 Python）
go test ./internal/syncinvoker/...

# 进程级 E2E（真实 Python executor，pythonBin() 优先用 python/.venv）
go test -v -timeout 300s ./cmd/syncinvoker/...

• internal/syncinvoker/core/*_test.go：Registry 终态门、executor 健康 / attach generation、PickExecutor / RankExecutors。
• internal/syncinvoker/adapters/service_test.go：admission、subcall 竞态、onDeadline / onClientGone、duration 聚合、失败分类；audit_gate_test.go：enforce / dark / allowlist；precheck_test.go：Precheck 各种返回码。
• cmd/syncinvoker/syncinvoker_process_test.go：startSyncInvoker 起真实进程，覆盖 inline / function_id / debug / 只读 IO / 写拒绝 / subcall / RESOURCE_EXHAUSTED / CPU hog 自愈 / wedge hard kill / graceful shutdown / health probe。
• cmd/syncinvoker/syncinvoker_perf_test.go：延迟分解 perf 测试；syncinvoker_sandbox_e2e_test.go 带 build tag sandbox_e2e。
• Makefile 把 cmd/syncinvoker 列为 SLOW_TEST_PACKAGES，make test 对它逐文件跑（每个文件独立 SYNCINVOKER_TEST_TIMEOUT，默认 3m），避免整包超时。

​

相关文档

• blockx 仓库 docs/specs/sync-invoker.md：形态、协议、admission、deadline 分层、subcall、生命周期、复用边界、归因、容量。
• blockx 仓库 docs/specs/sync-invoker-failure-origin.md：FailureOrigin 语义与映射表。
• blockx 仓库 docs/sync-invoker-grafana.md：指标清单、PromQL、排障路径。
• blockx 仓库 docs/deploy/syncinvoker-systemd-nerdctl.md：EC2 runbook。
• 站内：Worker、Call 执行子系统、Python Executor、Function Code View、IO 访问子系统、可观测性、协议与接口。