Hub event loop hits FD_SETSIZE=1024 Linux limit (select -> poll port)

[Aybook]

Problem

core/server.lua event loop calls luasocket.select which wraps the OS select() syscall via the bundled luasocket/src/select.c. On Linux, glibc's fd_set is hardcoded to 1024 bits in <sys/select.h> (__FD_SETSIZE). The hub silently caps at ~1000 concurrent connected sockets — connection #1024+ fails with EINVAL and the operator sees timeouts.

ulimit -n N does not help: it raises the per-process FD limit but the fd_set bitmask size is fixed at compile-time inside glibc.

Originally reported upstream as luadch/luadch#1 (2015, still open). Upstream maintainer's plan in 2020: "Eventually I will replace select by poll on unix". Never happened.

Why this isn't a one-line CMake bump

-DFD_SETSIZE=8192 only works on Windows. On Linux, glibc's fd_set typedef has a fixed buffer of 128 longs (1024 bits); calling FD_SET(2048, &set) writes past the struct. Buffer overflow, undefined behavior. The fd-bound guard in luasocket/src/select.c:140 is exactly to prevent that overflow.

Only path on Linux: replace select() with poll() (no bitmask, takes an struct pollfd[] array).

Code surface

File	Function	Role	LoC change
luasocket/src/select.c	global_select()	Lua-facing luasocket.select — main hub event loop	~80-100
luasocket/src/usocket.c	socket_waitfd()	Per-socket wait inside connect/send/receive. if (*ps >= FD_SETSIZE) return EINVAL → every operation on fd ≥ 1024 fails, not just the event loop	~25-30
luasocket/src/wsocket.c	socket_waitfd() + socket_select()	Windows variants, WSAPoll instead of poll	~50-60
luasocket/src/socket.h	prototypes	+5
luasocket/src/luasocket.c	register luasocket.poll	+5
core/server.lua	luasocket.select → luasocket.poll	+3
luasocket/CMakeLists.txt	-DLUASOCKET_USE_POLL build flag	+10
tests/smoke/	new smoke opening >1024 sockets	+60-80

Total: ~200 LoC C + ~10 Lua + ~80 LoC test = ~290 LoC.

Tiers

1. Linux poll() backend, opt-in via CMake (-DLUASOCKET_USE_POLL=ON, default OFF). 2-3 days.
2. Windows WSAPoll backend, same flag. WSAPoll has a historic non-blocking connect() reporting bug — workaround via getsockopt(SO_ERROR) after POLLWRNORM. 2-3 days.
3. Default ON + BUILDING.md update. 1 day.

Realistic total: 6-8 focused workdays, plus 1-2 days buffer for WSAPoll quirks.

Behaviour-difference risks

• poll() distinguishes POLLHUP / POLLERR / POLLIN; select() doesn't. Current code does not inspect why a socket is readable — just calls receive() and lets that report the error. Map POLLHUP|POLLERR|POLLNVAL → readable in the wrapper to preserve behaviour 1:1.
• Smoke test needs a synthetic >1024-socket load (pairs via socketpair() or many localhost connects). Today's smoke does not exercise this regime.

Out of scope

