refactor: Introduce explicit TransmitBuf::first_datagram

[flub]

Description

Having to initialise an TransmitBuf with the MTU makes no sense in the multipath world. Because the MTU may change depending on which path the buffer is populated for.

By passing in the MTU when creating the first datagram, this becomes a lot clearer. Additionally it makes starting datagrams for MTU probes or off-path packets more straightforward.

Finally it makes it obvious where the MTU size otherwise sneaks into.

Breaking Changes

n/a

Notes & open questions

poll_transmit is an endless source of possible refactorings. This only targets one specific aspect.

[github-actions]

Documentation for this PR has been generated and is available at: https://n0-computer.github.io/quinn/pr/352/docs/iroh_quinn/

Last updated: 2026-01-21T11:05:02Z

[codecov-commenter]

Codecov Report

❌ Patch coverage is 87.75510% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.48%. Comparing base (3c9d82c) to head (3bddeda).

Files with missing lines	Patch %	Lines
quinn-proto/src/connection/packet_builder.rs	16.66%	5 Missing ⚠️
quinn-proto/src/connection/transmit_buf.rs	90.19%	5 Missing ⚠️
quinn-proto/src/connection/mod.rs	94.87%	2 Missing ⚠️

Additional details and impacted files

@@                   Coverage Diff                    @@
##           flub/poll-transmit-ohno     #352   +/-   ##
========================================================
  Coverage                    76.47%   76.48%           
========================================================
  Files                           81       81           
  Lines                        22909    22926   +17     
========================================================
+ Hits                         17520    17535   +15     
- Misses                        5389     5391    +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

Performance Comparison Report

6798a525f98602c2eeac86c5ca7d15220dcef48d - artifacts

Raw Benchmarks (localhost)

Scenario	iroh-quinn	upstream	Delta	CPU (avg/max)
large-single	N/A	7508.4 Mbps	N/A	N/A
medium-concurrent	N/A	7061.6 Mbps	N/A	N/A
medium-single	N/A	3967.9 Mbps	N/A	N/A
small-concurrent	N/A	4968.7 Mbps	N/A	N/A
small-single	N/A	4201.5 Mbps	N/A	N/A

Netsim Benchmarks (network simulation)

Condition	iroh-quinn	upstream	Delta
ideal	828.1 Mbps	3577.4 Mbps	-76.9%
lan	592.1 Mbps	796.4 Mbps	-25.7%
lossy	55.9 Mbps	69.8 Mbps	-20.0%
wan	83.8 Mbps	83.8 Mbps	~0%

Summary

iroh-quinn is 65.5% slower on average

---

3bddedaca9a582d7ea047f4ec7ac4f51384973e1 - artifacts

Raw Benchmarks (localhost)

Scenario	iroh-quinn	upstream	Delta	CPU (avg/max)
large-single	5408.5 Mbps	7931.3 Mbps	-31.8%	93.7% / 98.2%
medium-concurrent	5396.9 Mbps	7103.9 Mbps	-24.0%	93.6% / 99.3%
medium-single	3795.3 Mbps	3941.4 Mbps	-3.7%	85.5% / 95.4%
small-concurrent	3739.1 Mbps	5038.6 Mbps	-25.8%	98.7% / 127.0%
small-single	3349.3 Mbps	4349.2 Mbps	-23.0%	86.8% / 96.1%

Netsim Benchmarks (network simulation)

Condition	iroh-quinn	upstream	Delta
ideal	2845.1 Mbps	3827.7 Mbps	-25.7%
lan	768.5 Mbps	796.5 Mbps	-3.5%
lossy	69.8 Mbps	55.9 Mbps	+25.0%
wan	83.8 Mbps	83.8 Mbps	~0%

Summary

iroh-quinn is 23.2% slower on average

[matheus23]

Having to initialise an TransmitBuf with the MTU makes no sense in the multipath world. Because the MTU may change depending on which path the buffer is populated for.

By passing in the MTU when creating the first datagram, this becomes a lot clearer. Additionally it makes starting datagrams for MTU probes or off-path packets more straightforward.

Sorry for the drive-by, but reading this, I can't help myself but think that the TransmitBuf should perhaps be initialized after the path_id it is for is known.

[divagant-martian]

I think this is no longer needed, should this be closed?

[flub]

You don't like this API? I think it is still nice:

• start_new_datagram_with_size is a pretty mean hack that's easy to hold wrong.
• splitting the API against 1st datagram and next datagrams significantly reduced the risk of writing the loss probes wrongly. The way that code changed also reenforced that this was a good change to me.

Of course the code needs a serious clean up, because of the other changes the diff is pretty useless right now.

There are many more improvements to TransmitBuf to make. None of them that urgent but still nice to have. E.g. I'd like to try add back an explicit DatagramBuffer that forbids writing more data into the datagram then allowed. If that works I'd like to try out if it would be possible to automatically "close" the first datagram by dropping that thing or something. Or figure out something to no longer need this manual "clip first datagram/set segment size" call.