Per-Connection Idle Timeout via ASIO Timer

[SeanTAllen]

Context

GitHub issue ponylang/stallion#46: the current idle timer approach in lori_http_server requires a shared Timers actor, creating two problems: (1) no timeout if the user doesn't supply one (footgun), and (2) if any connection gets backpressured the shared Timers actor can get muted, disabling idle timeouts for all connections (livelock). This PR adds the plumbing to lori so consumers can use per-connection idle timeouts without any extra actors, using the ASIO timer mechanism directly.

Approach

Add a second ASIO event (timer) per connection alongside the existing socket event. The Pony runtime already supports timerfd (Linux), EVFILT_TIMER (macOS/BSD), and WaitableTimer (Windows) through the same pony_asio_event_create API that the stdlib Timers actor uses. Timer events arrive at the same _event_notify behavior as socket events and are distinguished via event is _timer_event.

The timer resets on I/O activity (both send and receive), making it a true idle timeout. No extra actors, no inter-actor messaging, no muting risk.

Steps

1. Add FFI declaration and PonyAsio wrappers

File: lori/pony_asio.pony

• Add use @pony_asio_event_setnsec[U32](event: AsioEventID, nsec: U64) FFI declaration
• Add create_timer_event(the_actor, nsec) wrapper (calls @pony_asio_event_create with fd=0, AsioEvent.timer(), noisy=true — keeps the program alive while a timer is active)
• Add set_timer(event, nsec) wrapper (calls @pony_asio_event_setnsec)

2. Add _on_idle_timeout() to lifecycle receiver traits

File: lori/lifecycle_event_receiver.pony

Add _on_idle_timeout() with no-op default to both ServerLifecycleEventReceiver and ClientLifecycleEventReceiver. Docstring explains: fires when no send/receive for the configured duration, application decides what to do, timer auto-rearms, call idle_timeout(0) to disable.

3. Add timer fields and methods to TCPConnection

File: lori/tcp_connection.pony

New fields (after SSL fields):

• _timer_event: AsioEventID = AsioEvent.none()
• _idle_timeout_nsec: U64 = 0

Public API — idle_timeout(nsec: U64) placed after keepalive():

• Stores _idle_timeout_nsec = nsec
• If connected and nsec > 0: arms or resets the timer
• If connected and nsec == 0: cancels the timer
• If not yet connected: value is stored, timer armed when connection establishes

Internal methods:

• _arm_idle_timer() — create ASIO timer event via PonyAsio.create_timer_event(enclosing, nsec). Called when connection is established and _idle_timeout_nsec > 0.
• _reset_idle_timer() — guards not _timer_event.is_null() before calling PonyAsio.set_timer(_timer_event, nsec), else creates it via _arm_idle_timer(). Called on I/O activity.
• _cancel_idle_timer() — guards not _timer_event.is_null() before PonyAsio.unsubscribe + clear. Called on hard_close() and idle_timeout(0). The null guard is critical: unsubscribing a null AsioEventID triggers pony_assert(0) in the runtime.
• _fire_idle_timeout() — dispatches _on_idle_timeout() to lifecycle receiver, then re-arms if is_open() and _idle_timeout_nsec > 0.

4. Integrate timer into existing code paths

File: lori/tcp_connection.pony

Dispatch — at the top of _event_notify, before if event is _event:

if event is _timer_event → disposable? destroy : _fire_idle_timeout(); return

Arm — when TCP connection is established (before SSL handshake, so stalled handshakes trigger timeout):

• _complete_server_initialization: after _set_writeable() (line ~1189)
• _event_notify Happy Eyeballs success: after _set_readable() (line ~1055)

Reset on activity:

• _deliver_received(): first line, before match _ssl (any received data = activity)
• send(): before returning the token (line ~501)

Cancel on close:

• hard_close(): before PonyAsio.unsubscribe(_event) in the connected branch (line ~275), and in the not-connected early return branch (line ~251)

5. Add tests

File: lori/_test.pony

Three new tests, ports 7897-7899:

1. _TestIdleTimeout (port 7897) — Server sets 500ms idle timeout, client connects but sends nothing. Verify _on_idle_timeout fires. Test passes when the callback fires.

2. _TestIdleTimeoutReset (port 7898) — Server sets 500ms idle timeout, client sends data at 200ms intervals for 3 rounds (600ms total). Idle timeout should NOT fire during active sending. After client stops, timeout fires after 500ms of silence. Verify both that all data was received AND that the timeout fires after inactivity.

3. _TestIdleTimeoutDisable (port 7899) — Server sets 500ms idle timeout then immediately calls idle_timeout(0). Wait 1 second. _on_idle_timeout should never fire. Use a Timers-based watchdog to complete the test after 1s with success. Requires adding use "time" import to _test.pony.

