diff --git a/proto/src/handshake/request.rs b/proto/src/handshake/request.rs index 9f6b9cb..51b6ad5 100644 --- a/proto/src/handshake/request.rs +++ b/proto/src/handshake/request.rs @@ -9,8 +9,8 @@ pub struct HandshakeRequest { impl HandshakeRequest { - /// Creates a new `HandshakeRequest` with the specified version. - /// Expected `version` is 196608 (3.0). + /// Creates a new `HandshakeRequest` with the specified protocol version. + /// Expected `version` is `196608` for the 3.0. pub fn new(version: i32) -> Self { Self { version, diff --git a/proto/src/lib.rs b/proto/src/lib.rs index 4395510..e9d155d 100644 --- a/proto/src/lib.rs +++ b/proto/src/lib.rs @@ -1,5 +1,5 @@ -//! # PostgreSQL 16 Protocol -//! Low-level PostgreSQL protocol implementation for the version 16, protocol version 3.0. +//! # PostgreSQL Protocol +//! Low-level PostgreSQL protocol implementation for the server version 16, protocol version 3.0. //! Includes server and client side handshake with no password authentication. pub mod handshake; diff --git a/proto/src/message/backend.rs b/proto/src/message/backend.rs index 0aa0e20..869fe14 100644 --- a/proto/src/message/backend.rs +++ b/proto/src/message/backend.rs @@ -5,6 +5,8 @@ use crate::message::primitive::pgstring::PgString; use crate::message::proto_message::ProtoMessage; use bincode::{Decode, Encode}; +/// Backend messages sent from the server to the client. +/// For more info visit the [`55.2.3. Message Formats`](https://www.postgresql.org/docs/current/protocol-message-formats.html) #[derive(Debug)] pub enum BackendMessage { AuthenticationOk(AuthenticationOkData), diff --git a/proto/src/message/frontend.rs b/proto/src/message/frontend.rs index 178be7b..648938e 100644 --- a/proto/src/message/frontend.rs +++ b/proto/src/message/frontend.rs @@ -4,6 +4,8 @@ use crate::message::primitive::pgstring::PgString; use crate::message::proto_message::ProtoMessage; use bincode::{Decode, Encode}; +/// Frontend messages sent from the client to the server. +/// For more info visit the [`55.2.3. Message Formats`](https://www.postgresql.org/docs/current/protocol-message-formats.html) #[derive(Debug)] pub enum FrontendMessage { Query(QueryData), diff --git a/proto/src/message/primitive/config.rs b/proto/src/message/primitive/config.rs deleted file mode 100644 index 5aa74f5..0000000 --- a/proto/src/message/primitive/config.rs +++ /dev/null @@ -1,7 +0,0 @@ -use bincode::config::{BigEndian, Configuration, Fixint}; - -pub fn pg_proto_config() -> Configuration { - bincode::config::standard() - .with_big_endian() - .with_fixed_int_encoding() -} diff --git a/proto/src/message/primitive/data.rs b/proto/src/message/primitive/data.rs index 4df50ae..db19ad4 100644 --- a/proto/src/message/primitive/data.rs +++ b/proto/src/message/primitive/data.rs @@ -1,6 +1,12 @@ use crate::message::errors::{ProtoDeserializeError, ProtoSerializeError}; -use crate::message::primitive::config::pg_proto_config; use bincode::{Decode, Encode}; +use bincode::config::{BigEndian, Configuration, Fixint}; + +fn pg_proto_config() -> Configuration { + bincode::config::standard() + .with_big_endian() + .with_fixed_int_encoding() +} pub trait MessageData: Sized { fn serialize(&self) -> Result, ProtoSerializeError>; diff --git a/proto/src/message/primitive/mod.rs b/proto/src/message/primitive/mod.rs index e275e6e..4e84a1b 100644 --- a/proto/src/message/primitive/mod.rs +++ b/proto/src/message/primitive/mod.rs @@ -1,4 +1,3 @@ -pub(crate) mod config; pub(crate) mod data; pub mod pglist; pub mod pgstring; diff --git a/proto/src/message/primitive/pglist.rs b/proto/src/message/primitive/pglist.rs index aa95ca2..1e76db3 100644 --- a/proto/src/message/primitive/pglist.rs +++ b/proto/src/message/primitive/pglist.rs @@ -4,6 +4,9 @@ use bincode::error::{DecodeError, EncodeError}; use bincode::{BorrowDecode, Decode, Encode}; use std::marker::PhantomData; +/// Item list common in PostgreSQL messages. +/// - Generic type `T` is the type of the items in the list. +/// - Generic type `U` is the type of the list length (`i16` or `i32`). #[derive(Debug, Clone, PartialEq, BorrowDecode)] pub struct PgList(Vec, PhantomData); diff --git a/proto/src/message/primitive/pgstring.rs b/proto/src/message/primitive/pgstring.rs index 2c6cd7b..58fad78 100644 --- a/proto/src/message/primitive/pgstring.rs +++ b/proto/src/message/primitive/pgstring.rs @@ -4,6 +4,7 @@ use bincode::enc::Encoder; use bincode::error::{DecodeError, EncodeError}; use bincode::{BorrowDecode, Decode, Encode}; +/// PostgreSQL format of string encoded as a null-terminated string. #[derive(Debug, Clone, BorrowDecode)] pub struct PgString(String); diff --git a/proto/src/message/special.rs b/proto/src/message/special.rs index 166320f..6c45ab9 100644 --- a/proto/src/message/special.rs +++ b/proto/src/message/special.rs @@ -4,10 +4,15 @@ use bincode::enc::Encoder; use bincode::error::{DecodeError, EncodeError}; use bincode::{Decode, Encode}; +/// Special messages sent during handshake or to cancel request. +/// Sent in different format to preserve compatibility with older protocol versions. #[derive(Debug)] pub enum SpecialMessage { + /// Sent by client to cancel request. CancelRequest(CancelRequestData), + /// Sent by client to request upgrade to SSL connection. SSLRequest, + /// Sent by client to initiate the handshake. StartupMessage(StartupMessageData), }