git_policy_cli/
service_protocol.rs

1//! What:
2//!  The messages between the wrapper and the resident commit service, one JSON object per line.
3//! Why:
4//!  A client sends a prepared change with a request identity and waits; the service answers with a landing, a queue
5//!  position, a request to prepare again, or a failure from a closed list. The line form needs no framing library and
6//!  every field is checked on read, so a damaged or hostile line is refused rather than guessed
7//!  (`doc/planning/cli-git-resident-service.md`, "Protocol and request identity").
8//!
9//! In TS you'd write (pseudocode):
10//! ```ts
11//! socket.write(JSON.stringify(encodeRequest(request)) + '\n'); const reply = decodeResponse(await readLine(socket));
12//! ```
13
14use serde_json::{Map, Value};
15use std::path::PathBuf;
16
17/// The protocol version this build speaks; a service and a client agree when their versions are equal.
18pub const PROTOCOL_VERSION: u32 = 2;
19
20/// The longest line either side accepts, in bytes.
21pub const MAX_LINE_BYTES: usize = 1 << 20;
22
23/// The most paths one request may change.
24pub const MAX_CHANGES: usize = 4096;
25
26/// Modes a change may give a file.
27pub const ALLOWED_MODES: [u32; 3] = [0o100_644, 0o100_755, 0o120_000];
28
29/// What:
30///  One path a commit changes: a file to set, or a file to delete.
31/// Why:
32///   The client has already written the file's content into the repository's object store, so the service names the
33///  object and never reads the user's worktree.
34///
35/// In TS you'd write (pseudocode):
36/// ```ts
37/// type Change = { path: string; mode: number; blob?: string }; // no blob means delete
38/// ```
39#[derive(Clone, Debug, Eq, PartialEq)]
40pub struct Change {
41    /// Repository-relative path with `/` separators.
42    pub path: String,
43    /// File mode, one of `ALLOWED_MODES`.
44    pub mode: u32,
45    /// Object name of the content, or nothing for a deletion.
46    pub blob: Option<String>,
47}
48
49/// What:
50///  A request to land one commit.
51/// Why:
52///   Every field the service needs to land it on the current branch without asking the client anything.
53///
54/// In TS you'd write (pseudocode):
55/// ```ts
56/// type CommitRequest = { id; repository; commonDir; reference; base; changes; message; author?; committer };
57/// ```
58#[derive(Clone, Debug, Eq, PartialEq)]
59pub struct CommitRequest {
60    /// Random identity of this invocation, kept across reconnects.
61    pub id: String,
62    /// Worktree root whose index is updated.
63    pub repository: PathBuf,
64    /// Common git directory shared by the worktrees; the queue key.
65    pub common_dir: PathBuf,
66    /// Full name of the branch the commit goes on.
67    pub reference: String,
68    /// The commit the client prepared against.
69    pub base: String,
70    /// The paths to change.
71    pub changes: Vec<Change>,
72    /// The commit message, exact bytes.
73    pub message: String,
74    /// `Name <email> seconds zone`, or nothing to use the committer.
75    pub author: Option<String>,
76    /// `Name <email> seconds zone`.
77    pub committer: String,
78}
79
80/// The closed list of reasons the service gives for not landing a request.
81#[derive(Clone, Copy, Debug, Eq, PartialEq)]
82pub enum FailureCode {
83    /// The repository has no room.
84    RepositoryFull,
85    /// The repository cannot be written.
86    RepositoryReadOnly,
87    /// Another program holds the repository's index.
88    IndexInUse,
89    /// The request is not one the service accepts.
90    Rejected,
91    /// The branch moved too often while the request waited.
92    BranchKeepsChanging,
93    /// Anything else the service could not resolve.
94    Unavailable,
95}
96
97impl FailureCode {
98    /// The word on the wire.
99    pub fn word(self) -> &'static str {
100        return match self {
101            Self::RepositoryFull => "repository-full",
102            Self::RepositoryReadOnly => "repository-read-only",
103            Self::IndexInUse => "index-in-use",
104            Self::Rejected => "rejected",
105            Self::BranchKeepsChanging => "branch-keeps-changing",
106            Self::Unavailable => "unavailable",
107        };
108    }
109
110    /// Every code, so a test reaches all of them.
111    pub const ALL: [Self; 6] = [
112        Self::RepositoryFull,
113        Self::RepositoryReadOnly,
114        Self::IndexInUse,
115        Self::Rejected,
116        Self::BranchKeepsChanging,
117        Self::Unavailable,
118    ];
119
120    /// The code for a word, nothing for an unknown word.
121    pub fn from_word(word: &str) -> Option<Self> {
122        return Self::ALL.into_iter().find(|code| { return code.word() == word; });
123    }
124}
125
126/// What a client sends.
127#[derive(Clone, Debug, Eq, PartialEq)]
128pub enum ClientMessage {
129    /// Land this commit.
130    Commit(Box<CommitRequest>),
131    /// Finish the queue and exit, so the manager starts the current binary.
132    Retire,
133    /// Work items were written for this repository; run what is pending.
134    Work {
135        /// The repository's common Git directory, which holds the work directory.
136        common_dir: PathBuf,
137    },
138}
139
140/// What the service sends.
141#[derive(Clone, Debug, Eq, PartialEq)]
142pub enum ServiceMessage {
143    /// First line of every connection: the service's protocol version.
144    Welcome { version: u32 },
145    /// The request is queued behind others.
146    Position { number: usize, of: usize },
147    /// The commit is on the branch; `already` when an earlier request with the same identity landed it.
148    Landed { id: String, commit: String, already: bool },
149    /// A named path changed on the branch since the base; prepare again from `base`.
150    RetryPrepare { id: String, base: String },
151    /// The request was not landed.
152    Failed { id: String, code: FailureCode },
153}
154
155fn field<'a>(value: &'a Value, name: &str) -> Result<&'a str, String> {
156    return value.get(name).and_then(Value::as_str).ok_or_else(|| { return format!("field {name} is missing or not text"); });
157}
158
159/// Whether `text` is a full object name in hexadecimal (40 or 64 digits).
160pub fn is_object_name(text: &str) -> bool {
161    return (text.len() == 40 || text.len() == 64) && text.bytes().all(|byte| { return byte.is_ascii_hexdigit(); });
162}
163
164/// Whether `path` is a plain repository-relative path: no leading slash, no empty, `.` or `..` part, no NUL or newline.
165pub fn is_plain_path(path: &str) -> bool {
166    return !path.is_empty()
167        && !path.starts_with('/')
168        && !path.contains(['\0', '\n'])
169        && path.split('/').all(|part| { return !part.is_empty() && part != "." && part != ".." && part != ".git"; });
170}
171
172/// One JSON object, written on one line from its entries.
173fn object(entries: Vec<(&str, Value)>) -> String {
174    let mut map: Map<String, Value> = Map::new();
175    for (key, value) in entries {
176        map.insert(key.to_string(), value);
177    }
178    return Value::Object(map).to_string();
179}
180
181/// What:
182///  The line for a client message.
183/// Why:
184///   One object per line, no newline inside any field.
185///
186/// In TS you'd write (pseudocode):
187/// ```ts
188/// JSON.stringify(message)
189/// ```
190pub fn encode_client(message: &ClientMessage) -> String {
191    return match message {
192        ClientMessage::Retire => object(vec![("type", Value::from("retire")), ("version", Value::from(PROTOCOL_VERSION))]),
193        ClientMessage::Work { common_dir } => object(vec![
194            ("type", Value::from("work")),
195            ("version", Value::from(PROTOCOL_VERSION)),
196            ("commonDir", Value::from(common_dir.to_string_lossy().as_ref())),
197        ]),
198        ClientMessage::Commit(request) => object(vec![
199            ("type", Value::from("commit")),
200            ("version", Value::from(PROTOCOL_VERSION)),
201            ("id", Value::from(request.id.as_str())),
202            ("repository", Value::from(request.repository.to_string_lossy().as_ref())),
203            ("commonDir", Value::from(request.common_dir.to_string_lossy().as_ref())),
204            ("reference", Value::from(request.reference.as_str())),
205            ("base", Value::from(request.base.as_str())),
206            (
207                "changes",
208                Value::Array(
209                    request
210                        .changes
211                        .iter()
212                        .map(|change| {
213                            return Value::Object(Map::from_iter([
214                                (String::from("path"), Value::from(change.path.as_str())),
215                                (String::from("mode"), Value::from(change.mode)),
216                                (String::from("blob"), change.blob.as_deref().map_or(Value::Null, Value::from)),
217                            ]));
218                        })
219                        .collect(),
220                ),
221            ),
222            ("message", Value::from(request.message.as_str())),
223            ("author", request.author.as_deref().map_or(Value::Null, Value::from)),
224            ("committer", Value::from(request.committer.as_str())),
225        ]),
226    };
227}
228
229/// What:
230///  Reads and checks one client line.
231/// Why:
232///   The service trusts nothing from a socket: sizes, names, paths, modes and the object names are all checked.
233///
234/// In TS you'd write (pseudocode):
235/// ```ts
236/// decodeClient(line) // throws on anything that is not a well-formed message
237/// ```
238pub fn decode_client(line: &str) -> Result<ClientMessage, String> {
239    if line.len() > MAX_LINE_BYTES {
240        return Err(String::from("line is too long"));
241    }
242    let value: Value = serde_json::from_str(line).map_err(|error| { return error.to_string(); })?;
243    if value.get("version").and_then(Value::as_u64) != Some(u64::from(PROTOCOL_VERSION)) {
244        return Err(String::from("unsupported version"));
245    }
246    match field(&value, "type")? {
247        "retire" => return Ok(ClientMessage::Retire),
248        "work" => {
249            let common_dir: PathBuf = PathBuf::from(field(&value, "commonDir")?);
250            if !common_dir.is_absolute() || common_dir.to_string_lossy().contains('\0') {
251                return Err(String::from("work request is not acceptable"));
252            }
253            return Ok(ClientMessage::Work { common_dir });
254        }
255        "commit" => {}
256        other => return Err(format!("unknown message type {other}")),
257    }
258    let mut changes: Vec<Change> = Vec::new();
259    for entry in value.get("changes").and_then(Value::as_array).ok_or("changes is missing")? {
260        let path: &str = field(entry, "path")?;
261        let mode: u32 = u32::try_from(entry.get("mode").and_then(Value::as_u64).ok_or("mode is missing")?)
262            .map_err(|_| { return String::from("mode is out of range"); })?;
263        let blob: Option<String> = entry.get("blob").and_then(Value::as_str).map(str::to_string);
264        if !is_plain_path(path) || !ALLOWED_MODES.contains(&mode) || blob.as_deref().is_some_and(|name| { return !is_object_name(name); }) {
265            return Err(format!("change for {path:?} is not acceptable"));
266        }
267        changes.push(Change { path: path.to_string(), mode, blob });
268    }
269    if changes.len() > MAX_CHANGES {
270        return Err(String::from("number of changes is not acceptable"));
271    }
272    let request = CommitRequest {
273        id: field(&value, "id")?.to_string(),
274        repository: PathBuf::from(field(&value, "repository")?),
275        common_dir: PathBuf::from(field(&value, "commonDir")?),
276        reference: field(&value, "reference")?.to_string(),
277        base: field(&value, "base")?.to_string(),
278        changes,
279        message: field(&value, "message")?.to_string(),
280        author: value.get("author").and_then(Value::as_str).map(str::to_string),
281        committer: field(&value, "committer")?.to_string(),
282    };
283    let well_formed: bool = !request.id.is_empty()
284        && request.id.bytes().all(|byte| { return byte.is_ascii_alphanumeric() || byte == b'-'; })
285        && request.reference.starts_with("refs/")
286        && !request.reference.contains(['\0', '\n', ' '])
287        && is_object_name(&request.base)
288        && request.repository.is_absolute()
289        && request.common_dir.is_absolute()
290        && !request.committer.contains(['\0', '\n'])
291        && request.author.as_deref().is_none_or(|author| { return !author.contains(['\0', '\n']); });
292    if !well_formed {
293        return Err(String::from("request is not acceptable"));
294    }
295    return Ok(ClientMessage::Commit(Box::new(request)));
296}
297
298/// What:
299///  The line for a service message.
300/// Why:
301///   The same one-object form in the other direction.
302///
303/// In TS you'd write (pseudocode):
304/// ```ts
305/// JSON.stringify(message)
306/// ```
307pub fn encode_service(message: &ServiceMessage) -> String {
308    return match message {
309        ServiceMessage::Welcome { version } => object(vec![("type", Value::from("welcome")), ("version", Value::from(*version))]),
310        ServiceMessage::Position { number, of } => {
311            object(vec![("type", Value::from("position")), ("number", Value::from(*number)), ("of", Value::from(*of))])
312        }
313        ServiceMessage::Landed { id, commit, already } => object(vec![
314            ("type", Value::from("landed")),
315            ("id", Value::from(id.as_str())),
316            ("commit", Value::from(commit.as_str())),
317            ("already", Value::from(*already)),
318        ]),
319        ServiceMessage::RetryPrepare { id, base } => {
320            object(vec![("type", Value::from("retry-prepare")), ("id", Value::from(id.as_str())), ("base", Value::from(base.as_str()))])
321        }
322        ServiceMessage::Failed { id, code } => {
323            object(vec![("type", Value::from("failed")), ("id", Value::from(id.as_str())), ("code", Value::from(code.word()))])
324        }
325    };
326}
327
328/// What:
329///  Reads one service line.
330/// Why:
331///   The client checks what it is told as strictly as the service checks what it is sent.
332///
333/// In TS you'd write (pseudocode):
334/// ```ts
335/// decodeService(line)
336/// ```
337pub fn decode_service(line: &str) -> Result<ServiceMessage, String> {
338    if line.len() > MAX_LINE_BYTES {
339        return Err(String::from("line is too long"));
340    }
341    let value: Value = serde_json::from_str(line).map_err(|error| { return error.to_string(); })?;
342    let number = |name: &str| -> Result<usize, String> {
343        return value.get(name).and_then(Value::as_u64).and_then(|n| { return usize::try_from(n).ok(); })
344            .ok_or_else(|| { return format!("field {name} is missing"); });
345    };
346    return match field(&value, "type")? {
347        "welcome" => Ok(ServiceMessage::Welcome {
348            version: u32::try_from(number("version")?).map_err(|_| { return String::from("version is out of range"); })?,
349        }),
350        "position" => Ok(ServiceMessage::Position { number: number("number")?, of: number("of")? }),
351        "landed" => Ok(ServiceMessage::Landed {
352            id: field(&value, "id")?.to_string(),
353            commit: field(&value, "commit")?.to_string(),
354            already: value.get("already").and_then(Value::as_bool).unwrap_or(false),
355        }),
356        "retry-prepare" => Ok(ServiceMessage::RetryPrepare { id: field(&value, "id")?.to_string(), base: field(&value, "base")?.to_string() }),
357        "failed" => Ok(ServiceMessage::Failed {
358            id: field(&value, "id")?.to_string(),
359            code: FailureCode::from_word(field(&value, "code")?).ok_or("unknown failure code")?,
360        }),
361        other => Err(format!("unknown message type {other}")),
362    };
363}
364
365/// Protocol controls stay out of the release executable.
366#[cfg(test)]
367#[path = "service_protocol_tests.rs"]
368mod tests;
git_policy_cli/service_protocol.rs

git_policy_cli/
service_protocol.rs
