nomoreide_remote_protocol/

limits.rs

//! The frozen limits. Every number a v1 peer is allowed to assume about the
//! other side lives here, and nowhere else.
//!
//! They are constants rather than configuration on purpose. A limit either side
//! can tune is not a limit — it is a negotiation, and the frame that arrives
//! while the two ends disagree is the one that gets through. Changing any of
//! these is a protocol change: it needs a new major version, because a phone
//! built against the old number will send a frame the daemon now refuses.
//!
//! The byte counts are all measured over **UTF-8 bytes**, not characters. A
//! limit counted in `char`s is a limit an attacker picks the units of.

use std::time::Duration;

/// The largest frame either side will read off the socket.
///
/// Read *before* parsing: a 4 MiB frame that would have failed validation still
/// costs the memory to parse it, so the size check is the first thing that
/// happens and the socket closes rather than answering.
pub const MAX_FRAME_BYTES: usize = 256 * 1024;

/// The largest prompt one agent turn may carry.
///
/// Small relative to the frame budget because a prompt is the one field a
/// remote caller fully controls, and the daemon forwards it to a process.
pub const MAX_AGENT_PROMPT_BYTES: usize = 16 * 1024;

/// Where a single log line is cut. A service that writes a megabyte without a
/// newline must not be able to fill the frame budget by itself.
pub const MAX_LOG_LINE_BYTES: usize = 8 * 1024;

/// The most log lines one response may carry, whatever was asked for.
pub const MAX_LOG_LINES: usize = 200;

/// The ceiling on a whole log response, applied after per-line truncation —
/// 200 lines of 8 KiB would otherwise be 1.6 MiB.
pub const MAX_LOG_RESPONSE_BYTES: usize = 256 * 1024;

/// How many requests one device may have in flight.
///
/// The bound is per device rather than per user: it is the daemon's memory that
/// a flood consumes, and a user with two machines should not be able to starve
/// one by hammering the other.
pub const MAX_PENDING_COMMANDS: usize = 32;

/// How long a service action may take before the relay stops waiting.
///
/// A timeout is *not* a failure of the action — the daemon may well finish it.
/// That is why a timed-out mutation is never retried automatically; see
/// [`super::idempotency`].
pub const SERVICE_COMMAND_TIMEOUT: Duration = Duration::from_secs(30);

/// How often a connected daemon announces it is still there.
pub const HEARTBEAT_INTERVAL: Duration = Duration::from_secs(25);

/// How long the platform waits before calling a device offline.
///
/// Three heartbeat intervals, so a single dropped frame on a slow phone network
/// does not flap the device between states. Reaching it suspends command
/// routing rather than queueing — presence fails closed.
pub const PRESENCE_TIMEOUT: Duration = Duration::from_secs(75);

/// The ceiling on the daemon's reconnect backoff. Jittered by the connector, so
/// a platform restart does not bring every daemon back in the same second.
pub const RECONNECT_BACKOFF_CAP: Duration = Duration::from_secs(30);

/// How far in the past a frame's `sentAt` may be before it is refused.
///
/// The point is not clock accuracy, it is intent: a command that spent two
/// minutes in a queue is one whose sender has already given up and whose user
/// has moved on. Executing it then is a surprise, and for a mutation it is a
/// dangerous one.
pub const MAX_REQUEST_AGE: Duration = Duration::from_secs(60);

/// How far *ahead* of the receiver a frame's `sentAt` may be.
///
/// Phones have wrong clocks. Refusing everything from a device three minutes
/// fast would make it permanently unusable, so the window is generous in this
/// direction and the staleness rule above is what carries the security weight.
pub const MAX_CLOCK_SKEW_AHEAD: Duration = Duration::from_secs(300);

/// How long a request id is remembered for duplicate detection.
///
/// Longer than [`MAX_REQUEST_AGE`] so that the two rules cannot disagree: a
/// frame young enough to execute is always young enough to have been seen.
pub const REQUEST_ID_DEDUP_WINDOW: Duration = Duration::from_secs(600);

/// How long a remote approval waits for a human before it denies itself.
pub const APPROVAL_EXPIRY: Duration = Duration::from_secs(120);

