Update comments on digest functions

5 files changed, 16 insertions, 11 deletions

diff --git a/.bleep b/.bleep
index 10944e6..0a99fe9 100644
--- a/.bleep
+++ b/.bleep
@@ -1 +1 @@
-04ff13f360fd33f2a508a47df6fbd2f6ca95ac89
\ No newline at end of file
+e91e896243a80fdbac73b5663224459a6e8d1db5
\ No newline at end of file
diff --git a/pingora-core/src/protocols/http/client.rs b/pingora-core/src/protocols/http/client.rs
index af7a614..4d3044d 100644
--- a/pingora-core/src/protocols/http/client.rs
+++ b/pingora-core/src/protocols/http/client.rs
@@ -153,7 +153,7 @@ impl HttpSession {
     /// Return the [Digest] of the connection
     ///
     /// For reused connection, the timing in the digest will reflect its initial handshakes
-    /// The caller should check if the connection is reused to avoid misuse of the timing field
+    /// The caller should check if the connection is reused to avoid misuse of the timing field.
     pub fn digest(&self) -> Option<&Digest> {
         match self {
             Self::H1(s) => Some(s.digest()),
@@ -161,10 +161,9 @@ impl HttpSession {
         }
     }
 
-    /// Return a mutable [Digest] reference for the connection
+    /// Return a mutable [Digest] reference for the connection, see [`digest`] for more details.
     ///
-    /// For reused connection, the timing in the digest will reflect its initial handshakes
-    /// The caller should check if the connection is reused to avoid misuse of the timing field
+    /// Will return `None` if this is an H2 session and multiple streams are open.
     pub fn digest_mut(&mut self) -> Option<&mut Digest> {
         match self {
             Self::H1(s) => Some(s.digest_mut()),
diff --git a/pingora-core/src/protocols/http/server.rs b/pingora-core/src/protocols/http/server.rs
index 6e702b1..c6479e7 100644
--- a/pingora-core/src/protocols/http/server.rs
+++ b/pingora-core/src/protocols/http/server.rs
@@ -387,7 +387,7 @@ impl Session {
         }
     }
 
-    /// Return the digest for the session.
+    /// Return the [Digest] for the connection.
     pub fn digest(&self) -> Option<&Digest> {
         match self {
             Self::H1(s) => Some(s.digest()),
@@ -395,7 +395,9 @@ impl Session {
         }
     }
 
-    /// Return a mutable digest reference for the session.
+    /// Return a mutable [Digest] reference for the connection.
+    ///
+    /// Will return `None` if multiple H2 streams are open.
     pub fn digest_mut(&mut self) -> Option<&mut Digest> {
         match self {
             Self::H1(s) => Some(s.digest_mut()),
diff --git a/pingora-core/src/protocols/http/v1/client.rs b/pingora-core/src/protocols/http/v1/client.rs
index c567d78..8c2ab14 100644
--- a/pingora-core/src/protocols/http/v1/client.rs
+++ b/pingora-core/src/protocols/http/v1/client.rs
@@ -631,10 +631,15 @@ impl HttpSession {
         // TODO: support h1 trailer
     }
 
+    /// Return the [Digest] of the connection
+    ///
+    /// For reused connection, the timing in the digest will reflect its initial handshakes
+    /// The caller should check if the connection is reused to avoid misuse the timing field.
     pub fn digest(&self) -> &Digest {
         &self.digest
     }
 
+    /// Return a mutable [Digest] reference for the connection, see [`digest`] for more details.
     pub fn digest_mut(&mut self) -> &mut Digest {
         &mut self.digest
     }
diff --git a/pingora-core/src/protocols/http/v2/client.rs b/pingora-core/src/protocols/http/v2/client.rs
index c639165..86a3fe3 100644
--- a/pingora-core/src/protocols/http/v2/client.rs
+++ b/pingora-core/src/protocols/http/v2/client.rs
@@ -305,15 +305,14 @@ impl Http2Session {
     /// Return the [Digest] of the connection
     ///
     /// For reused connection, the timing in the digest will reflect its initial handshakes
-    /// The caller should check if the connection is reused to avoid misuse the timing field
+    /// The caller should check if the connection is reused to avoid misuse the timing field.
     pub fn digest(&self) -> Option<&Digest> {
         Some(self.conn.digest())
     }
 
-    /// Return a mutable [Digest] reference for the connection
+    /// Return a mutable [Digest] reference for the connection, see [`digest`] for more details.
     ///
-    /// For reused connection, the timing in the digest will reflect its initial handshakes
-    /// The caller should check if the connection is reused to avoid misuse the timing field
+    /// Will return `None` if multiple H2 streams are open.
     pub fn digest_mut(&mut self) -> Option<&mut Digest> {
         self.conn.digest_mut()
     }