szn

Bug 522 — behind is never cleared on backlog drop

522. Force-dropping the out-buffer leaves the client marked behind forever

Severity: MEDIUM Status: ✅ FIXED Files: src/server/server.zig:2830-2837, src/server/server.zig:2766-2772, src/server/server.zig:2890

Verification status: the logic was read from live source and the state machine is unambiguous; the reachability (a client accumulating >16 MiB behind) was not demonstrated. Treat as a lead until reproduced.

Problem

When a display client falls far enough behind, the server abandons its backlog:

// src/server/server.zig:2830-2837
if (dc.out_buf.items.len + total_len > MAX_OUT_BUF) {
    _ = self.flushDisplayClient(dc);
    if (dc.out_buf.items.len + total_len > MAX_OUT_BUF) {
        dc.out_buf.clearRetainingCapacity();
        dc.last_cells.clearRetainingCapacity();
        return false;
    }
}

The drop path clears out_buf and last_cells but leaves dc.behind == true and behind_count set. That combination deadlocks the client:

The result is that all_flushed stays false permanently, self.dirty is never cleared, and that client never receives another frame — even after it drains. appendClientOutUrgent (:2764) has the same omission.

Proposed Fix

When dropping the backlog, clear the flag in the same step:

if (dc.behind) {
    dc.behind = false;
    self.behind_count -|= 1;
}

and, if no client remains behind, call resumePaneReads(). Factor the cap check into one helper so both appendClientOut variants share it (see bug #520, site 1).

Fix

All backlog-clearing and client-disconnect sites (appendClientOutUrgent, appendClientOutFrame, removeClient, writeFrameToClient, and flushDisplayClient) now clear the flag through one helper:

// src/server/server.zig
fn clearBehind(self: *Server, dc: *DisplayClient) void {
    if (dc.behind) {
        dc.behind = false;
        self.behind_count -|= 1;
        if (!self.anyDisplayClientBehind()) {
            self.resumePaneReads();
        }
    }
}

The saturating decrement matches every other behind_count site, so a stale flag can never underflow the counter and make anyDisplayClientBehind() lie. When behind_count reaches zero, resumePaneReads() is called immediately to re-arm POLL.IN on every pane master pty (which was disarmed during throttling at server.zig:811). Without this, a force-drop left pane reads disarmed forever because out_buf was emptied and the flush catch-up path could never fire. The same fix applies to client disconnects (removeClient) and broken-pipe errors (writeFrameToClient / flushDisplayClient).

Regression test

clearBehind resets the flag and the counter — bug #522 and clearBehind resumes pane reads when behind_count reaches zero — bug #522 follow-up (src/server/server.zig) verify flag clearing, underflow safety, and that POLL.IN on pane master ptys is re-armed if and only if no client remains behind.

The drop sites themselves need a >16 MiB backlog (MAX_OUT_BUF = 16 << 20) to reach, which is too heavy for this suite’s shared DebugAllocator budget, so they are covered by inspection rather than by a test that fills the buffer.

Verified with the full suite on Zig 0.16.0 and 0.17.0: 1053/1053 passing on both.

Bugs #297, #298, #376 and #403 all concern display backpressure; #376 in particular is about responses being dropped while a client is marked behind.