/// How far back a reconnecting client may resume an agent run's events.
pub const AGENT_EVENT_REPLAY_WINDOW: Duration = Duration::from_secs(300);

/// A prompt that could fill a frame on its own would leave no room for the
/// envelope around it. Checked at compile time rather than in a test, because
/// it is a relationship between two constants and nothing should be able to
/// build with it broken.
const _: () = assert!(MAX_AGENT_PROMPT_BYTES * 2 < MAX_FRAME_BYTES);

/// The most events one run keeps for replay. A run that emits faster than the
/// window can hold drops the oldest; a client that asks for a sequence older
/// than the buffer is told to restart from the snapshot rather than handed a
/// gap it cannot see.
pub const AGENT_EVENT_REPLAY_EVENTS: usize = 2048;

/// The most raw PTY output carried in one frame, before base64.
///
/// Well under [`MAX_FRAME_BYTES`] with the encoding's third added on top, so a
/// coalesced burst can never be the thing that overflows a frame.
pub const MAX_TERMINAL_CHUNK_BYTES: usize = 32 * 1024;

/// How long the daemon gathers PTY output before sending it.
///
/// A TUI repaints far faster than anyone can read, and a frame per `read()`
/// would spend a phone's battery redrawing frames it never displays. Roughly
/// one screen's worth of latency, which is imperceptible while typing and
/// collapses a spinner into a handful of frames a second.
pub const TERMINAL_COALESCE_INTERVAL: Duration = Duration::from_millis(16);

/// The most keystroke data one input frame may carry.
///
/// Small on purpose: this is for typing, and a phone with a long block of text
/// to deliver should use the agent prompt path, which is bounded separately and
/// goes in as one paste rather than as a stream of keys.
pub const MAX_TERMINAL_INPUT_BYTES: usize = 4 * 1024;

/// How many terminals one device may have mirrored at once.
pub const MAX_TERMINAL_STREAMS: usize = 4;

/// The widest and tallest a mirrored terminal may claim to be. A resize is
/// attacker-supplied arithmetic that reaches `ioctl`, so it is bounded before
/// it gets there rather than trusted.
pub const MAX_TERMINAL_DIMENSION: u16 = 1_000;

// --- The inspection surface --------------------------------------------------
//
// Every list below is bounded twice: by the count, and by the prose budget the
// count multiplies against. A GitHub payload and a service's own error text are
// both written by somebody else, so neither the number of rows nor the length
// of a row is something this side gets to assume.

/// The most workflow runs one response may carry, whatever was asked for.
///
/// One page of GitHub's own listing. A phone scrolling further is a request for
/// a second page, which this protocol does not have — and deliberately: an
/// endless CI history is a website's job, and the phone's job is "is it green".
pub const MAX_WORKFLOW_RUNS: usize = 30;

/// The most jobs one workflow run's response may carry.
///
/// Larger than the run bound because a matrix build is genuinely wide, and a
/// truncated job list is the one case where the missing row is the failing one.
pub const MAX_WORKFLOW_JOBS: usize = 100;

/// The most pull requests one response may carry.
pub const MAX_PULL_REQUESTS: usize = 30;

/// The most incidents one response may carry.
pub const MAX_INCIDENTS: usize = 50;

/// The most timeline entries one response may carry.
pub const MAX_TIMELINE_ENTRIES: usize = 100;

/// Where any single piece of prose on the inspection surface is cut — a run
/// title, a pull request title, an incident title, a timeline detail.
///
/// These strings come from GitHub and from the user's own build output, so they
/// are unbounded at the source. Cutting each one keeps a single pathological
/// value from consuming the whole response, and the count bounds above then cap
/// the total.
pub const MAX_SUMMARY_BYTES: usize = 512;

/// The ceiling on a whole inspection response, applied after per-field
/// truncation, for the same reason [`MAX_LOG_RESPONSE_BYTES`] exists: the
/// per-item bounds multiplied out are much larger than anything worth sending.
pub const MAX_INSPECTION_RESPONSE_BYTES: usize = 128 * 1024;

