Track state of connections, seats, and devices

[glamberson]

Implements the state tracking requested in #15: equivalents of libei's
ei_state, ei_seat_state, ei_device_state and libeis's eis_client_state,
eis_seat_state, eis_device_state.

Changes

Six enums, one per side per object, all #[non_exhaustive]:

Client (event.rs)	Server (request.rs)
EiConnectionState: Connected, Disconnected	EisConnectionState: Connected, Disconnected
EiSeatState: New, Done, Removed	EisSeatState: Added, Bound, Removed
EiDeviceState: Paused, Resumed, Emulating, RemovedFromServer	EisDeviceState: AwaitingReady, Paused, Resumed, Emulating, ClosedByClient, Dead

Each is reachable through a state() accessor on the corresponding
Connection / Seat / Device wrapper. Client-side transitions are driven by
incoming protocol events, server-side ones by the calls that emit them.

Per-side rather than consolidated, because the two sides genuinely differ. A
server seat is Added then Bound; a client seat is New then Done. The
server device has AwaitingReady, ClosedByClient and Dead phases with no
client equivalent. Collapsing them would mean either inventing shared names for
different concepts or carrying variants one side can never reach.

States a converter can't observe are omitted rather than declared and never
set. Both sides drop the pre-done phases, since a seat or device is only
exposed after its done event. The client also drops REMOVED_FROM_CLIENT and
DEAD, because the converter doesn't model client-initiated release. Each
omission is documented on the enum it applies to.

Connection state is derived rather than stored on both sides, reading the
disconnected flag the server wrapper already had and that the client wrapper
now carries too. Seat and device state are stored, since they have more than
two states.

Relationship to #33

#33 landed after this branch was last updated and touches the same structs, so
this rebase resolves three collisions in DeviceInner and its construction
sites. All three are additive and the resolution keeps both sides.

The features themselves don't interact. #33 holds events that carry a timestamp
until an ei_device.frame commits them, and passes untimestamped events
straight through. Every event driving a lifecycle transition here is
untimestamped: Disconnected, SeatAdded, SeatRemoved, DeviceAdded,
DeviceRemoved, DevicePaused, DeviceResumed, DeviceStartEmulating. The
timestamped set #33 buffers is entirely input.

The per-device split helps here. #33 emits a frame before any untimestamped
device event that finds pending work, so a device's input events now arrive
ahead of the DevicePaused that follows them. With the previous shared queue, a
frame on one device could flush another's.

Scope

An earlier revision tracked pressed_keys, pressed_buttons and
down_touch_ids per device with public accessors. Those were dropped after
review. What remains is a private server-side down_touch_ids set with no
public accessor, used to enforce EIS_MAX_TOUCHES and to reject touch motion
or up for an id that isn't down.

Closes #15

[glamberson]

Rebased onto master now that #22 and #23 are in, and adapted to the changes there:

• The handler extraction that was part of this branch is gone, since Handle Release requests for devices and interfaces #23 already extracted the keyboard/button request handlers. The pressed key/button tracking now lives in those existing handlers instead.
• The device Release arm sets DeviceState::Closed when queueing DeviceClosed, matching libeis where eis_device_closed_by_client() updates the state before the server application calls remove. Device::remove() also sets it, so the state is correct on both legs of the two-step close.
• On the client side, the Destroyed handling combines the state update with the interface cleanup from Remove destroyed interfaces from device #22.

The diff against master is additive apart from the widened re-export.

[ids1024]

If we add this, presumably pressed_keys shouldn't be updated until the Frame event.

[ids1024]

Adding the state enums is definitely good, as long as all the uses of them are correct. Given that's how libei works. Though libei doesn't seem to expose them publicly. Is there a particularly good reason to make these public, or can we just leave them out of the public API surface? How useful is this in practice in applications using reis?

Without marking the enums as #[non_exhaustive], adding a variant would be a breaking API change. Though reis doesn't really have a stable API yet anyway.

