feat!: add IntoErrorPayload trait for structured JSON-RPC errors by prestwich · Pull Request #42 · init4tech/ajj

prestwich · 2026-03-24T17:18:53Z

Summary

Adds IntoErrorPayload trait that lets handler error types control JSON-RPC error code, message, and data fields when returning Result<T, E>
Adds InternalError<T> wrapper for placing a value in the error data field with code -32603
Adds convenience impls for ErrorPayload, String, &'static str, ()
Adds internal IntoResponsePayload trait to unify the macro conversion path
Removes From<Result<T, E>> for ResponsePayload, From<T> for ErrorPayload<T> where T: Error + RpcSend, and convert_internal_error_msg
Adds magic8ball example showcasing custom error types with per-variant error codes and structured data
Bumps version to 0.7.0

Breaking changes

Result<T, E> handlers now require E: IntoErrorPayload instead of E: RpcSend
String/&str errors now populate the message field (previously went in data)
Removed From<Result<T, E>> for ResponsePayload, From<T> for ErrorPayload<T> where T: Error + RpcSend, and ResponsePayload::convert_internal_error_msg
Migration: wrap error types in InternalError<E> for the old behavior, or implement IntoErrorPayload for custom error codes

Test plan

Unit tests for all IntoErrorPayload impls (ErrorPayload identity, InternalError, String, &str, (), custom error type)
Unit tests for IntoResponsePayload (Result and ResponsePayload paths)
Existing handler inference tests pass
All doc tests compile and pass
Integration tests (ws, ipc, axum) pass
Clippy clean with --all-features and --no-default-features
magic8ball example compiles and demonstrates all error paths

Closes ENG-2085

🤖 Generated with Claude Code

Adds the public IntoErrorPayload trait with error_code, error_message, error_data, and into_error_payload methods. Adds convenience impls for ErrorPayload, InternalError<T>, String, &'static str, and (). ENG-2085 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Unifies Result and ResponsePayload conversion paths for the handler macro. Result<T, E: IntoErrorPayload> delegates to into_error_payload(). ResponsePayload<T, E> passes through unchanged. ENG-2085 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Prepares for IntoErrorPayload by routing through the new internal IntoResponsePayload trait instead of From<Result<T, E>>. Also updates OutputResult handler bounds from ErrData: RpcSend to ErrData: IntoErrorPayload, as these changes are co-dependent. ENG-2085 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

BREAKING: Removes From<Result<T, E>> for ResponsePayload, From<T> for ErrorPayload<T> where T: Error + RpcSend, and ResponsePayload::convert_internal_error_msg. These are replaced by the IntoErrorPayload and IntoResponsePayload traits. ENG-2085 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ENG-2085 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Breaking changes in this release: - Handler Result<T, E> error types must implement IntoErrorPayload - String/&str errors now populate the message field (not data) - Removed From<Result> for ResponsePayload, From<T> for ErrorPayload, and convert_internal_error_msg Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Demonstrates custom error types with per-variant JSON-RPC error codes, messages, and structured error data via the IntoErrorPayload trait. ENG-2085 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Remove the blanket `From<T>` impl on `InternalError<T>` so that wrapping a value requires explicit `InternalError(val)` construction. This prevents silent semantic shifts when switching between `String` (→ message field) and `InternalError<String>` (→ data field) as handler error types. Also gitignore /docs to prevent plan files from being committed. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Fraser999

All just non-blocking nits.

Fraser999 · 2026-03-26T12:35:05Z

examples/magic8ball.rs