/// The per-item cuts multiplied out must not overflow the response budget on
/// their own — otherwise the byte ceiling would be the only thing doing the
/// work, and it truncates a list without being asked. Checked at compile time,
/// like the prompt/frame relationship above, because nothing should build with
/// it broken.
const _: () = {
    assert!(MAX_WORKFLOW_JOBS * MAX_SUMMARY_BYTES <= MAX_INSPECTION_RESPONSE_BYTES);
    assert!(MAX_TIMELINE_ENTRIES * MAX_SUMMARY_BYTES <= MAX_INSPECTION_RESPONSE_BYTES);
    assert!(MAX_INSPECTION_RESPONSE_BYTES < MAX_FRAME_BYTES);
};

#[cfg(test)]
mod tests {
    use super::*;

    /// The numbers are frozen. This test exists to make changing one a
    /// deliberate act with a protocol-version conversation attached, rather
    /// than a one-character diff nobody reviews.
    #[test]
    fn v1_limits_are_frozen() {
        assert_eq!(MAX_FRAME_BYTES, 262_144);
        assert_eq!(MAX_AGENT_PROMPT_BYTES, 16_384);
        assert_eq!(MAX_LOG_LINE_BYTES, 8_192);
        assert_eq!(MAX_LOG_LINES, 200);
        assert_eq!(MAX_LOG_RESPONSE_BYTES, 262_144);
        assert_eq!(MAX_PENDING_COMMANDS, 32);
        assert_eq!(SERVICE_COMMAND_TIMEOUT.as_secs(), 30);
        assert_eq!(HEARTBEAT_INTERVAL.as_secs(), 25);
        assert_eq!(PRESENCE_TIMEOUT.as_secs(), 75);
        assert_eq!(RECONNECT_BACKOFF_CAP.as_secs(), 30);
        assert_eq!(APPROVAL_EXPIRY.as_secs(), 120);
        assert_eq!(MAX_TERMINAL_CHUNK_BYTES, 32_768);
        assert_eq!(MAX_TERMINAL_INPUT_BYTES, 4_096);
        assert_eq!(MAX_TERMINAL_STREAMS, 4);
        assert_eq!(MAX_TERMINAL_DIMENSION, 1_000);
        assert_eq!(TERMINAL_COALESCE_INTERVAL.as_millis(), 16);
    }

    /// The inspection bounds are frozen too, for the same reason: a phone that
    /// sizes a list against one of these numbers is relying on it.
    #[test]
    fn inspection_limits_are_frozen() {
        assert_eq!(MAX_WORKFLOW_RUNS, 30);
        assert_eq!(MAX_WORKFLOW_JOBS, 100);
        assert_eq!(MAX_PULL_REQUESTS, 30);
        assert_eq!(MAX_INCIDENTS, 50);
        assert_eq!(MAX_TIMELINE_ENTRIES, 100);
        assert_eq!(MAX_SUMMARY_BYTES, 512);
        assert_eq!(MAX_INSPECTION_RESPONSE_BYTES, 131_072);
    }

    /// A coalesced chunk must still fit a frame once base64 has added its
    /// third, with room for the envelope around it. Base64 is 4 bytes out per
    /// 3 in, so the check is the encoded size rather than the raw one.
    #[test]
    fn a_full_terminal_chunk_fits_a_frame_once_encoded() {
        let encoded = MAX_TERMINAL_CHUNK_BYTES.div_ceil(3) * 4;
        assert!(
            encoded * 2 < MAX_FRAME_BYTES,
            "a coalesced chunk must leave room for the envelope, not merely fit"
        );
    }

    /// A dedup window shorter than the staleness window would let a frame be
    /// young enough to execute but old enough to have been forgotten — which is
    /// exactly the replay the request id is there to stop.
    #[test]
    fn dedup_window_outlasts_request_staleness() {
        assert!(REQUEST_ID_DEDUP_WINDOW > MAX_REQUEST_AGE);
    }

    /// Offline has to mean "missed several", not "missed one".
    #[test]
    fn presence_timeout_tolerates_lost_heartbeats() {
        assert!(PRESENCE_TIMEOUT >= HEARTBEAT_INTERVAL * 3);
    }
}