switchrpc: improve TrackOnion error handling

[calvinrzachman]

Change Description

Following up on some review comments from #9489, we explore an update to the communication of error information via TrackOnionResponse.

• Enforce at compile time that either a pre-image or an attempt error will be set in the TrackOnionResponse through a top-level oneof.
• Avoid proprietary string-based encoding of hop index and wire message for ForwardingError, instead opting for structured protobuf messages (FailureDetails) to transport rich error details without loss of information.
• Provide type-safe mechanisms (oneof failure) within FailureDetails to carry specific failure types: ForwardingFailure, ClearTextFailure, or raw encrypted_error_data bytes.
• Communicate failures of the TrackOnion query itself (e.g., attempt not found, server unavailable) via standard gRPC status codes (codes.NotFound, codes.Unavailable), cleanly separating them from application-level payment outcomes in the response body.

NOTE: This is a breaking change for clients. Though given that this RPC is not included in any release, this seems perfectly fine. A follow-up PR is planned for SendOnion.

Steps to Test

• make itest icase=track_onion
• go test -v -timeout 30s -tags switchrpc -run ^TestTrackOnion$ github.com/lightningnetwork/lnd/lnrpc/switchrpc
• go test -v -timeout 30s -tags switchrpc github.com/lightningnetwork/lnd/lnrpc/switchrpc

[gemini-code-assist]

Summary of Changes

Hello @calvinrzachman, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly refactors the error handling mechanism for the TrackOnion RPC. The primary goal is to move from a less structured, string-based error reporting to a more robust, type-safe, and explicit protobuf-driven approach. This enhancement ensures that clients receive clearer, more detailed, and programmatically accessible information about payment outcomes, whether successful or failed, while also aligning RPC-level errors with standard gRPC status codes.

Highlights

• Structured Error Handling: The TrackOnionResponse now uses a oneof field to ensure that either a preimage (for success) or detailed FailureDetails (for failure) is set, enforcing mutual exclusivity at compile time.
• Rich Failure Details: Proprietary string-based encoding for ForwardingError has been replaced with structured protobuf messages (FailureDetails), allowing for the transport of rich error details without loss of information.
• Type-Safe Failure Types: The new FailureDetails message includes a oneof field to carry specific failure types: ForwardingFailure, ClearTextFailure, or raw encrypted_error_data bytes, providing type-safe mechanisms for error reporting.
• Standard gRPC Status Codes: Failures related to the TrackOnion query itself (e.g., attempt not found, server unavailable) are now communicated via standard gRPC status codes (codes.NotFound, codes.Unavailable), cleanly separating them from application-level payment outcomes in the response body.
• Breaking Change Acknowledged: This change is acknowledged as a breaking change for clients, but it is deemed acceptable as the TrackOnion RPC is not yet included in any released version.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request significantly improves error handling for the TrackOnion RPC by introducing structured error messages using protobuf's oneof feature. This is a great improvement over the previous string-based error reporting, making the API more robust and easier for clients to consume. The changes correctly separate RPC-level errors (communicated via gRPC status codes) from application-level payment failures. The implementation is solid, but I found one issue where the ErrorCode field is not being set for certain failure types, which I've commented on. Overall, this is a high-quality change that enhances the switchrpc API.

[calvinrzachman]

This leads to a code structure in the RPC client code like:

	switch result := trackResp.Result.(type) {
	case *switchrpc.TrackOnionResponse_Preimage:
		preimage, err := lntypes.MakePreimage(result.Preimage)
		if err != nil {
			// This is a data corruption error from the server. It
			// is NOT a definitive payment failure.

		}

		// Do something with pre-image...

	case *switchrpc.TrackOnionResponse_FailureDetails:
		details := result.FailureDetails
		translatedErr, err := switchrpc.UnmarshallFailureDetails(
			details, deobfuscator,
		)

		// Do something to handle attempt result (either settle/fail or retry if uncertain)

[bitromortac]

The code repetition here and in translageErrorForRPC isn't ideal, but I like the clarity of using one_of. Mabye we could do a similar approach in the SendOnion error to also add a ClearTextFailure.

[calvinrzachman]

Yep, for sure. I have a similar PR incoming which updates the way SendOnion rpc communicates error information. It will remove translateErrorForRPC. Just wanted to keep the PRs as small as possible to facilitate review.

[calvinrzachman]

One thing to consider is that SendOnion semantics differ a bit from TrackOnion. For TrackOnion, the gRPC request can itself be successful, but deliver information to the client about the failure of the given attempt ID being queried. For such failures, it makes sense to transport those via the RPC proto response message.

The SendOnion PR will likely move away from transporting error information via the proto response message. Instead we can reserve gRPC status status.OK for successful dispatches only and then transport structured error information via Details as mentioned in these docs:

• https://grpc.io/docs/guides/error/
• https://pkg.go.dev/google.golang.org/grpc/internal/status

I think this has added benefit to observability in that we'll be able to track gRPC failures/non-OK status for SendOnion endpoint more clearly to see if the remote router is having issues communicating with Switch RPC servers.