Build and run: make test ssl=3.0.x

6. Add idle-timeout example

New file: examples/idle-timeout/idle-timeout.pony

Echo server variant with 10-second idle timeout. On _on_started, calls idle_timeout(10_000_000_000). On _on_idle_timeout, calls close(). Port 7672.

7. Update examples README

File: examples/README.md

Add idle-timeout entry after "backpressure" (ordered simplest to most involved — idle-timeout is a simple server variant).

8. Update package docstring

File: lori/lori.pony

Add "Idle Timeout" section after "Connection Limits" with usage example showing idle_timeout() and _on_idle_timeout().

9. Create release notes

File: .release-notes/next-release.md

Append section: "Add per-connection idle timeout". Classify as added. PR label: changelog - added.

10. Update CLAUDE.md

File: CLAUDE.md

• Source Layout: add idle-timeout/ to examples list
• Lifecycle Event Receivers description: add _on_idle_timeout to shared callbacks
• Add "### Idle timeout" architecture subsection after "### Send system"
• Note timer fields, arm/reset/cancel points, event dispatch

Edge Cases

• SSL handshake: Handshake data flows through _deliver_received, resetting the timer. Only a stalled handshake (no data) triggers timeout — correct behavior.
• STARTTLS: Timer already running from plaintext phase. Handshake data resets it normally.
• After hard_close: _cancel_idle_timer() unsubscribes. Final disposable event is handled. Timer cannot fire after close.
• Multiple idle_timeout() calls: Updates _idle_timeout_nsec and resets/creates the timer. No duplicate events.
• idle_timeout(0): Cancels timer, zeroes stored value. All timer methods become no-ops.
• Pre-connection config: Value stored, _arm_idle_timer() called when connection establishes.
• TCPConnection.none(): _idle_timeout_nsec = 0 by default, all timer methods are no-ops.

Verification

make test ssl=3.0.x        # All tests including 3 new idle timeout tests
make examples ssl=3.0.x    # All examples including idle-timeout
make ci ssl=3.0.x           # Full CI

Manual: run idle-timeout example, connect via netcat localhost 7672, verify echoing works and connection closes after 10s of silence.

[SeanTAllen]

Review Decisions

1. Reset once per read event

Move the timer reset from _deliver_received() to _read() (POSIX) and _read_completed() (Windows). This gives one set_timer syscall per read event instead of per chunk, since _deliver_received() is called in a loop during _read().

2. Don't clear _timer_event until disposable arrives

Mirror the _event disposal pattern: add a _timer_cancelled: Bool flag to prevent re-arming after cancel, but keep _timer_event set until the disposable notification arrives so the dispatch in _event_notify handles it explicitly. This avoids relying on the Happy Eyeballs catch-all handler for timer disposal cleanup.

3. Document backpressure interaction

The _on_idle_timeout docstring should clarify that it measures application-level inactivity (successful sends and receives), not wire-level inactivity. During sustained backpressure with no receives, the timer fires because send() only resets on success (SendToken), not on SendErrorNotWriteable. Pending write completions (OS draining the buffer) also don't reset the timer. This is correct behavior — the application isn't doing I/O — but could surprise users who expect "data flowing to the OS" to count as activity.

4. Use 5-second test timeouts

CI runners (especially Windows ARM) experience significant scheduling jitter. Use generous timing margins:

Test	Timeout	Send interval	Rounds	Margin	Approx duration
1 (basic fires)	5s	—	—	—	~5s
2 (reset on activity)	5s	1s	3	4s	~8s
3 (disable)	5s	—	—	watchdog at 10s	~10s

Long_test timeouts at 3x expected duration (15s, 25s, 30s) to absorb extreme jitter.

Test 2 send scheduling uses the stdlib Timers actor with one-shot Timer callbacks in the test client. This is fine for tests — the shared-actor muting problem that motivates this feature doesn't apply in test contexts.

5. Simplify _reset_idle_timer()

Remove the fallback to _arm_idle_timer(). The method becomes: if not _timer_event.is_null() then PonyAsio.set_timer(_timer_event, _idle_timeout_nsec). During normal I/O, _timer_event is null only when _idle_timeout_nsec is 0 (no timeout configured) or pre-connection (no I/O happening). The fallback path is unreachable.

6. Document keepalive vs idle_timeout distinction

The idle_timeout docstring should note that TCP keepalive is a transport-level probe for detecting dead connections, while idle_timeout is application-level inactivity detection. They are independent mechanisms and can be used together.

[SeanTAllen]

Implemented in #194.