RFC: server internals as acceptor + driver + loop (opt-in restructure; follows #306–#308, #304)

[rpb-ant]

This retitles #305. It is not required for any of the API in A–D (#306 ConnectionInfo + Server::serve_connection, #307 ConnectionConfig, #308 free serve_connection + axum::serve, #304 with_connection_extensions) — those four land the whole adopter-facing surface on today's server.rs / axum.rs, each under the 250-line rule by net non-test lines (B's gross churn is ~2k because setter docs move; it is mechanical), with no file moves. What is left in this branch is internal structure, offered because it addresses #250 (items 2–3 and the Notes line) and #253 (the server.rs row) directly. If you want it, I will rebase it onto D and send it as 3–4 mostly-move PRs; if not, nothing in A–D depends on it and it can be closed.

The branch as pushed (rpb/server-layers, 10 commits on main) predates A–D and still carries the earlier, larger public surface (public Acceptor family, Server::service, accept_config accessors). Read it for shape, not for API: rebased, every one of those becomes pub(crate) and the public items are exactly A–D's.

What A–D already bank (so this RFC does not claim them)

• One connection driver behind Server, BoundServer, axum::serve, axum::serve_tls and custom loops (C), returning ConnectionClosed (A).
• One crate-private accept loop shared by all four entry points (C) — serve_tls can no longer silently lack a setting.
• One ConnectionConfig value instead of nine fields × two builders × four default blocks × positional plumbing (B): a new knob is field + default + setter + accessor + apply = 5 hunks, versus the measured 11 (HTTP/2 knob) to 22 (positional knob; the fourth default block really does fail cargo check) on 0.9.0, and it cannot skip axum.rs as 4 of the last 5 knob PRs did.

What the restructure adds, measured on the branch against main @ 758bd3a

	main	branch
server.rs	4 330 lines (2 132 non-test) in one file	server/{mod 134, config 838, peer 259, acceptor 369, connection 621, accept_loop 125, standalone 784}.rs; largest non-test file 707
accept loops / TLS handshake blocks	2 / 2	1 / 1 (accept_loop::run, 72 lines; Accepted::handshake, 28) — already 1 / 1 after C; what the branch adds is the loop and the accept+handshake step as their own small units (accept_loop.rs, acceptor.rs) instead of one 130-line function
longest function	serve_with_listener 174, ConnectionLifecycle::poll 115	serve_connection 126, accept_loop::run 72
connection lifecycle	hand-rolled Future: struct + IdleTracker + 3-state enum + poll with 10 poll sites, 210 lines	two biased select! phases + retirement() + quiet_for, 99 lines (last commit, −177/+90, independently droppable)
#[allow(clippy::too_many_arguments)] / cfg-dependent arity	2 / yes	0 / no
tests	one 2 198-line mod tests (59 tests), 0 in-memory, 41 sockets	server/tests/{acceptor,builders,connection,header_read_timeout,http2,max_connection_age,max_connection_idle,max_requests,peer,shutdown}.rs by topic (#253's own axes) + unit tests beside the code; a direct driver suite of 8 tests over tokio::io::duplex (max-age / idle / request-count retirement, drain, panic isolation, extension stamping) with no listener
functional diff (driver + loop + axum as one change)	—	net −405 non-test lines, because the second loop and handshake die; commits 1–2 are a 100 % rename and a pure test move (+23 net)

Costs, also measured: 9 pub(crate) seams between files that were one; cfg(feature = "server-tls") sites 37 → 41 spread over 5 files instead of 2; the layer table has to be kept true in module docs, crate docs and the guide; +4 CI steps (already in C).

Proposed shape if accepted (rebased onto D)

1. moves — server.rs → server/mod.rs; test module → server/tests/*.rs by topic. Pure moves, reviewable with --color-moved; closes Test modules run several times the size CONTRIBUTING allows, with the harness copied per test #253's server.rs row on its own.
2. acceptor + loop — crate-private Acceptor / Accepted::handshake (TCP accept, nodelay, transient-error retry with a 1 s back-off on EMFILE/ENFILE, TLS handshake + timeout + cert capture in one place) and accept_loop::run in their own files; standalone.rs becomes the two builders + run. No public items.
3. async lifecycle — the poll state machine as an async body. Droppable.
4. example + docs — examples/custom-accept-loop (admission and runtime placement by client-certificate identity over the public serve_connection, handshake inline as in C's guide section, with an e2e test) and the module-doc layer table.

Keeping Acceptor / Accepted / ServerIo / HandshakeError / AcceptConfig crate-private until someone asks is deliberate: promoting them later is ~24 visibility tokens and re-exports; retracting them would be a breaking release, and #250's self-taking transition may want to reshape AcceptConfig first.

Evidence from the branch as it stands: per-commit fmt / clippy (all feature shapes) / rustdoc / MSRV green; 697 lib tests; conformance server mode 3600/3600 (all protocols) and 2396/2396 (Connect + TLS); cargo semver-checks vs v0.9.0 clean three ways; echo_bench --quick within noise of main.

🤖 Generated with Claude Code

[rpb-ant]

Closing: the parts of this with adopter demand landed as #306, #307, #308 and #304 (one ConnectionConfig, ConnectionInfo, a public service-generic serve_connection, and Server/BoundServer/axum::serve sharing one accept loop and driver).

What remains of the layering proposal is internal and behaviour-neutral: splitting server.rs into server/{config,peer,connection,accept_loop,…}.rs (the #253 row), splitting the test module by topic with a socket-free driver suite, extracting the two inline TLS-handshake blocks into a crate-private acceptor, and expressing the connection lifecycle as an async body instead of the hand-rolled poll state machine. The branch here predates #306–#308 and their follow-up fixes, so it would be re-cut from main as move-only commits rather than rebased. Happy to do that whenever #253/#250 want it; leaving it as an offer rather than an open diff.