[RFC] Unified Error Status Model and Panic Policy

[feichai0017]

Background

NoKV currently uses plain error, ad-hoc error strings, and panic across different modules. This creates three problems:

• Error semantics are inconsistent, so callers cannot reliably classify retry vs conflict vs internal failures.
• Cross-layer mapping is unclear (engine -> raftstore -> rpc/client).
• Service robustness is weaker, because some recoverable misuse paths can still trigger panic.

Goal

Define a unified Error Status model and a clear panic policy:

• Externally (API/RPC): deterministic, observable, and testable behavior.
• Internally (between modules): minimal friction and no unnecessary wrapper noise.
• Migration should be incremental, not a single breaking rewrite.

Non-Goals

• This RFC does not introduce a full retry framework.
• This RFC does not rewrite every existing error path in one pass.

Proposal (Draft)

1) Unified status codes (StatusCode)

Proposed minimum set:

• OK
• InvalidArgument
• NotFound
• AlreadyExists
• Conflict
• DeadlineExceeded
• Unavailable
• ResourceExhausted
• Internal

2) Unified status object (Status)

Proposed fields:

• Code
• Message
• Cause (optional, internal debugging)
• Op (optional, operation name)
• Retryable (optional)

3) Panic policy

• panic is allowed only for impossible internal invariant violations.
• Caller misuse, invalid input, and runtime state errors must return Status/Error, not panic.

4) Layered mapping

• Engine/LSM/VLog/Txn: return unified Status/Error.
• RaftStore: preserve region/leader semantics and map into unified codes.
• RPC layer: map unified codes to gRPC status + structured message.

Migration Plan (Incremental)

1. Add a status package and mapping helpers first, without changing core behavior.
2. Migrate 1-2 high-risk paths first (e.g., iterator/txn constructors, vlog read/write paths).
3. Replace panic-on-misuse paths gradually and add regression tests.
4. Document an error semantics matrix (module x scenario x status code).

Open Questions

1. Should code naming align with TiKV/etcd conventions for easier interoperability?
2. Should Cause be process-local only, or partially propagated across RPC boundaries?
3. When should panic-to-status changes be treated as a coordinated breaking release?

Feedback welcome on:

• Whether the code set is too small or too broad.
• Which migration path should be prioritized first.
• External API compatibility constraints.