Events Monitoring and Shell Integration

Events, Monitoring, and Shell Integration

中文 · Session State and Events

The project has two event models with different purposes. SessionEvent is the formal runtime input for an active remote session. ScrcpyEventBus provides application-level cross-component notification, statistics, and compatibility projections. The latter must not replace the session state machine.

Session events first

Events that change ADB, server, socket, decoder, cleanup, or reconnect facts enter the current Session.handleEvent(). One Channel serially reduces them into SessionState and the component snapshot. New main-path code must not update only the global bus while leaving session state unchanged.

ScrcpyEventBus is appropriate for:

• Cross-module notifications such as USB detach and connection lost.
• Shell, forward, and file-push observation statistics.
• Sampled telemetry such as media frames and socket bytes.
• Native status/error callbacks and main-thread dispatch.

It must not persist user configuration, own connection resources, decide reconnect budget, or become the UI's only truth.

Bus flow and sampling

ScrcpyEventLoop serially consumes an unbounded Channel, asks ScrcpyEventLogger to log, then calls the handler registered for the event class. ScrcpyEventMonitor projects Shell, forward, files, ADB verification, server logs, sockets, media, device screen, connections, and exceptions into device monitor state.

• High-frequency events whose needsSampling() is true log every 100th item while total statistics continue accumulating.
• Lifecycle, failure, user action, and resource-boundary events are not sampled because their order matters.
• Because the Channel is unbounded, producers still aggregate high-frequency data at the source; they must not publish every byte or pointer sample without limit.
• Handler registration currently retains one function per event class. Confirm that a new consumer will not overwrite an existing handler.
• Monitor state is a diagnostic projection cleared by device id on disconnect; it does not drive the session backward.

Shell APIs

AdbShellManager.execute(connection, command, retryOnFailure, reportToEventBus) runs on the IO dispatcher and publishes ShellCommandExecuted or ShellCommandFailed. Internal probes such as property reads and heartbeat may disable bus reporting to avoid noise.

Choose an entry point:

• One-shot command: AdbConnection.executeShell(); use AdbShellManager.execute() when unified statistics are required.
• Continuous output: openStreamingShellStream() on the delayed-ACK streaming lane.
• Interactive terminal: openPtyShellStream(); the implementation may fall back to a raw stream on failure.
• scrcpy-specific server and forward orchestration remains in ConnectionLifecycle, not the generic Shell manager.

Integration checklist

• Is this a session fact, cross-module notification, telemetry, or just a function result?
• Does it carry device/session correlation without treating an mDNS resolved endpoint as transport identity?
• Are command arguments quoted safely, and can output contain sensitive or unbounded content?
• Are failure, cancellation, and stream close reported once while preserving cancellation semantics?
• Is high-frequency data aggregated at the source with explicit sampling?
• Is a projection being misused as resource owner or reconnect trigger?