[SunSi12138]

feat(server): pre-call connection admission bounds (issue #162)

Summary

Bounds the framework-owned connection resources that exist before RPC call admission:
every server now has a hard limit on simultaneously live accepted connections and an
independent hard limit on connections still inside TLS / Protocol v2 / authentication
handshake. Over-limit connections are rejected (closed) immediately — they never enter the
handshake/session lifecycle and never spawn a framework task.

Evidence (Phase 0, baremetal 8 pinned cores @ fd236a5)

With no bound, the framework-owned live set grows exactly with arrival rate:

scenario	N	socket-fd delta	alloc delta	VmRSS delta	Stop time
tcp-stall-nobytes	100 / 1000 / 5000	200 / 2000 / 10000	6.4 / 59.4 / 298 MB	10 / 48 / 203 MB	39 / 54 / 213 ms
tls-ready-stall-protocol	100 / 1000 / 2000	200 / 2000 / 4000	5.6 / 79.6 / 166 MB	—	12 / 53 / 86 ms

• Pre-auth connections are invisible to the existing sharplink.connections.active
  gauge (Ready-only, 0 observed in every stall scenario).
• TLS handshake burst: 256 concurrent handshakes ≈ 388 ms CPU on 8 cores
  (~1.5 ms CPU per handshake, wall ≈ 117 ms) — an unbound burst can saturate cores.
• Conclusion: Go — single connection bound would conflate two different resource
  shapes (an idle Ready connection is orders of magnitude cheaper than a TLS handshake),
  so both bounds are exposed; handshakes are additionally always capped by the
  connection bound.

Design

• Connection slot: acquired synchronously in the accept loop right after
  AcceptAsync; released exactly once at terminal cleanup. A rejected connection is
  disposed inline and the loop continues — no task, no lifecycle entry.
• Handshake slot: covers TLS AuthenticateAsync + Protocol v2 handshake +
  application authenticator; released exactly once at the Ready transition (or by the
  terminal cleanup for every pre-Ready failure: TLS throw/timeout, protocol reject,
  auth reject/cancel, Stop, duplicate/replaced connection id).
• Exactly-once ownership: one lease per admitted connection with idempotent
  releases; the single release owner is the terminal cleanup plus the Ready transition
  for the handshake slot. No manual Interlocked.Decrement scattered across catch blocks.
• No waiting: over-limit connections are rejected immediately. Pre-Ready connections
  carry no user state worth queueing; waiting would turn "handshaking" into "parked and
  still consuming a socket + task", exactly the unbounded growth this issue removes.
• Not on the request hot path: admission lives only on the accept/handshake path;
  RPC dispatch never touches the gate.
• Stop/drain: slots release through the existing framework-task drain; Stop and
  Accept races cannot leak a slot (task terminal cleanup always runs).

API (server-specific, mirrors UseAdmissionControl)

builder.UseConnectionAdmission(options =>
{
    options.MaxConcurrentConnections = 10_000;  // default 1024
    options.MaxConcurrentHandshakes = 256;      // default 0 = follows connection bound
});

• MaxConcurrentHandshakes 0 (default) means no independent handshake bound;
  a positive value must not exceed MaxConcurrentConnections.
• Distinct from MaxConcurrentCallsPerConnection/PerServer (post-handshake RPC
  dispatch) — documented on the options class.

Diagnostics

• sharplink.connections.admitted / sharplink.connections.handshakes.active (UpDown)
• sharplink.connections.rejected with sharplink.admission.reason =
  connection_limit | handshake_limit
• 5 s-throttled warning log (1105) and startup capacity log (5004).

Tests

21 deterministic tests in ConnectionAdmissionTests:
options validation, gate unit tests (readmit after release, idempotent release),
scripted-listener lifecycle coverage (immediate reject + dispose-exactly-once, TLS
throw, protocol reject + peer error frame, auth reject, Ready handshake-slot release,
handshake bound, Stop races, 2000-connection churn to zero, duplicate connection id,
handshake timeout), rejection telemetry, real-TCP connection bound and TLS handshake
bound behavior. Full unit suite 982/982.

Validation gates

• Overload: live accepted connections ≤ configured bound; rejected connections leave
  no retained framework task (head evidence matrix on baremetal, default limits).
• Healthy path: unary load base-vs-head comparison (no hot-path change by construction).
• quick CI + integration/chaos suites on this PR.

[SunSi12138]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 26de539bbd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[SunSi12138]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Can't wait for the next one!

Reviewed commit: c6d3fba435

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".