Skip to main content

krot_proto/
frames.rs

1//! Control-stream frames (§7, §14.2).
2//!
3//! Every variant is encoded with `postcard`; the outer framing (varint
4//! length prefix) is handled by [`crate::framing`].
5
6use serde::{Deserialize, Serialize};
7
8use crate::error::ErrorCode;
9use crate::ids::{Nonce, PubKey, SessionId, Signature, TunnelId};
10
11/// Kind of tunnel a client wants to register.
12#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
13pub enum TunnelKind {
14    /// HTTP(S) tunnel, routed by subdomain. Valid only in DomainMode (§15.1).
15    Http,
16    /// Raw TCP tunnel. `remote_port` MAY request a specific server port; if
17    /// unset the server picks one from its pool.
18    Tcp { remote_port: Option<u16> },
19}
20
21/// A frame sent by the client on the Control stream.
22#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
23pub enum ClientFrame {
24    /// Begin authenticated session by presenting a public key (§7.1 step 1).
25    AuthRequest { pubkey: PubKey },
26    /// Sign the challenge returned by the server (§7.1 step 3).
27    AuthResponse { signature: Signature },
28
29    /// Register a tunnel or resume a previous session (§7.2, §7.3).
30    ///
31    /// `inspect` opts into the server-provided passive inspection
32    /// prelude on every server-opened Data stream (§16.2). When
33    /// `false` the server MUST NOT emit a prelude.
34    RegisterTunnel {
35        label: String,
36        kind: TunnelKind,
37        resume_session_id: Option<SessionId>,
38        inspect: bool,
39    },
40    /// Explicitly close a previously registered tunnel.
41    UnregisterTunnel { tunnel_id: TunnelId },
42
43    /// Application-level ping. Server echoes with the same nonce.
44    Ping { nonce: u64 },
45
46    /// Graceful shutdown signal. Prevents lease resumption for open tunnels.
47    Bye,
48
49    /// Bootstrap: exchange an admin token for enrollment (§14.2).
50    ///
51    /// A connection presenting this frame is treated as bootstrap-only:
52    /// the server closes it immediately after enrollment succeeds or fails.
53    Enroll {
54        admin_token: String,
55        pubkey: PubKey,
56        label_hint: Option<String>,
57    },
58
59    /// Ask the server for the list of federated peer relays that this
60    /// identity is authorized to publish tunnels on (§16.3.3).
61    ///
62    /// The response is a [`ServerFrame::Peers`] whose `relays` is the
63    /// intersection of the server's static peer list (§16.3.2) and the
64    /// identity's `federation=` allowlist (§16.3.1).
65    ListPeers,
66}
67
68/// A frame sent by the server on the Control stream.
69#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
70pub enum ServerFrame {
71    /// Challenge to be signed by the client (§7.1 step 2).
72    AuthChallenge {
73        nonce: Nonce,
74    },
75    /// Successful authentication; the enclosed session id may be used for resume.
76    AuthOk {
77        session_id: SessionId,
78    },
79    /// Authentication failed.
80    AuthReject {
81        code: ErrorCode,
82    },
83
84    /// Confirms a tunnel registration.
85    TunnelRegistered {
86        tunnel_id: TunnelId,
87        public_url: String,
88        public_port: Option<u16>,
89    },
90    /// Rejects a tunnel registration.
91    TunnelRejected {
92        code: ErrorCode,
93        detail: String,
94    },
95
96    /// Echo of a client `Ping`.
97    Pong {
98        nonce: u64,
99    },
100
101    /// Notifies the client that quota or bandwidth limits were hit.
102    RateLimit {
103        tunnel_id: Option<TunnelId>,
104        retry_after_ms: u32,
105    },
106
107    /// Server-initiated shutdown of the session.
108    ServerBye {
109        code: ErrorCode,
110    },
111
112    /// Enrollment outcome (§14.3).
113    EnrollOk {
114        authorized_line: String,
115    },
116    EnrollRejected {
117        code: ErrorCode,
118    },
119
120    /// Response to [`ClientFrame::ListPeers`] (§16.3.3).
121    ///
122    /// `relays` carries apex domains (optionally with an explicit
123    /// `<apex>:<quic_port>` when the peer is on a non-default port).
124    /// May be empty if the identity has no `federation=` overlap with
125    /// the server's static peer list.
126    Peers {
127        relays: Vec<String>,
128    },
129}
130
131/// Passive inspection prelude (§16.2). Emitted by the server between
132/// the §5.1 Data-stream header and the first byte of tunneled payload,
133/// but only when the tunnel was registered with `inspect = true`.
134///
135/// Wire layout: length-prefixed postcard value (same framing as
136/// Control frames — see §6).
137#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
138pub struct InspectionPrelude {
139    /// Wall-clock timestamp of the public-side accept, seconds since
140    /// UNIX epoch. Coarse enough to survive replay ordering.
141    pub accept_unix_secs: u64,
142    /// Peer address that hit the public port, formatted as
143    /// `<ip>:<port>`.
144    pub peer: String,
145    /// Present for HTTP tunnels; None for raw TCP.
146    pub http: Option<HttpMetadata>,
147}
148
149/// Router-derived metadata for HTTP tunnels. The server extracts this
150/// from bytes it already parses for routing (Host header for plain HTTP,
151/// SNI for HTTPS); it never re-parses the tunneled payload.
152#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
153pub struct HttpMetadata {
154    /// Best available host string: Host header (plain HTTP) or SNI
155    /// (HTTPS passthrough). Empty when neither was extractable.
156    pub host: String,
157    /// TLS ClientHello SNI, when the traffic is HTTPS-passthrough.
158    /// `None` for plain HTTP.
159    pub sni: Option<String>,
160}