Async handling of Onion Messages with BackpressureQueue

[gijswijs]

This pull request refactors the onion message handling to be asynchronous, addressing potential performance bottlenecks in the synchronous design from #10089.

Before this PR: ChannelMailbox (bounded Go channel)

Each onion peer actor was created with the default ChannelMailbox — a simple buffered Go channel. Looking at actor.go:82-86, when no MailboxSize was configured, it defaulted to 1:

mailboxCapacity := cfg.MailboxSize
if mailboxCapacity <= 0 {
    mailboxCapacity = 1
}

When a sender called Tell or Ask, the ChannelMailbox.Send() (mailbox.go:70-89) would do a select on:

1. m.ch <- env — try to enqueue
2. <-ctx.Done() — caller's context cancelled
3. <-m.actorCtx.Done() — actor shutting down

This is a blokcing risk. With a buffer of only 1, a second inbound onion message from the same peer would block the caller until the actor finished processing the first message. The caller here is peer/brontide.go — the peer's message reading goroutine. While blocked waiting to enqueue into the actor's mailbox:

• The peer's entire read loop would stall — no other wire messages (HTLCs, channel updates, pings, etc.) from that peer could be processed.
• If the onion message processing was slow (e.g., processOnionMessage involves sphinx decryption, node ID resolution, forwarding to another peer), the tiny buffer would fill immediately.

There was no message shedding — every message either got queued (eventually) or blocked. A malicious or chatty peer could effectively slow down their entire connection by flooding onion messages.

After this PR: BackpressureMailbox with RED

The PR replaces this with:

1. Larger buffer: DefaultOnionMailboxSize = 50 instead of 1
2. Random Early Detection (RED): Starting at depth 40 (DefaultMinREDThreshold), messages are probabilistically dropped. At depth 50 (full), all messages are dropped.
3. Per-peer customization: The OnionActorOpts callback allows different peers to get different drop policies in the future.

This means the peer's read loop will almost never block on onion message delivery — messages are either quickly enqueued (plenty of buffer) or dropped under load rather than causing backpressure into the connection handler.

[gemini-code-assist]

Summary of Changes

Hello @gijswijs, 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 enhances the Lightning Network node's capability to handle onion messages by introducing an asynchronous processing model. By integrating a BackpressureQueue with Random Early Drop, the system can now gracefully manage high volumes of onion messages, preventing performance degradation and ensuring the stability of peer communication. This makes the node a more robust and efficient router for onion message traffic, laying the groundwork for future privacy-preserving communication features.

Highlights

• Asynchronous Onion Message Handling: The core onion message processing has been refactored to operate asynchronously, utilizing a new BackpressureQueue to prevent synchronous processing from blocking critical peer communication. This ensures that incoming onion messages are enqueued and processed in a background goroutine, improving node stability and throughput.
• Introduction of BackpressureQueue: A new generic, bounded queue named BackpressureQueue has been implemented. This queue incorporates a 'Random Early Drop' (RED) predicate, which intelligently discards incoming messages as the queue approaches its capacity. This mechanism provides backpressure to the network under heavy load, preventing resource exhaustion without completely blocking new messages.
• Onion Message Protocol Support: New lnwire.OnionMessage types, corresponding feature bits (OnionMessagesOptional, OnionMessagesRequired), and RPC endpoints (SendOnionMessage, SubscribeOnionMessages) have been added. This enables nodes to advertise their capability to handle onion messages and provides an interface for sending and receiving them.
• Blinded Path Enhancements for Onion Messages: The htlcswitch/hop package has been updated to specifically handle onion messages within blinded paths. This includes adding a NextNodeID field to ForwardingInfo for routing messages that don't rely on channel IDs, and adapting payload parsing and validation logic to differentiate between regular payments and onion messages.
• Integration Tests for Onion Messages: New integration tests have been introduced to validate the functionality of onion messages, covering both basic sending/receiving between two nodes and multi-hop forwarding through a network of three nodes. These tests ensure the robustness and correctness of the new asynchronous handling and routing logic.

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 in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

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 issue 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 introduces a significant and well-designed refactoring to handle onion messages asynchronously. The introduction of a generic BackpressureQueue with Random Early Drop (RED) is a great approach to improve node stability and throughput under heavy message load. The code is well-structured, and the inclusion of new integration tests is commendable. My review focuses on a couple of minor areas for code cleanup and simplification to enhance maintainability.

[gijswijs]

Pushed a new version of this PR. It's based on the latest version of #10089. The BackpressureMailbox now uses queue.BackpressureQueue[envelope[M,R]] as its core buffer. It implements all Mailbox interface methods directly, using BackpressureQueue.Enqueue/TryEnqueue for sends, ReceiveChan() for the receive iterator, and Close() for lifecycle. The Send method merges the caller context with the actor context via context.AfterFunc so the blocking Enqueue respects both cancellation signals.

Would love to hear your thoughts @Roasbeef

[gijswijs]

Rebased the PR after the merge of #10089. Also updated the description to better explain what the BackpressureQueue is doing in the context of the onion message actor.

[Abdulkbk]

Did a first passand left some comments. Will test using Docker.

[bitromortac]

Really cool work 💯. Looks already quite good to me, which is why I also included some nits

[gijswijs]

I've addressed all comments by @Abdulkbk and @bitromortac. Quite a few were in relation to first commit (6b806f2) which was actually cherry picked from #9838, So we should carry those changes over to that PR, and rebase this one before merging. Or we might forego on that PR alltogether (since it's a single commit PR) and merge this one instead.

[bitromortac]

Thanks for the updates, it looks very close, but have some remarks.

I think we should also be more defensive in the Brontide's readHandler. We use Tell there which in principle could block (if there's a bug), but we pass in a ctx.TODO. So probably better to set a context with a timeout to prevent the handler from accidental blocking?

[Abdulkbk]

LGTM, pending my comment and bitromortac's.

[lightninglabs-deploy]

@Roasbeef: review reminder
@gijswijs, remember to re-request review from reviewers when ready

[erickcestari]

Nice work! I ran some load tests comparing the current master branch with this PR, and it significantly improves how the lnd node handles bursts of onion messages.

[Roasbeef]

LGTM 🫜

[erickcestari]

LGTM 🧅

[bitromortac]

LGTM 🎉