Stabilize tcp_deferaccept

[JohnTitor]

Close #119639
FCP: #119639 (comment)

[rustbot]

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: @ChrisDenton, libs
• @ChrisDenton, libs expanded to 8 candidates
• Random selection from Mark-Simulacrum, jhpratt

[asquared31415]

I think that the doc comments need editing for grammar and also to allow for cases where the Duration is used in a different way.

Additionally, the API requires passing a Duration, but the documentation says

Takes an integer value (seconds), this can bound the maximum number of attempts TCP will make to complete the connection.

In practice I believe that the special value 0 is equivalent to disabling the option and the duration is translated to a number of "retransmits" (capped at 255) so it may not be reliable. I don't believe that the current API is suitable, or if it is, it needs very heavy warnings.

[JohnTitor]

It's intentionally Duration, see #119639 (comment) and #140482

[asquared31415]

Another problem: the number of seconds passed also isn't a maximum either, it's a hint.

For example, if you pass 8 seconds to this API, that will get calculated as 4 retransmits, which will wait up to 15 seconds worth of retransmits. (as of linux kernel tag v6.18 (2025-11-30) which is what I have easily available at the moment)

This means that the duration can be significantly higher than the passed duration (up to 120 seconds longer in the most extreme cases I believe) or significantly lower (the duration is capped at 255 retransmits, which is about 29880 seconds or so if i'm doing the math correctly)

[Mark-Simulacrum]

View changes since the review

Suggested change

	/// Configures `TCP_DEFER_ACCEPT` on the socket.
	///
	/// This defers `accept()` yielding an incoming TcpStream that has not received any data yet by
	/// `accept` Duration.
	///
	/// Contrary to other platforms `SO_ACCEPTFILTER` feature equivalent, there is
	/// no necessity to set it after the `listen` call.
	///
	/// Note that the delay is expressed as a `Duration`, but the underlying syscall requires
	/// seconds. Currently we round down to the nearest second expressible as a `c_int`. This may
	/// change in the future if the underlying API becomes more expressive.

Proposal for updating the wording a bit to avoid some of the grammar issues (may need editing locally to adjust indentation etc).

[Mark-Simulacrum]

I'll also nominate just to do a last check with libs-api on the comments from @asquared31415 above and some more thoughts as I look at this.

• I think it might be worth noting Duration::ZERO as a special sentinel to disable this option (and make fn deferaccept -> Result<Option<Duration>> likewise).
• I also find it a little odd that we name the method deferaccept rather than defer_accept, given that it's TCP_DEFER_ACCEPT in libc.

[the8472]

We discussed this during today's libs-api meeting. We want the defer_accept name, with underscore.

Another problem: the number of seconds passed also isn't a maximum either, it's a hint.

We'd like to see this addressed too - it was in fact news to us since it's not mentioned on the manpage. Since the logic first rounds down and then up again and since this is a performance optimization and not some hard timing guarantee we didn't think it'd be worthwhile to spend too wording on the exact details and instead we could say something like these times are approximate and subject to both rounding by the standard library and the kernel.

---

I think it might be worth noting Duration::ZERO as a special sentinel to disable this option

We didn't discuss this during the meeting, but it seems reasonable to me .

[the8472]

@asquared31415 I interpret this sentence on the manpage

Takes an integer value (seconds), this can
bound the maximum number of attempts TCP will make to
complete the connection.

as saying that this also caps the maximum number of retransmits. Does that mean that low values may make handshakes less reliable than the default system configuration?

[asquared31415]

Correct, it bounds the maximum number of retransmits using an undocumented formula based on the input integer.

I think that having this value set may cause the handshake to be "less reliable" in that under extreme conditions when many retransmits are needed, the connection may be dropped instead (if the maximum is reached). But that's the explicit tradeoff you opt in to when you use this option.