Added crate level docs to mirrord-protocol (#3231)

* Added crate level docs

* Bump mirrord-protocol version

Author: Razz4780

Cargo.lock

@@ -0,0 +1 @@
+Added some documentation to the `mirrord-protocol` crate.

changelog.d/3182.internal.md

@@ -1,6 +1,6 @@
 [package]
 name = "mirrord-protocol"
-version = "1.19.2"
+version = "1.19.3"
 authors.workspace = true
 description.workspace = true
 documentation.workspace = true

mirrord/protocol/Cargo.toml

@@ -1,3 +1,58 @@
+//! This crate contains the definition of the mirrord-protocol,
+//! which is used in communication between various components of mirrord, e.g. the CLI and the agent
+//! or the CLI and the operator.
+//!
+//! # Protocol
+//!
+//! The protocol is based on [`bincode`]. It is defined **only** by the Rust types in this crate.
+//!
+//! Since mirrord components (namely: CLI, agent and operator) are distributed independently,
+//! it is important to remember that the peer might not use the same version of the protocol.
+//! This protocol must be kept backwards compatible.
+//!
+//! # Backwards compatibility
+//!
+//! To keep this protocol backwards compatible, limit your changes to:
+//! 1. Renaming types, fields, or variants.
+//! 2. Changing the type of a field, given that [`bincode`] representation is the same e.g. `T` ->
+//!    `Arc<T>`.
+//! 3. Adding a new variant to an enum, given that the new variant is the last one. Before sending
+//!    the new variant, make sure that the peer can handle it (check their version of
+//!    mirrord-protocol). We usually store version requirements in static variables, e.g.
+//!    [`tcp::HTTP_FRAMED_VERSION`].
+//! 4. Code unrelated to types' representation on the wire.
+//!
+//! Example changes that **do break** backwards compatibility:
+//! 1. Adding a new field.
+//! 2. Changing the type of a field from `T` to `Option<T>` and vice versa.
+//! 3. Reordering variants of an enum.
+//!
+//! If you're not sure whether your change is breaking,
+//! you can check it manually with a unit test.
+//!
+//! # Versioning
+//!
+//! The version of the protocol is stored in the [`VERSION`] static variable
+//! and is the same as the version of this crate.
+//!
+//! Unlike the other crates in this workspace, this crate is versioned independently.
+//!
+//! Mind that CI checks that the version of this crate is bumped
+//! whenever the files in this crate are modified, regardless of what the change actually is.
+//!
+//! When you make changes to this crate:
+//! 1. If you're extending the protocol, bump minor version.
+//! 2. Otherwise, bump patch version.
+//!
+//! # Utilities
+//!
+//! * [`ClientCodec`] and [`ProtocolCodec`] implement [`actix_codec::Decoder`] can be used with
+//!   [`actix_codec::Framed`] transform an IO stream into
+//!   [`Sink`](futures::Sink)+[`Stream`](futures::Stream) of mirrord-protocol messages.
+//! * Some mirrord-protocol types implement conversion to/from [`socket2`] and [`hyper`] types.
+//!   These should probably be implemented elsewhere (to remove dependencies from this crate), but
+//!   right now we have these deps everywhere anyway, so it's not a big deal.
+
 #![feature(const_trait_impl)]
 #![feature(io_error_more)]
 #![warn(clippy::indexing_slicing)]
@@ -22,9 +77,10 @@ pub use error::*;
 pub type Port = u16;
 pub type ConnectionId = u64;
 
-/// A per-connection HTTP request ID
-pub type RequestId = u16; // TODO: how many requests in a single connection? is u16 appropriate?
+/// An HTTP request ID, unique within a single incoming connection.
+pub type RequestId = u16;
 
+/// The version of this crate and the mirrord-protocol.
 pub static VERSION: LazyLock<semver::Version> = LazyLock::new(|| {
     env!("CARGO_PKG_VERSION")
         .parse()