From 20143ba0cf08a25dd0aecb9c7e6e192e3c91cf70 Mon Sep 17 00:00:00 2001 From: Lucio Franco Date: Wed, 4 Sep 2019 18:41:39 -0400 Subject: [PATCH] Add more warnings and clean up --- tonic/src/body.rs | 19 ++++++++++++++++++- tonic/src/client/grpc.rs | 2 +- tonic/src/codec/decode.rs | 8 +++++++- tonic/src/codec/encode.rs | 6 +++--- tonic/src/lib.rs | 7 ++++++- tonic/src/metadata/encoding.rs | 2 ++ tonic/src/metadata/key.rs | 3 +++ tonic/src/metadata/map.rs | 16 +++++++++++++--- tonic/src/metadata/value.rs | 2 ++ tonic/src/request.rs | 3 ++- tonic/src/response.rs | 4 +++- tonic/src/server/grpc.rs | 4 ++-- tonic/src/status.rs | 1 + tonic/src/transport/channel.rs | 2 +- tonic/src/transport/mod.rs | 9 ++++++--- tonic/src/transport/server.rs | 4 ++-- tonic/src/transport/service/add_origin.rs | 4 ++-- tonic/src/transport/service/boxed.rs | 4 ++-- tonic/src/transport/service/connect.rs | 4 ++-- tonic/src/transport/service/connector.rs | 4 ++-- tonic/src/transport/service/io.rs | 2 +- tonic/src/transport/service/mod.rs | 11 ++++++----- tonic/src/transport/tls/mod.rs | 14 +++++++------- tonic/src/transport/tls/openssl.rs | 14 +++++++------- 24 files changed, 101 insertions(+), 48 deletions(-) diff --git a/tonic/src/body.rs b/tonic/src/body.rs index d04848f..d24c6b2 100644 --- a/tonic/src/body.rs +++ b/tonic/src/body.rs @@ -1,3 +1,8 @@ +//! HTTP specific body utilities. +//! +//! This module contains traits and helper types to work with http bodies. Most +//! of the types in this module are based around [`http_body::Body`]. + use crate::{Error, Status}; use bytes::{Buf, Bytes, IntoBuf}; use http_body::Body as HttpBody; @@ -9,17 +14,29 @@ use std::{ pub(crate) type BytesBuf = ::Buf; +/// A trait alias for [`http_body::Body`]. pub trait Body: sealed::Sealed { + /// The body data type. type Data: Buf; + /// The errors produced from the body. type Error: Into; + /// Check if the stream is over or not. + /// + /// Reference [`http_body::Body::is_end_stream`]. fn is_end_stream(&self) -> bool; + /// Poll for more data from the body. + /// + /// Reference [`http_body::Body::poll_data`]. fn poll_data( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll>>; + /// Poll for the trailing headers. + /// + /// Reference [`http_body::Body::poll_trailers`]. fn poll_trailers( self: Pin<&mut Self>, cx: &mut Context<'_>, @@ -164,7 +181,7 @@ where } impl fmt::Debug for BoxBody { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("BoxBody").finish() } } diff --git a/tonic/src/client/grpc.rs b/tonic/src/client/grpc.rs index 4f7b64b..f498796 100644 --- a/tonic/src/client/grpc.rs +++ b/tonic/src/client/grpc.rs @@ -203,7 +203,7 @@ impl Clone for Grpc { } impl fmt::Debug for Grpc { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("Grpc").finish() } } diff --git a/tonic/src/codec/decode.rs b/tonic/src/codec/decode.rs index b996d85..87f1784 100644 --- a/tonic/src/codec/decode.rs +++ b/tonic/src/codec/decode.rs @@ -90,10 +90,16 @@ impl Streaming { } impl Streaming { + /// Fetch the next message from this stream. pub async fn message(&mut self) -> Option> { future::poll_fn(|cx| Pin::new(&mut *self).poll_next(cx)).await } + /// Fetch the trailing metadata. + /// + /// This will drain the stream of all its messages to recieve the trailing + /// metadata. If [`Streaming::message`] returns `None` then this function + /// will not need to poll for trailers since the body was totally consumed. pub async fn trailers(&mut self) -> Result, Status> { // Shortcut to see if we already pulled the trailers in the stream step // we need to do that so that the stream can error on trailing grpc-status @@ -243,7 +249,7 @@ impl Stream for Streaming { } impl fmt::Debug for Streaming { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("Streaming").finish() } } diff --git a/tonic/src/codec/encode.rs b/tonic/src/codec/encode.rs index be32eaa..5029334 100644 --- a/tonic/src/codec/encode.rs +++ b/tonic/src/codec/encode.rs @@ -9,7 +9,7 @@ use std::pin::Pin; use std::task::{Context, Poll}; use tokio_codec::Encoder; -pub fn encode_server( +pub(crate) fn encode_server( encoder: T, source: U, ) -> EncodeBody>> @@ -21,7 +21,7 @@ where EncodeBody::new_server(stream) } -pub fn encode_client( +pub(crate) fn encode_client( encoder: T, source: U, ) -> EncodeBody>> @@ -77,7 +77,7 @@ enum Role { #[pin_project] #[derive(Debug)] -pub struct EncodeBody { +pub(crate) struct EncodeBody { #[pin] inner: S, error: Option, diff --git a/tonic/src/lib.rs b/tonic/src/lib.rs index ce14853..d7776ed 100644 --- a/tonic/src/lib.rs +++ b/tonic/src/lib.rs @@ -1,5 +1,10 @@ #![recursion_limit = "512"] -#![warn(missing_debug_implementations)] +#![warn( + missing_debug_implementations, + missing_docs, + rust_2018_idioms, + unreachable_pub +)] //! gRPC implementation diff --git a/tonic/src/metadata/encoding.rs b/tonic/src/metadata/encoding.rs index f954cc4..41bbb40 100644 --- a/tonic/src/metadata/encoding.rs +++ b/tonic/src/metadata/encoding.rs @@ -52,8 +52,10 @@ pub trait ValueEncoding: Clone + Eq + PartialEq + Hash + self::value_encoding::S } #[derive(Clone, Debug, Eq, PartialEq, Hash)] +#[doc(hidden)] pub enum Ascii {} #[derive(Clone, Debug, Eq, PartialEq, Hash)] +#[doc(hidden)] pub enum Binary {} // ===== impl ValueEncoding ===== diff --git a/tonic/src/metadata/key.rs b/tonic/src/metadata/key.rs index 14a076a..3fe0b68 100644 --- a/tonic/src/metadata/key.rs +++ b/tonic/src/metadata/key.rs @@ -28,7 +28,9 @@ pub struct InvalidMetadataKey { _priv: (), } +/// An ascii metadata key. pub type AsciiMetadataKey = MetadataKey; +/// A binary metadata key. pub type BinaryMetadataKey = MetadataKey; impl MetadataKey { @@ -175,6 +177,7 @@ impl fmt::Display for MetadataKey { } impl InvalidMetadataKey { + #[doc(hidden)] pub fn new() -> InvalidMetadataKey { InvalidMetadataKey { _priv: () } } diff --git a/tonic/src/metadata/map.rs b/tonic/src/metadata/map.rs index cab445d..b14baa9 100644 --- a/tonic/src/metadata/map.rs +++ b/tonic/src/metadata/map.rs @@ -1,6 +1,6 @@ -pub use self::as_encoding_agnostic_metadata_key::AsEncodingAgnosticMetadataKey; -pub use self::as_metadata_key::AsMetadataKey; -pub use self::into_metadata_key::IntoMetadataKey; +pub(crate) use self::as_encoding_agnostic_metadata_key::AsEncodingAgnosticMetadataKey; +pub(crate) use self::as_metadata_key::AsMetadataKey; +pub(crate) use self::into_metadata_key::IntoMetadataKey; use super::encoding::{Ascii, Binary, ValueEncoding}; use super::key::{InvalidMetadataKey, MetadataKey}; @@ -49,7 +49,9 @@ pub struct Iter<'a> { /// to either an ascii or a binary ("*-bin") key. #[derive(Debug)] pub enum KeyAndValueRef<'a> { + /// An ascii metadata key and value. Ascii(&'a MetadataKey, &'a MetadataValue), + /// A binary metadata key and value. Binary(&'a MetadataKey, &'a MetadataValue), } @@ -57,7 +59,9 @@ pub enum KeyAndValueRef<'a> { /// to either an ascii or a binary ("*-bin") key. #[derive(Debug)] pub enum KeyAndMutValueRef<'a> { + /// An ascii metadata key and value. Ascii(&'a MetadataKey, &'a mut MetadataValue), + /// A binary metadata key and value. Binary(&'a MetadataKey, &'a mut MetadataValue), } @@ -90,7 +94,9 @@ pub struct Keys<'a> { /// to either an ascii or a binary ("*-bin") key. #[derive(Debug)] pub enum KeyRef<'a> { + /// An ascii metadata key and value. Ascii(&'a MetadataKey), + /// A binary metadata key and value. Binary(&'a MetadataKey), } @@ -109,7 +115,9 @@ pub struct Values<'a> { /// to either an ascii or a binary ("*-bin" key) value. #[derive(Debug)] pub enum ValueRef<'a> { + /// An ascii metadata key and value. Ascii(&'a MetadataValue), + /// A binary metadata key and value. Binary(&'a MetadataValue), } @@ -127,7 +135,9 @@ pub struct ValuesMut<'a> { /// to either an ascii or a binary ("*-bin" key) value. #[derive(Debug)] pub enum ValueRefMut<'a> { + /// An ascii metadata key and value. Ascii(&'a mut MetadataValue), + /// A binary metadata key and value. Binary(&'a mut MetadataValue), } diff --git a/tonic/src/metadata/value.rs b/tonic/src/metadata/value.rs index a58af1b..072003e 100644 --- a/tonic/src/metadata/value.rs +++ b/tonic/src/metadata/value.rs @@ -33,7 +33,9 @@ pub struct ToStrError { _priv: (), } +/// An ascii metadata value. pub type AsciiMetadataValue = MetadataValue; +/// A binary metadata value. pub type BinaryMetadataValue = MetadataValue; impl MetadataValue { diff --git a/tonic/src/request.rs b/tonic/src/request.rs index b603db4..a73a790 100644 --- a/tonic/src/request.rs +++ b/tonic/src/request.rs @@ -54,7 +54,7 @@ impl Request { Request::from_http_parts(parts, message) } - pub fn into_http(self, uri: http::Uri) -> http::Request { + pub(crate) fn into_http(self, uri: http::Uri) -> http::Request { let mut request = http::Request::new(self.message); *request.version_mut() = http::Version::HTTP_2; @@ -65,6 +65,7 @@ impl Request { request } + #[doc(hidden)] pub fn map(self, f: F) -> Request where F: FnOnce(T) -> U, diff --git a/tonic/src/response.rs b/tonic/src/response.rs index e6579d6..b30b895 100644 --- a/tonic/src/response.rs +++ b/tonic/src/response.rs @@ -16,6 +16,7 @@ impl Response { } } + /// Get a immutable reference to `T`. pub fn get_ref(&self) -> &T { &self.message } @@ -56,7 +57,7 @@ impl Response { } } - pub fn into_http(self) -> http::Response { + pub(crate) fn into_http(self) -> http::Response { let mut res = http::Response::new(self.message); *res.version_mut() = http::Version::HTTP_2; @@ -65,6 +66,7 @@ impl Response { res } + #[doc(hidden)] pub fn map(self, f: F) -> Response where F: FnOnce(T) -> U, diff --git a/tonic/src/server/grpc.rs b/tonic/src/server/grpc.rs index f5c11eb..b7c5306 100644 --- a/tonic/src/server/grpc.rs +++ b/tonic/src/server/grpc.rs @@ -61,7 +61,7 @@ where self.map_response(response) } - // Handle a server side streaming request. + /// Handle a server side streaming request. pub async fn server_streaming( &mut self, mut service: S, @@ -202,7 +202,7 @@ where } impl fmt::Debug for Grpc { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("Grpc").finish() } } diff --git a/tonic/src/status.rs b/tonic/src/status.rs index a6f63cb..55da063 100644 --- a/tonic/src/status.rs +++ b/tonic/src/status.rs @@ -21,6 +21,7 @@ pub struct Status { /// gRPC status codes used by `Status`. #[derive(Clone, Copy, Debug, PartialEq, Eq)] +#[allow(missing_docs)] pub enum Code { Ok = 0, Cancelled = 1, diff --git a/tonic/src/transport/channel.rs b/tonic/src/transport/channel.rs index e7df044..01aab5c 100644 --- a/tonic/src/transport/channel.rs +++ b/tonic/src/transport/channel.rs @@ -119,7 +119,7 @@ impl Builder { } impl fmt::Debug for Channel { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("Channel").finish() } } diff --git a/tonic/src/transport/mod.rs b/tonic/src/transport/mod.rs index 5f68d99..b0bbf23 100644 --- a/tonic/src/transport/mod.rs +++ b/tonic/src/transport/mod.rs @@ -1,3 +1,6 @@ +// TODO: write transport docs. +#![allow(missing_docs)] + mod channel; mod endpoint; mod server; @@ -40,7 +43,7 @@ impl From<(ErrorKind, crate::Error)> for Error { } impl fmt::Debug for Error { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { let mut f = f.debug_tuple("Error"); f.field(&self.kind); if let Some(source) = &self.source { @@ -51,7 +54,7 @@ impl fmt::Debug for Error { } impl fmt::Display for Error { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { if let Some(source) = &self.source { write!(f, "{}: {}", self.kind, source) } else { @@ -69,7 +72,7 @@ impl error::Error for Error { } impl fmt::Display for ErrorKind { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!(f, "{:?}", self) } } diff --git a/tonic/src/transport/server.rs b/tonic/src/transport/server.rs index ce3a029..dca6eea 100644 --- a/tonic/src/transport/server.rs +++ b/tonic/src/transport/server.rs @@ -94,7 +94,7 @@ fn incoming( // TODO: add custom tracing here #[derive(Debug)] -pub struct Svc(S); +pub(crate) struct Svc(S); impl Service> for Svc where @@ -113,7 +113,7 @@ where } } -pub struct MakeSvc(M); +pub(crate) struct MakeSvc(M); impl Service for MakeSvc where diff --git a/tonic/src/transport/service/add_origin.rs b/tonic/src/transport/service/add_origin.rs index 0f3b6dd..7c7df74 100644 --- a/tonic/src/transport/service/add_origin.rs +++ b/tonic/src/transport/service/add_origin.rs @@ -3,13 +3,13 @@ use std::task::{Context, Poll}; use tower_service::Service; #[derive(Debug)] -pub struct AddOrigin { +pub(crate) struct AddOrigin { inner: T, origin: Uri, } impl AddOrigin { - pub fn new(inner: T, origin: Uri) -> Self { + pub(crate) fn new(inner: T, origin: Uri) -> Self { Self { inner, origin } } } diff --git a/tonic/src/transport/service/boxed.rs b/tonic/src/transport/service/boxed.rs index f32e174..67e9a7b 100644 --- a/tonic/src/transport/service/boxed.rs +++ b/tonic/src/transport/service/boxed.rs @@ -6,12 +6,12 @@ use std::{ use tower_service::Service; #[derive(Debug, Clone)] -pub struct BoxService { +pub(crate) struct BoxService { inner: S, } impl BoxService { - pub fn new(inner: S) -> Self { + pub(crate) fn new(inner: S) -> Self { Self { inner } } } diff --git a/tonic/src/transport/service/connect.rs b/tonic/src/transport/service/connect.rs index 67d8072..ca160c5 100644 --- a/tonic/src/transport/service/connect.rs +++ b/tonic/src/transport/service/connect.rs @@ -1,4 +1,4 @@ -use super::{add_origin::AddOrigin, connector::Connector}; +use super::{AddOrigin, Connector}; use crate::{transport::Endpoint, BoxBody}; use http::{Request, Response, Uri}; use hyper::client::conn::Builder; @@ -56,7 +56,7 @@ impl Load for Connection { } impl fmt::Debug for Connection { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("Connection").finish() } } diff --git a/tonic/src/transport/service/connector.rs b/tonic/src/transport/service/connector.rs index 5135ba1..57b5539 100644 --- a/tonic/src/transport/service/connector.rs +++ b/tonic/src/transport/service/connector.rs @@ -10,13 +10,13 @@ use tower_service::Service; type ConnectFuture = >::Future; -pub struct Connector { +pub(crate) struct Connector { http: HttpConnector, tls: Option, } impl Connector { - pub fn new(cert: Option) -> Result { + pub(crate) fn new(cert: Option) -> Result { let mut http = HttpConnector::new(); http.enforce_http(false); diff --git a/tonic/src/transport/service/io.rs b/tonic/src/transport/service/io.rs index 6c8f3aa..b6ba752 100644 --- a/tonic/src/transport/service/io.rs +++ b/tonic/src/transport/service/io.rs @@ -10,7 +10,7 @@ pub(in crate::transport) trait Io: impl Io for T where T: AsyncRead + AsyncWrite + Send + Unpin + 'static {} -pub struct BoxedIo(Pin>); +pub(crate) struct BoxedIo(Pin>); impl BoxedIo { pub(in crate::transport) fn new(io: I) -> Self { diff --git a/tonic/src/transport/service/mod.rs b/tonic/src/transport/service/mod.rs index fccba24..b730bc3 100644 --- a/tonic/src/transport/service/mod.rs +++ b/tonic/src/transport/service/mod.rs @@ -5,8 +5,9 @@ mod connector; mod discover; mod io; -pub use self::add_origin::AddOrigin; -pub use self::boxed::BoxService; -pub use self::connect::Connection; -pub use self::discover::ServiceList; -pub use self::io::BoxedIo; +pub(crate) use self::add_origin::AddOrigin; +pub(crate) use self::boxed::BoxService; +pub(crate) use self::connect::Connection; +pub(crate) use self::connector::Connector; +pub(crate) use self::discover::ServiceList; +pub(crate) use self::io::BoxedIo; diff --git a/tonic/src/transport/tls/mod.rs b/tonic/src/transport/tls/mod.rs index 454fb06..489adf2 100644 --- a/tonic/src/transport/tls/mod.rs +++ b/tonic/src/transport/tls/mod.rs @@ -12,40 +12,40 @@ mod imp; use tokio::net::TcpStream; #[derive(Debug, Clone)] -pub struct Cert { +pub(crate) struct Cert { pub(crate) ca: Vec, pub(crate) key: Option>, pub(crate) domain: String, } #[derive(Clone)] -pub struct TlsConnector { +pub(crate) struct TlsConnector { inner: imp::TlsConnector, } impl TlsConnector { - pub fn new(cert: Cert) -> Result { + pub(crate) fn new(cert: Cert) -> Result { let inner = imp::TlsConnector::new(cert)?; Ok(Self { inner }) } - pub async fn connect(&self, io: TcpStream) -> Result { + pub(crate) async fn connect(&self, io: TcpStream) -> Result { self.inner.connect(io).await } } #[derive(Clone)] -pub struct TlsAcceptor { +pub(crate) struct TlsAcceptor { inner: imp::TlsAcceptor, } impl TlsAcceptor { - pub fn new(cert: Cert) -> Result { + pub(crate) fn new(cert: Cert) -> Result { let inner = imp::TlsAcceptor::new(cert)?; Ok(Self { inner }) } - pub async fn connect(&self, io: TcpStream) -> Result { + pub(crate) async fn connect(&self, io: TcpStream) -> Result { self.inner.connect(io).await } } diff --git a/tonic/src/transport/tls/openssl.rs b/tonic/src/transport/tls/openssl.rs index e34c799..449e72f 100644 --- a/tonic/src/transport/tls/openssl.rs +++ b/tonic/src/transport/tls/openssl.rs @@ -7,16 +7,16 @@ use tokio_openssl::SslStream; const ALPN_H2: &[u8] = b"\x02h2"; -pub type TlsStream = SslStream; +pub(crate) type TlsStream = SslStream; #[derive(Clone)] -pub struct TlsConnector { +pub(crate) struct TlsConnector { config: SslConnector, domain: Arc, } impl TlsConnector { - pub fn new(cert: Cert) -> Result { + pub(crate) fn new(cert: Cert) -> Result { let Cert { ca, domain, .. } = cert; let mut config = SslConnector::builder(SslMethod::tls()).unwrap(); @@ -34,7 +34,7 @@ impl TlsConnector { }) } - pub async fn connect(&self, io: TcpStream) -> Result { + pub(crate) async fn connect(&self, io: TcpStream) -> Result { let config = self.config.configure()?; let tls = tokio_openssl::connect(config, &self.domain, io).await?; Ok(tls) @@ -42,12 +42,12 @@ impl TlsConnector { } #[derive(Clone)] -pub struct TlsAcceptor { +pub(crate) struct TlsAcceptor { config: SslAcceptor, } impl TlsAcceptor { - pub fn new(cert: Cert) -> Result { + pub(crate) fn new(cert: Cert) -> Result { let Cert { ca, key, .. } = cert; let key = PKey::private_key_from_pem(&key.unwrap()[..])?; @@ -64,7 +64,7 @@ impl TlsAcceptor { }) } - pub async fn connect(&self, io: TcpStream) -> Result { + pub(crate) async fn connect(&self, io: TcpStream) -> Result { let config = self.config.clone(); let tls = tokio_openssl::accept(&config, io).await?; Ok(tls)