• epoll() on Linux for O(1) event delivery (vs poll's O(N) array scan). Worth doing if hub regularly serves 5000+ concurrent users; not before.
• libevent / libev / cqueues replacement of luasocket. Too invasive, this issue is the minimal fix.
• Replacing luadch with uhub for mass-hub use cases (upstream blasti's 2015 suggestion). Out of project scope.

Upstream maintenance

luasocket releases are slow (3.0 in 2013, 3.1 in 2022). Re-porting the poll diff at each upstream bump: ~1-2h.

When this is worth doing

Today, the hubs we know of (Sopor / similar) run <500 concurrent users — the limit is theoretical. This issue is for when:

• a luadch operator wants to host >800 concurrent users, OR
• we want to advertise luadch as suitable for public mass-hubs.

Until then, later label.

[Aybook]

Interaction with the max_users default (noted during #416 review)

max_users defaults to 3000, but the effective concurrent-socket ceiling until this select->poll port lands is FD_SETSIZE:

• Windows: 64 -> 1024 as of Windows: hub crashes at 64 concurrent sockets (luasocket FD_SETSIZE default) - raise to 1024 #416 (parity with Linux).
• Linux: 1024 (glibc's fixed fd_set).

max_users and FD_SETSIZE count different things:

	counts	enforced
max_users (3000)	logged-in users	at login (hub_dispatch.lua _cfg_max_users <= _get_user_count())
FD_SETSIZE (1024)	all sockets in the select loop	at TCP accept

Sockets = users + listeners (v4/v6 x tcp/ssl) + connections still in handshake + HBRI + HTTP + outbound. Consequences:

• A hub does not actually reach max_users=3000 concurrent on either platform today - it hits the ~1024 socket ceiling first. So this port is the real fix for large hubs, regardless of OS.
• max_users is not a guard against the FD_SETSIZE crash: pre-login / flood sockets are not counted by it. The guards are ratelimit_perip_max_conns + the FD_SETSIZE raise.

Decision (with the maintainer): keep max_users=3000 (design intent) rather than lower it to paper over a temporary implementation ceiling. This port removes the ceiling on both platforms, after which max_users becomes genuinely reachable.

[Aybook]

Code-surface re-verification (2026-07-14, against current master)

A fresh deep-dive against the current source shows the code-surface table above has drifted - it predates #416. Two of the three "scary" C items are already resolved, so the real change is smaller, Linux-only, and lower-risk than the original estimate. Keeping the later label; this is just to correct the record for whoever picks it up.

1. Unix socket_waitfd is ALREADY poll-based - 0 LoC, not ~25-30

SOCKET_SELECT is never defined in our build, so luasocket/src/usocket.c:20-41 (socket_waitfd, the per-socket connect/send/recv wait) already uses poll(). The select() variant with the if (*ps >= FD_SETSIZE) return EINVAL guard (usocket.c:53) is dead code. Consequence: per-socket I/O on an fd >= 1024 already works today; only the central event loop is FD_SETSIZE-bound. TLS is covered too - LuaSec links luasocket_static (built from the same usocket.c), so its bundled copy is dead in this build.

2. Windows already has FD_SETSIZE=1024 (#416) - WSAPoll is OUT OF SCOPE for the Linux fix

luasocket/CMakeLists.txt:73 + :114 set FD_SETSIZE=1024 for both the socket module and luasocket_static (landed in #416). On Winsock, fd_set is a SOCKET array of length FD_SETSIZE, i.e. a count, not a max-fd-value - so bumping it genuinely enlarges the watch set (Windows watches up to 1024 concurrent today). WSAPoll is only needed to exceed 1024 on Windows, which is not part of #310's Linux driver (glibc's fd_set is a fixed 1024-bit buffer that cannot be safely enlarged - hence the count-vs-value guard split at select.c:137 Windows vs :140 POSIX).

3. Real scope: Linux-only, ~120-180 LoC C, ~0 Lua

The genuinely-required work is a global_poll backend in luasocket/src/select.c (the Lua-facing luasocket.select), collecting into a struct pollfd[] instead of fd_set, dropping the FD_SETSIZE guard. Recommendation: swap the backend behind the existing select name rather than adding a new luasocket.poll - then the hub side is literally untouched. There is exactly ONE event-loop call site: core/server.lua:1219 (socket_select(_readlist, _sendlist, _selecttimeout)). The +3 Lua LoC estimate is if anything an overcount; the only Lua churn is the now-obsolete socket._SETSIZE boot-log at core/hub.lua:1888 (doc-currency).

4. Contract-fidelity is where ALL the risk lives (get these exact or the hub misbehaves)

The poll backend must reproduce select.c's contract byte-for-byte:

• check_dirty MUST be preserved (select.c:158-181): it force-includes sockets holding buffered-but-unconsumed data (LuaSec TLS records already decrypted at the SSL layer) and zeroes the timeout. Miss this and every TLS client with buffered app-data but no new kernel readable event stalls - and it looks like a hub bug, not a luasocket bug. Highest-fidelity-risk item (hub is TLS-by-default).
• Return two array-iterable tables, empty (never nil) on timeout - tick() does ipairs(read)/ipairs(write); ipairs(nil) crashes the hub every tick. Timeout path returns {}, {}, "timeout".
• Iterate inputs array-style 1..n (like collect_fd), ignoring the associative reverse-map entries in the hybrid _readlist/_sendlist.
• The same fd must be reportable in both read and write results in one tick (TLS want-write at server.lua:712-719, partial-send re-arm at 810-814).
• revents mapping: POLLIN|POLLHUP|POLLERR|POLLNVAL -> readable, POLLOUT|POLLERR -> writable. Surface an errored fd into both lists it was polled in (do not copy the partial POLLIN|POLLERR mask from the connect-only socket_waitfd). POLLNVAL->readable is actually better than select's all-or-nothing EBADF (isolates the one bad fd).
• pollfd buffer via lua_newuserdata (survives the luaL_error longjmp), not malloc.

5. WSAPoll connect-reporting bug is a non-issue for luadch (if Windows >1024 is ever pursued)

The historic WSAPoll bug (a failed non-blocking connect() not signalled via POLLERR/POLLHUP before Win10 2004) only bites code that infers connect-completion from a writability event. luadch's only such path is addclient/wrapclient, which is dead code (no in-tree caller; server.lua:1027 comment says so). core/http_client.lua (the only live outbound connector) detects connect by re-calling connect(), not by a readiness event; core/hbri.lua does no outbound connect. So keep Windows socket_waitfd on select() (uses exceptfd for connect) even if socket_select ever moves to WSAPoll; cheap insurance = the documented getsockopt(SO_ERROR)-after-POLLWRNORM guard for the latent path.

6. Testing: a real >1024 smoke is NOT CI-practical

Three walls: (a) GitHub ubuntu-latest default ulimit -n = 1024 (both hub and client need raising, hard cap 4096 without root); (b) the msys2 Python client is the Windows bottleneck; (c) the hub's own limits reject a naive single-IP test at connection #17 - ratelimit_perip_max_conns = 16. A real test needs a bespoke cfg (ratelimit_activate = false or the per-IP caps raised), a plain tcp_ports listener to dodge 1024 concurrent TLS handshakes, and bare-socket liveness. Recommendation: (i) a small per-PR functional test proving the poll path works at a handful of fds (fails pre-fix if the backend is absent), (ii) a manual/nightly load test that actually crosses 1024. Do not gate PRs on a real >1024 run.

7. Upstream will not provide a drop-in

Upstream luasocket's -DSOCKET_POLL only affects the per-socket socket_waitfd() waits (which we already have on poll) - NOT socket.select(), the API the main loop calls. The global_select poll backend is unfixed upstream since 2012; we would write it ourselves exactly as Tier 1 scopes.

Timing unchanged

The later trigger (an operator wanting >800 concurrent, or advertising mass-hub suitability) has not fired; #416's 1024-socket parity covers every known operator with margin. Revisit when a concrete operator reports hitting ~1000 concurrent.

[Aybook]

Implementation landed on feat/select-poll-eventloop -> #436 (targets dev for testhub validation). Scope matches the code-surface re-verification above:

• luasocket/src/select.c: a global_poll backend (variable-length struct pollfd[], no FD_SETSIZE cap) registered under the same select name behind #if defined(_WIN32). Windows keeps the fd_set/select path (FD_SETSIZE=1024, Windows: hub crashes at 64 concurrent sockets (luasocket FD_SETSIZE default) - raise to 1024 #416). All contract-parity items preserved: check_dirty force-include of buffered-decrypted TLS sockets, empty-not-nil result tables on timeout, a socket reportable in both read+write in one tick, errored fds surfaced into every watched list.
• hub/hub.c: raises RLIMIT_NOFILE soft->hard at boot so the default ulimit -n = 1024 does not become the new silent cap; getfdlimit() exposes the ceiling. Going above the hard limit still needs the OS (ulimit -Hn / systemd LimitNOFILE / Docker --ulimit nofile) - documented in docs/BUILDING.md.
• Backend-aware boot log + a backend-aware #416 smoke guard.

Validated on Linux (WSL Ubuntu): full smoke suite green on the real poll path; the reworked backend test is red pre-fix / green on the fix (§1a.7). No behavioural change on Windows (unchanged select path, build + smoke green). Two-pass §1a.6 review (C contract-fidelity + integration) found no correctness bugs.