feat(network): lean base pools (#2641)

**Follow-on to #2639 (merged). References a local IORingGroup `1.0.13-preview.11` pack until 1.0.13 (modernuo/IORingGroup#15) is published; do not merge before that switch.**

## Summary

Consumes IORingGroup's lean base pools (modernuo/IORingGroup#15): both network pools now start with one slab, grow a slab at a time with the population, and trim idle slabs back after quiet periods.

- Fixes the transport's send-pool cap: previously only 1024 of the 4096 connections could get a send buffer; connection 1025 was closed at accept.
- Network memory at boot drops from about 96 MB to about 10 MB at the defaults; a full 4096 logged-in connections is about 1.25 GB of base buffers plus the growth budget.
- New settings: `network.initialBufferSlabs` (default 1; slabs of each pool held from boot and the trim floor) and `network.maxBufferSlabs` (default 128; divides the connection maximum into slabs, 32 connections per slab). Both are coerced with a warning; the same value feeds the ring table and the manager so they cannot drift.
- The Debug-only maintenance line includes base-pool capacity and releases.
- `dev-docs/server-requirements.md` rewrites the network memory story and adds the two settings.

## Pre-auth buffers

Every connection starts on the transport's platform-minimum buffers (4 KB receive, 4 KB send) instead of the base pools. It is promoted to full-size buffers (64 KB receive, `network.sendBufferSize` send) when the game server verifies its account — the point where `NetState.Account` is assigned in the `GameServer_AwaitingGameServerLogin` or `GameServer_LoggedIn` state, so a verdict that lands after the parser has moved on still promotes. Nothing ever moves back. The login-server pass stays on the small buffers for its whole lifetime.

Before credentials verify, nothing promotes: the 4 KB send ring is the entire pre-auth send budget, and a connection that overruns it is dropped as exhausted, exactly as the receive side drops a packet header declaring more bytes than the receive buffer can hold (new guard in `HandlePacket`; it also closes the old 65535-byte edge on 64 KB buffers). The stock login sequence sends under 2 KB. After credentials verify, the send path promotes on demand if it ever needs to (unbudgeted, outside the memory ceiling and the shrink bookkeeping — promotion is not growth), and the oversize-packet guard waits on a pending receive promotion or retries a stalled one once for a verified account before disconnecting. A completion that fills the receive buffer arms no receive, so `HandleReceive` now calls `RingSocket.ResumeReceive()` after the parse loop — at 4 KB a burst of small packets fills the buffer in one completion.

Net effect: a flood of unauthenticated connections tops out at about 32 MB across the full 4096-connection cap where the platform minimum is 4 KB (the transport's retained slabs and the base pools used by logged-in players are separate), and never allocates a base-pool slab.

Platform note: on Windows Server 2012 R2 / 2016 the transport's legacy mapping path floors at 64 KB: the pre-auth receive pool is off there (its base is 64 KB), while the pre-auth send buffer starts at 64 KB under the 256 KB base. The server logs the effective sizes at startup.

## Testing

Server.Tests (905) and UOContent.Tests green on the preview pack (one pre-existing `FamiliarAITests` failure from #2644 reproduces on `main`, tracked separately). New tests cover both coercions, that the ring's registration table equals `RequiredRegisteredBuffers` for the configured values, promotion on game-server auth and on a late account, no promotion on the login server, pre-credential overrun ending in exhaustion, post-credential on-demand promotion, the oversize-packet guard through loopback (error, wait, retry with an account, and a promotion made pending mid-parse), and receiving again after a burst fills the initial buffer.

Projects/Server/Network/NetState/NetState.Network.cs

@@ -29,18 +29,26 @@ namespace Server.Network;
 public partial class NetState
 {
     // Buffer sizes
-    private const int RecvBufferSize = 1024 * 64;    // 64KB recv buffers
+    internal const int RecvBufferSize = 1024 * 64;    // 64KB recv buffers
     private const int DefaultSendBufferSize = 1024 * 256;  // 256KB send buffers
     private const int MinSendBufferSize = 1024 * 64;       // Platform allocation granularity
     private const int DefaultMaxSendBufferSize = 1024 * 1024 * 2;          // 2 MB
     private const long DefaultSendBufferGrowthBudget = 1024L * 1024 * 256; // 256 MB
     private const int DefaultMemoryCeilingPercent = 80;
+    private const int DefaultInitialBufferSlabs = 1;   // one slab of each base pool warm at boot
+    internal const int DefaultMaxBufferSlabs = 128;    // 32 connections per slab at MaxConnections
 
     // Transport ceiling; larger values overflow its tier enumeration
     private const int TransportMaxSendBufferSize = 1024 * 1024 * 256; // 256 MB
     private const int MaxConnections = 4096;         // Max concurrent connections
 
+    internal static int SendBufferSize { get; private set; }
     internal static int MaxSendBufferSize { get; private set; }
+
+    // Pre-auth buffers are the smallest the platform can map; a platform whose floor is not below
+    // the base size (the Windows legacy mapping path) starts sockets on base
+    internal static int InitialRecvBufferSize { get; private set; }
+    internal static int InitialSendBufferSize { get; private set; }
     private static long _sendBufferGrowthBudget;
     private static int _memoryCeilingPercent;
 
@@ -51,6 +59,7 @@ public partial class NetState
     private static long _lastTierCapacityBytes;
     private static int _lastTierInUse;
     private static int _lastTierRetainFloor;
+    private static long _lastBaseCapacityBytes;
 
     private static readonly Queue<NetState> _disposed = [];
     private static readonly TimeSpan ConnectingSocketIdleLimit = TimeSpan.FromMilliseconds(5000); // 5 seconds
@@ -141,23 +150,46 @@ public partial class NetState
 
         // Per-connection send buffer: the lever for "send buffer exhausted" disconnects, and the
         // per-connection memory ceiling.
-        var sendBufferSize = GetSendBufferSize();
-        MaxSendBufferSize = GetPowerOfTwoSetting("network.sendBufferMaxSize", DefaultMaxSendBufferSize, sendBufferSize);
+        SendBufferSize = GetSendBufferSize();
+        MaxSendBufferSize = GetPowerOfTwoSetting("network.sendBufferMaxSize", DefaultMaxSendBufferSize, SendBufferSize);
         _sendBufferGrowthBudget = CoerceSendBufferGrowthBudget(
             ServerConfiguration.GetOrUpdateSetting("network.sendBufferGrowthBudget", DefaultSendBufferGrowthBudget),
-            sendBufferSize,
+            SendBufferSize,
             MaxSendBufferSize
         );
         // 0 disables the ceiling
         _memoryCeilingPercent = Math.Clamp(ServerConfiguration.GetOrUpdateSetting("network.memoryCeilingPercent", DefaultMemoryCeilingPercent), 0, 100);
         _availableMemoryBytes = GC.GetGCMemoryInfo().TotalAvailableMemoryBytes;
 
-        const int maxBufferSlabs = 32;
+        // Divides MaxConnections into base-pool slabs; both pools still reach MaxConnections, so
+        // this sets slab granularity, not a connection or memory ceiling.
+        var maxBufferSlabs = CoerceMaxBufferSlabs(
+            ServerConfiguration.GetOrUpdateSetting("network.maxBufferSlabs", DefaultMaxBufferSlabs)
+        );
+
+        // Slabs of each base pool held from boot; the pools grow and trim from here
+        var initialBufferSlabs = CoerceInitialBufferSlabs(
+            ServerConfiguration.GetOrUpdateSetting("network.initialBufferSlabs", DefaultInitialBufferSlabs),
+            BasePoolSlabCount(maxBufferSlabs)
+        );
+
+        // Until the game server verifies credentials a connection holds the smallest buffers the
+        // platform can map; a flood can fill these pools but never reaches the base pools. This is a
+        // request: the manager raises it to the platform floor and turns the pool off if that leaves
+        // no room below the base size (the Windows legacy mapping path floors at 64 KiB, which can
+        // equal RecvBufferSize). The effective sizes are read back below once the manager knows them.
+        var initialBufferSize = IORingBuffer.MinimumSize;
+
+        // Both calls take the same slab count; the manager throws if the table is smaller. Sized by
+        // the request, not the effective size the manager may coerce down to - conservative, never small.
         var ring = IORingGroup.Create(
             queueSize: MaxConnections * 2,
             maxConnections: MaxConnections,
             maxOutstandingSends: maxOutstandingSends,
-            maxRegisteredBuffers: RingSocketManager.RequiredRegisteredBuffers(MaxConnections, sendBufferSize, MaxSendBufferSize, _sendBufferGrowthBudget, maxBufferSlabs)
+            maxRegisteredBuffers: RingSocketManager.RequiredRegisteredBuffers(
+                MaxConnections, SendBufferSize, MaxSendBufferSize, _sendBufferGrowthBudget, maxBufferSlabs,
+                initialBufferSize, initialBufferSize
+            )
         );
 
         // Create socket manager which handles buffer pools and socket lifecycle
@@ -165,13 +197,28 @@ public partial class NetState
             ring,
             maxSockets: MaxConnections,
             recvBufferSize: RecvBufferSize,
-            sendBufferSize: sendBufferSize,
-            initialBufferSlabs: 8,
+            sendBufferSize: SendBufferSize,
+            initialBufferSlabs: initialBufferSlabs,
             maxBufferSlabs: maxBufferSlabs,
             maxSendBufferSize: MaxSendBufferSize,
-            sendBufferGrowthBudget: _sendBufferGrowthBudget
+            sendBufferGrowthBudget: _sendBufferGrowthBudget,
+            initialRecvBufferSize: initialBufferSize,
+            initialSendBufferSize: initialBufferSize
         );
 
+        InitialRecvBufferSize = _socketManager.InitialRecvBufferSize;
+        InitialSendBufferSize = _socketManager.InitialSendBufferSize;
+
+        if (InitialRecvBufferSize == 0 || InitialSendBufferSize == 0)
+        {
+            logger.Information(
+                "Pre-auth buffers off where the platform floor ({Minimum} bytes) leaves no room below the base size (recv {Recv}, send {Send})",
+                IORingBuffer.MinimumSize,
+                RecvBufferSize,
+                SendBufferSize
+            );
+        }
+
         _maintenanceTimer = Timer.DelayCall(TimeSpan.FromMinutes(1), TimeSpan.FromMinutes(1), MaintainSendBuffers);
     }
 
@@ -193,27 +240,79 @@ public partial class NetState
         var stats = _socketManager.Maintain();
         var changed = stats.TierCapacityBytes != _lastTierCapacityBytes ||
                       stats.TierInUse != _lastTierInUse ||
-                      stats.TierRetainFloor != _lastTierRetainFloor;
+                      stats.TierRetainFloor != _lastTierRetainFloor ||
+                      stats.BaseCapacityBytes != _lastBaseCapacityBytes;
         _lastTierCapacityBytes = stats.TierCapacityBytes;
         _lastTierInUse = stats.TierInUse;
         _lastTierRetainFloor = stats.TierRetainFloor;
+        _lastBaseCapacityBytes = stats.BaseCapacityBytes;
 
         // Quiet unless something moved
-        if (changed || stats.BuffersReleased > 0 || stats.GrowthRefusals > 0 || capRefusals > 0 || ceilingRefusals > 0)
+        if (changed || stats.BuffersReleased > 0 || stats.BaseBuffersReleased > 0 || stats.GrowthRefusals > 0 ||
+            capRefusals > 0 || ceilingRefusals > 0)
         {
             logger.Debug(
-                "Send buffer tiers: {Capacity} bytes of tier capacity, {InUse} buffers in use, floor {Floor} buffers, released {Released}, refused: budget {BudgetRefusals}, at max {CapRefusals}, ceiling {CeilingRefusals}",
+                "Send buffer tiers: {Capacity} bytes of tier capacity, {InUse} buffers in use, floor {Floor} buffers, released {Released}, refused: budget {BudgetRefusals}, at max {CapRefusals}, ceiling {CeilingRefusals}, base {BaseCapacity} bytes, released {BaseReleased}",
                 stats.TierCapacityBytes,
                 stats.TierInUse,
                 stats.TierRetainFloor,
                 stats.BuffersReleased,
                 stats.GrowthRefusals,
                 capRefusals,
-                ceilingRefusals
+                ceilingRefusals,
+                stats.BaseCapacityBytes,
+                stats.BaseBuffersReleased
             );
         }
     }
 
+    /// <summary>
+    /// Slabs each base pool is divided into, after the transport applies its minimum slab size.
+    /// </summary>
+    internal static int BasePoolSlabCount(int maxBufferSlabs) =>
+        RingSocketManager.BasePoolSlabCount(MaxConnections, maxBufferSlabs);
+
+    /// <summary>
+    /// Clamps the base-pool slab divisor. Fewer than one slab is meaningless, and more slabs than
+    /// connections cannot make a slab any smaller.
+    /// </summary>
+    internal static int CoerceMaxBufferSlabs(int configured)
+    {
+        var slabs = Math.Clamp(configured, 1, MaxConnections);
+
+        if (slabs != configured)
+        {
+            logger.Warning(
+                "network.maxBufferSlabs {Configured} is outside 1..{Maximum}; using {Adjusted}",
+                configured,
+                MaxConnections,
+                slabs
+            );
+        }
+
+        return slabs;
+    }
+
+    /// <summary>
+    /// Clamps the slabs of each base pool held from boot; a pool never holds more slabs than it has.
+    /// </summary>
+    internal static int CoerceInitialBufferSlabs(int configured, int slabCount)
+    {
+        var slabs = Math.Clamp(configured, 1, slabCount);
+
+        if (slabs != configured)
+        {
+            logger.Warning(
+                "network.initialBufferSlabs {Configured} is outside 1..{Maximum}; using {Adjusted}",
+                configured,
+                slabCount,
+                slabs
+            );
+        }
+
+        return slabs;
+    }
+
     /// <summary>
     /// Reads the configured send buffer size, coerced to a power of two of at least the platform
     /// allocation granularity. IORingBuffer requires this and would otherwise throw at socket

Projects/Server/Network/NetState/NetState.cs

@@ -227,7 +227,39 @@ public partial class NetState : IComparable<NetState>, IValueLinkListNode<NetSta
     public IAccount Account
     {
         get => _account;
-        set => _account = value;
+        set
+        {
+            _account = value;
+
+            // 0x91 credentials just verified: the character list and the world-entry burst follow.
+            // The login-server pass stays on the initial buffers; it never sends more than a server list.
+            // An off-loop password check can land its verdict after HandleReceive already flipped the
+            // state to LoggedIn, so both states promote; both calls below are no-ops once applied.
+            if (value != null && _protocolState is ProtocolState.GameServer_AwaitingGameServerLogin or ProtocolState.GameServer_LoggedIn)
+            {
+                PromoteBuffers();
+            }
+        }
+    }
+
+    private void PromoteBuffers()
+    {
+        if (_socket == null)
+        {
+            return;
+        }
+
+        if (!_socketManager.TryPromoteSendBuffer(_socket) && _socket.SendBuffer.PhysicalSize < SendBufferSize)
+        {
+            // The send path promotes on demand and disconnects if that fails too
+            logger.Debug("{NetState}: send buffer promotion deferred to the send path", this);
+        }
+
+        if (!_socketManager.TryPromoteRecvBuffer(_socket) && _socket.RecvBuffer.PhysicalSize < RecvBufferSize)
+        {
+            // The oversize-packet guard in HandlePacket gets one more try where the small buffer matters
+            logger.Debug("{NetState}: recv buffer promotion deferred", this);
+        }
     }
 
     public string Assistant { get; set; }
@@ -525,6 +557,19 @@ public partial class NetState : IComparable<NetState>, IValueLinkListNode<NetSta
             return false;
         }
 