+        let data = match &self {
+            Self::CrystalBallCloudy => serde_json::value::to_raw_value(&CloudyDetail {
+                visibility: "opaque",
+                suggestion: "try polishing the ball",
+            })
+            .ok(),
+            Self::StarsMisaligned { sign } => {
+                serde_json::value::to_raw_value(&MisalignmentDetail {
+                    sign: sign.clone(),


Suggested change

let data = match &self {

Self::CrystalBallCloudy => serde_json::value::to_raw_value(&CloudyDetail {

visibility: "opaque",

suggestion: "try polishing the ball",

})

.ok(),

Self::StarsMisaligned { sign } => {

serde_json::value::to_raw_value(&MisalignmentDetail {

sign: sign.clone(),

let data = match self {

Self::CrystalBallCloudy => serde_json::value::to_raw_value(&CloudyDetail {

visibility: "opaque",

suggestion: "try polishing the ball",

})

.ok(),

Self::StarsMisaligned { sign } => {

serde_json::value::to_raw_value(&MisalignmentDetail {

sign,

Fraser999 · 2026-03-26T13:23:17Z

examples/magic8ball.rs

+            Self::CrystalBallCloudy => -32001,
+            Self::StarsMisaligned { .. } => -32002,
+            Self::MercuryRetrograde => -32003,
+            Self::UnreadableAura(_) => -32004,


My interpretation of the spec makes me think we shouldn't be using error codes in the range [-32099, -32000] for application errors like this, but only for errors specific to our JSON RPC implementation - i.e. for ajj to use itself.

Fraser999 · 2026-03-26T13:37:46Z

src/routes/handler.rs

    Fut: Future<Output = Result<Payload, ErrData>> + Send + 'static,
    Payload: RpcSend,
-    ErrData: RpcSend,
+    ErrData: IntoErrorPayload,


Now that we have IntoErrorPayload with an associated type ErrData, it might be helpful to rename all these ErrData type params in this file to something like E or Error?

Fraser999 · 2026-03-26T13:40:59Z

src/types/resp/into_error.rs

+///             Self::NotFound(_) => 404,
+///             Self::RateLimited { .. } => 429,


nit: these look like http error codes, which could give readers the wrong impression that an http error would be returned in these cases.

Fraser999 · 2026-03-26T13:44:31Z

src/types/resp/into_error.rs

+        -32603
+    }
+}
+


We could maybe add an impl IntoErrorPayload for core::convert::Infallible?

Fraser999 · 2026-03-26T13:48:42Z

src/types/resp/into_error.rs

+/// Only [`error_code`] is required. The remaining methods have sensible
+/// defaults:


Suggested change

/// Only [`error_code`] is required. The remaining methods have sensible

/// defaults:

/// Only [`error_code`] and the associated type `ErrData` must be specified.

/// The remaining methods have sensible defaults:

- Use application-level error codes instead of reserved JSON-RPC range - Fix doc example codes that looked like HTTP status codes - Add IntoErrorPayload impl for core::convert::Infallible - Clarify that ErrData associated type is required in trait docs - Refactor magic8ball match to take ownership, removing unnecessary clone Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

prestwich and others added 9 commits March 24, 2026 13:04

docs: update Handler trait rustdoc for IntoErrorPayload

62a1db6

ENG-2085 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs: update lib.rs module docs for IntoErrorPayload

8e1b652

ENG-2085 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs: update examples and comments for IntoErrorPayload

9ed0c70

ENG-2085 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat: add magic8ball example showcasing IntoErrorPayload

0cace46

Demonstrates custom error types with per-variant JSON-RPC error codes, messages, and structured error data via the IntoErrorPayload trait. ENG-2085 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

prestwich requested review from Evalir and Fraser999 March 24, 2026 17:22

prestwich mentioned this pull request Mar 25, 2026

feat(rpc): structured JSON-RPC error codes for all endpoints init4tech/node-components#119

Open

6 tasks

Fraser999 approved these changes Mar 26, 2026

View reviewed changes

prestwich merged commit 4556396 into main Mar 26, 2026
6 checks passed

prestwich mentioned this pull request Mar 26, 2026

fix: address review nits from #42 #43

Open

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat!: add IntoErrorPayload trait for structured JSON-RPC errors#42

feat!: add IntoErrorPayload trait for structured JSON-RPC errors#42
prestwich merged 10 commits intomainfrom
prestwich/into-error-payload

prestwich commented Mar 24, 2026 •

edited

Loading

Uh oh!

Fraser999 left a comment

Uh oh!

Fraser999 Mar 26, 2026

Uh oh!

Fraser999 Mar 26, 2026

Uh oh!

Fraser999 Mar 26, 2026

Uh oh!

Fraser999 Mar 26, 2026

Uh oh!

Fraser999 Mar 26, 2026

Uh oh!

Fraser999 Mar 26, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		/// Self::NotFound(_) => 404,
		/// Self::RateLimited { .. } => 429,

		/// Only [`error_code`] is required. The remaining methods have sensible
		/// defaults:

Conversation

prestwich commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking changes

Test plan

Uh oh!

Fraser999 left a comment

Choose a reason for hiding this comment

Uh oh!

Fraser999 Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Fraser999 Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Fraser999 Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Fraser999 Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Fraser999 Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Fraser999 Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

prestwich commented Mar 24, 2026 •

edited

Loading