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}