+        if (_socket.SendBuffer.PhysicalSize < SendBufferSize)
+        {
+            // Promotion is unbudgeted and is not growth, so neither the ceiling nor the shrink
+            // bookkeeping applies. Before credentials verify nothing promotes: the 4 KiB ring is the
+            // whole pre-auth send budget, and a connection that exceeds it is dropped as exhausted.
+            if (_account == null)
+            {
+                return false;
+            }
+
+            return _socketManager.TryPromoteSendBuffer(_socket);
+        }
+
         if (!UnderMemoryCeiling())
         {
             _ceilingRefusals++;
@@ -1084,6 +1129,13 @@ public partial class NetState : IComparable<NetState>, IValueLinkListNode<NetSta
                     break;
                 }
             }
+
+            // A completion that fills the buffer arms no receive; whatever the loop consumed is free
+            // space again. No-op while a receive is armed or the buffer is still full.
+            if (_running)
+            {
+                _socket.ResumeReceive();
+            }
         }
         catch (Exception ex)
         {
@@ -1137,6 +1189,22 @@ public partial class NetState : IComparable<NetState>, IValueLinkListNode<NetSta
             }
         }
 
+        // Can never complete: the buffer holds PhysicalSize - 1 bytes (one slot tells full from
+        // empty) and a recv arms only into free space
+        if (packetLength >= _socket.RecvBuffer.PhysicalSize)
+        {
+            // A verified account whose promotion could not be applied earlier gets one more try here,
+            // where the small buffer actually matters; the swap lands before the next completion's event
+            if (_account != null && _socket.RecvBuffer.PhysicalSize < RecvBufferSize &&
+                _socketManager.TryPromoteRecvBuffer(_socket))
+            {
+                return ParserState.AwaitingPartialPacket;
+            }
+
+            LogInfo($"Received packet 0x{packetId:X2} declaring {packetLength} bytes, more than the receive buffer holds.");
+            return ParserState.Error;
+        }
+
         // Not enough data, let's wait for more to come in
         if (length < packetLength)
         {

Projects/Server/Server.csproj

@@ -34,7 +34,7 @@
     </Target>
     <ItemGroup>
         <ProjectReference Include="..\Logger\Logger.csproj" />
-        <PackageReference Include="IORingGroup" Version="1.0.12" />
+        <PackageReference Include="IORingGroup" Version="1.0.13" />
         <PackageReference Include="CommunityToolkit.HighPerformance" Version="8.4.2" />
         <PackageReference Include="LibDeflate.Bindings" Version="1.0.4" />
         <PackageReference Include="System.IO.Hashing" Version="10.0.12" />