pressed_keys, pressed_buttons, and down_touch_ids, meanwhile, isn't something libei/libeis has, right? It's not necessarily bad to offer something useful like that regardless, though there may be some potential to misuse it. (For instance, when processing a stream of events, these accessors won't provide the state at the time of the event being processed, if new events have caused changes.) And then it's also not ideal that these require cloning a HashSet.

Given we leave it up to the caller of the library to use something like xkbcommon to track the keyboard state, maybe it's best to let the caller managed its own pressed_keys, etc. That might make it easier to make sure it's being used correctly, could avoid the extra clone, and probably doesn't make application code all that much more complicated.

[glamberson]

I appreciate the detailed review. I've split the PR into its two halves based on your feedback.

I dropped the pressed-key, pressed-button, and touch tracking. You're right that libei and libeis don't offer it, and it's easy to misuse: The set updates as events come in, so a consumer that's processing a queued event can't rely on it to reflect the state as of that event, and every call clones the set. It's better left to the caller, which already tracks keyboard state through xkbcommon and can update its own set in step with the events it handles. The server's internal down_touch_ids field stays, since it's still needed for the EIS_MAX_TOUCHES enforcement.

I kept the lifecycle state enums and marked them #[non_exhaustive] as you suggested. That's the opinionated part of the change. I'd like Connection::state(), Seat::state(), and Device::state() as a small queryable surface for an out-of-band session-health check (for example, whether a device's resumed or the connection's still up) that runs outside the event loop. In that setting the caller just wants the latest known state, so the timing mismatch that makes the pressed-key tracking unsafe doesn't apply here. The same information can be derived from the resumed, paused, and disconnected events, but a lock-guarded enum on the handle that reis already owns seemed like the cleaner primitive.

Further out, I'm interested in lightweight per-device metrics for performance tuning, such as event throughput and timing to drive adaptive encoding. That's a separate conversation, and I've kept it out of this change to keep the scope minimal. I've rebased the branch onto master.

[ids1024]

Yeah, it's probably fine with #[non_exhaustive] to make these public, as long as there's a use for them.

[ids1024]

Something I didn't mention explicitly in #15 (since I wrote the issue more for my own reference) is that we should also use the state to have checks that messages are received or functions are called only in the appropriate state, and send protocol errors or log and return if it is incorrect. The hard part of this is carefully adding all of those checks that exist in libei and making sure they're all right.

That's the role the state machine serves in libei/libeis, given the enum isn't public.

But we should be able to add these things incrementally later; this validation can hopefully be considered a minor non-breaking change since it shouldn't affect any correct uses of the protocol.

Consolidated into three enums rather than six, since the client and server perspectives share the same state values.

The way libei/libei define these doesn't seem to be quite the same on client and server side, particularly the seat state seems different? Though I haven't carefully studied exactly how libei defines all of the states.

enum ei_device_state {
	/* Before the DeviceAddedDone was received */
	EI_DEVICE_STATE_NEW,
	EI_DEVICE_STATE_PAUSED,
	EI_DEVICE_STATE_RESUMED,
	EI_DEVICE_STATE_EMULATING,
	/**
	 * Client removed the device, we no longer accept events from the
	 * client
	 */
	EI_DEVICE_STATE_REMOVED_FROM_CLIENT,
	/**
	 * Server removed the device, we need to remove it ourselves now.
	 */
	EI_DEVICE_STATE_REMOVED_FROM_SERVER,
	/**
	 * Device has been removed by both sides.
	 */
	EI_DEVICE_STATE_DEAD,
};

enum eis_device_state {
	EIS_DEVICE_STATE_NEW,
	EIS_DEVICE_STATE_AWAITING_READY,
	EIS_DEVICE_STATE_PAUSED,
	EIS_DEVICE_STATE_RESUMED,
	EIS_DEVICE_STATE_EMULATING,
	EIS_DEVICE_STATE_CLOSED_BY_CLIENT,
	EIS_DEVICE_STATE_DEAD,
};

enum ei_seat_state {
	EI_SEAT_STATE_NEW,
	EI_SEAT_STATE_DONE,
	EI_SEAT_STATE_REMOVED,
};

enum eis_seat_state {
	EIS_SEAT_STATE_PENDING,
	EIS_SEAT_STATE_ADDED,
	EIS_SEAT_STATE_BOUND,
	EIS_SEAT_STATE_REMOVED_INTERNALLY, /* Removed internally but eis_seat_remove() may be called
					    */
	EIS_SEAT_STATE_REMOVED, /* Removed but still waiting for some devices to be removed */
	EIS_SEAT_STATE_DEAD,    /* Removed from our list */
};

enum ei_state {
	EI_STATE_NEW,           /* No backend yet */
	EI_STATE_BACKEND,       /* We have a backend */
	EI_STATE_CONNECTING,    /* client requested connect */
	EI_STATE_CONNECTED,     /* server has sent connect */
	EI_STATE_DISCONNECTING, /* in the process of cleaning up */
	EI_STATE_DISCONNECTED,
};

enum eis_client_state {
	EIS_CLIENT_STATE_NEW,        /* socket just handed over */
	EIS_CLIENT_STATE_CONNECTING, /* client completed setup but hasn't been accepted yet */
	EIS_CLIENT_STATE_CONNECTED,  /* caller has done eis_client_connect */
	EIS_CLIENT_STATE_REQUESTED_DISCONNECT, /* caller has disconnected */
	EIS_CLIENT_STATE_DISCONNECTED,
};

ei_state/ei_client_state can be reduced to 3 states here since the event/request converters are only after a complete handshake (so any extra validation there needs to be done separately), but otherwise we probably want all the states libei has, so we can ensure we validate everything in the same way?

[glamberson]

Following up on your review. The more I dug in response to your comments and went back through the issues, the more I think this PR's shape is wrong rather than just incomplete.

I built #21 the expedient way: I tracked each wrapper's state as events flowed and consolidated it into a few shared enums to get a lifecycle surface working quickly. But once I treated the state as a validation engine the way you framed it and went back to the protocol itself, the right shape came out quite different. The protocol doesn't define these states at all, so they're purely an internal modeling choice, and the per-side asymmetry that libei has matters in ways the consolidated version flattened.

So I'd rather not patch this incrementally. I'm treating #21 as suspended and moving the design discussion back to #15, where I'll lay out the per-side model and where the validation actually has to live before I write the rework. I'll either repurpose this branch or open a fresh one once the shape is settled there.

[glamberson]

I've pushed the per-side rework to the branch. It replaces the consolidated three-enum approach with separate client and server enums that match libei's variant sets, with the state tracked through the converters. The full shape, what I dropped from libei and why, and the open question of how much should be public are in #15. If you'd rather a different shape, say so there and I'll amend before adding the validation checks.