rename the new pub type (requires moving the internal DTrace type wit…

…h the same name)

add demo test
fix up docs a bit

dropshot/src/dtrace.rs

@@ -0,0 +1,42 @@
+// Copyright 2023 Oxide Computer Company
+//! DTrace probes and support
+
+#[derive(Debug, Clone, serde::Serialize)]
+pub(crate) struct RequestInfo {
+    id: String,
+    local_addr: std::net::SocketAddr,
+    remote_addr: std::net::SocketAddr,
+    method: String,
+    path: String,
+    query: Option<String>,
+}
+
+#[derive(Debug, Clone, serde::Serialize)]
+pub(crate) struct ResponseInfo {
+    id: String,
+    local_addr: std::net::SocketAddr,
+    remote_addr: std::net::SocketAddr,
+    status_code: u16,
+    message: String,
+}
+
+#[cfg(feature = "usdt-probes")]
+#[usdt::provider(provider = "dropshot")]
+mod probes {
+    use super::{RequestInfo, ResponseInfo};
+    fn request__start(_: &RequestInfo) {}
+    fn request__done(_: &ResponseInfo) {}
+}
+
+/// The result of registering a server's DTrace USDT probes.
+#[derive(Debug, Clone, PartialEq)]
+pub enum ProbeRegistration {
+    /// The probes are explicitly disabled at compile time.
+    Disabled,
+
+    /// Probes were successfully registered.
+    Succeeded,
+
+    /// Registration failed, with an error message explaining the cause.
+    Failed(String),
+}

dropshot/src/extractor/mod.rs

@@ -31,7 +31,7 @@ use std::fmt::Debug;
 
 mod common;
 
-use crate::RequestHeader;
+use crate::RequestInfo;
 pub use common::ExclusiveExtractor;
 pub use common::ExtractorMetadata;
 pub use common::RequestExtractor;
@@ -58,7 +58,7 @@ impl<QueryType: DeserializeOwned + JsonSchema + Send + Sync> Query<QueryType> {
 /// Given an HTTP request, pull out the query string and attempt to deserialize
 /// it as an instance of `QueryType`.
 fn http_request_load_query<QueryType>(
-    request: &RequestHeader,
+    request: &RequestInfo,
 ) -> Result<Query<QueryType>, HttpError>
 where
     QueryType: DeserializeOwned + JsonSchema + Send + Sync,

dropshot/src/handler.rs

@@ -85,23 +85,22 @@ pub struct RequestContext<Context: ServerContext> {
     pub log: Logger,
 
     /// basic request information (method, URI, etc.)
-    pub request: RequestHeader,
+    pub request: RequestInfo,
 }
 
 // This is deliberately as close to compatible with `hyper::Request` as
 // reasonable.
-// XXX-dap TODO This could use a better name.
 #[derive(Debug)]
-pub struct RequestHeader {
+pub struct RequestInfo {
     method: http::Method,
     uri: http::Uri,
     version: http::Version,
     headers: http::HeaderMap<http::HeaderValue>,
 }
 
-impl<B> From<&hyper::Request<B>> for RequestHeader {
+impl<B> From<&hyper::Request<B>> for RequestInfo {
     fn from(request: &hyper::Request<B>) -> Self {
-        RequestHeader {
+        RequestInfo {
             method: request.method().clone(),
             uri: request.uri().clone(),
             version: request.version().clone(),
@@ -110,7 +109,7 @@ impl<B> From<&hyper::Request<B>> for RequestHeader {
     }
 }
 
-impl RequestHeader {
+impl RequestInfo {
     pub fn method(&self) -> &http::Method {
         &self.method
     }

dropshot/src/lib.rs

@@ -213,15 +213,16 @@
 //!      [path_params: Path<P>,]
 //!      [body_param: TypedBody<J>,]
 //!      [body_param: UntypedBody<J>,]
+//!      [raw_request: RawRequest,]
 //! ) -> Result<HttpResponse*, HttpError>
 //! ```
 //!
 //! The `RequestContext` must appear first.  The `Context` type is
 //! caller-provided context which is provided when the server is created.
 //!
-//! The types `Query`, `Path`, `TypedBody`, and `UntypedBody` are called
-//! **Extractors** because they cause information to be pulled out of the request
-//! and made available to the handler function.
+//! The types `Query`, `Path`, `TypedBody`, `UntypedBody`, and `RawRequest` are
+//! called **Extractors** because they cause information to be pulled out of the
+//! request and made available to the handler function.
 //!
 //! * [`Query`]`<Q>` extracts parameters from a query string, deserializing them
 //!   into an instance of type `Q`. `Q` must implement `serde::Deserialize` and
@@ -233,11 +234,14 @@
 //!   body as JSON (or form/url-encoded) and deserializing it into an instance
 //!   of type `J`. `J` must implement `serde::Deserialize` and `schemars::JsonSchema`.
 //! * [`UntypedBody`] extracts the raw bytes of the request body.
+//! * [`RawRequest`] provides access to the underlying [`hyper::Request`].  The
+//!   hope is that this would generally not be needed.  It can be useful to
+//!   implement functionality not provided by Dropshot.
 //!
-//! `Query` and `Path` impl `SharedExtractor`.  `TypedBody` and `UntypedBody`
-//! impl `ExclusiveExtractor`.  Your function may accept 0-3 extractors, but
-//! only one can be `ExclusiveExtractor`, and it must be the last one.
-//! Otherwise, the order of extractor arguments does not matter.
+//! `Query` and `Path` impl `SharedExtractor`.  `TypedBody`, `UntypedBody`, and
+//! `RawRequest` impl `ExclusiveExtractor`.  Your function may accept 0-3
+//! extractors, but only one can be `ExclusiveExtractor`, and it must be the
+//! last one.  Otherwise, the order of extractor arguments does not matter.
 //!
 //! If the handler accepts any extractors and the corresponding extraction
 //! cannot be completed, the request fails with status code 400 and an error
@@ -504,8 +508,8 @@
 //! Dropshot optionally exposes two DTrace probes, `request_start` and
 //! `request_finish`. These provide detailed information about each request,
 //! such as their ID, the local and remote IPs, and the response information.
-//! See the [`RequestInfo`] and [`ResponseInfo`] types for a complete listing
-//! of what's available.
+//! See the dropshot::dtrace::RequestInfo` and `dropshot::dtrae::ResponseInfo`
+//! types for a complete listing of what's available.
 //!
 //! These probes are implemented via the [`usdt`] crate. They may require a
 //! nightly toolchain if built on macOS prior to Rust version 1.66. Otherwise a
@@ -551,45 +555,9 @@
     feature(asm_sym)
 )]
 
-#[derive(Debug, Clone, serde::Serialize)]
-pub(crate) struct RequestInfo {
-    id: String,
-    local_addr: std::net::SocketAddr,
-    remote_addr: std::net::SocketAddr,
-    method: String,
-    path: String,
-    query: Option<String>,
-}
-
-#[derive(Debug, Clone, serde::Serialize)]
-pub(crate) struct ResponseInfo {
-    id: String,
-    local_addr: std::net::SocketAddr,
-    remote_addr: std::net::SocketAddr,
-    status_code: u16,
-    message: String,
-}
-
-#[cfg(feature = "usdt-probes")]
-#[usdt::provider(provider = "dropshot")]
-mod probes {
-    use crate::{RequestInfo, ResponseInfo};
-    fn request__start(_: &RequestInfo) {}
-    fn request__done(_: &ResponseInfo) {}
-}
-
-/// The result of registering a server's DTrace USDT probes.
-#[derive(Debug, Clone, PartialEq)]
-pub enum ProbeRegistration {
-    /// The probes are explicitly disabled at compile time.
-    Disabled,
-
-    /// Probes were successfully registered.
-    Succeeded,
-
-    /// Registration failed, with an error message explaining the cause.
-    Failed(String),
-}
+// The macro used to define DTrace probes needs to be defined before anything
+// that might use it.
+mod dtrace;
 
 mod api_description;
 mod config;
@@ -626,6 +594,7 @@ pub use api_description::TagDetails;
 pub use api_description::TagExternalDocs;
 pub use config::ConfigDropshot;
 pub use config::ConfigTls;
+pub use dtrace::ProbeRegistration;
 pub use error::HttpError;
 pub use error::HttpErrorResponseBody;
 pub use extractor::ExclusiveExtractor;
@@ -653,7 +622,7 @@ pub use handler::HttpResponseTemporaryRedirect;
 pub use handler::HttpResponseUpdatedNoContent;
 pub use handler::NoHeaders;
 pub use handler::RequestContext;
-pub use handler::RequestHeader;
+pub use handler::RequestInfo;
 pub use http_util::CONTENT_TYPE_JSON;
 pub use http_util::CONTENT_TYPE_NDJSON;
 pub use http_util::CONTENT_TYPE_OCTET_STREAM;

dropshot/src/server.rs

@@ -1,13 +1,13 @@
-// Copyright 2020 Oxide Computer Company
+// Copyright 2023 Oxide Computer Company
 //! Generic server-wide state and facilities
 
 use super::api_description::ApiDescription;
 use super::config::{ConfigDropshot, ConfigTls};
+#[cfg(feature = "usdt-probes")]
+use super::dtrace::probes;
 use super::error::HttpError;
 use super::handler::RequestContext;
 use super::http_util::HEADER_REQUEST_ID;
-#[cfg(feature = "usdt-probes")]
-use super::probes;
 use super::router::HttpRouter;
 use super::ProbeRegistration;
 
@@ -38,7 +38,7 @@ use tokio::net::{TcpListener, TcpStream};
 use tokio_rustls::{server::TlsStream, TlsAcceptor};
 use uuid::Uuid;
 
-use crate::RequestHeader;
+use crate::RequestInfo;
 use slog::Logger;
 
 // TODO Replace this with something else?
@@ -679,7 +679,7 @@ async fn http_request_handle_wrap<C: ServerContext>(
     #[cfg(feature = "usdt-probes")]
     probes::request__start!(|| {
         let uri = request.uri();
-        crate::RequestInfo {
+        crate::dtrace::RequestInfo {
             id: request_id.clone(),
             local_addr: server.local_addr,
             remote_addr,
@@ -710,7 +710,7 @@ async fn http_request_handle_wrap<C: ServerContext>(
 
             #[cfg(feature = "usdt-probes")]
             probes::request__done!(|| {
-                crate::ResponseInfo {
+                crate::dtrace::ResponseInfo {
                     id: request_id.clone(),
                     local_addr,
                     remote_addr,
@@ -771,7 +771,7 @@ async fn http_request_handle<C: ServerContext>(
         server.router.lookup_route(&method, uri.path().into())?;
     let rqctx = RequestContext {
         server: Arc::clone(&server),
-        request: RequestHeader::from(&request),
+        request: RequestInfo::from(&request),
         path_variables: lookup_result.variables,
         body_content_type: lookup_result.body_content_type,
         request_id: request_id.to_string(),

dropshot/src/websocket.rs

@@ -297,7 +297,7 @@ mod tests {
     use crate::router::HttpRouter;
     use crate::server::{DropshotState, ServerConfig};
     use crate::{
-        ExclusiveExtractor, HttpError, RequestContext, RequestHeader,
+        ExclusiveExtractor, HttpError, RequestContext, RequestInfo,
         WebsocketUpgrade,
     };
     use http::Request;
@@ -332,7 +332,7 @@ mod tests {
                 ),
                 tls_acceptor: None,
             }),
-            request: RequestHeader::from(&request),
+            request: RequestInfo::from(&request),
             path_variables: Default::default(),
             body_content_type: Default::default(),
             request_id: "".to_string(),

dropshot/tests/fail/bad_endpoint1.stderr

@@ -5,6 +5,7 @@ error: Endpoint handlers must have the following signature:
                [path_params: Path<P>,]
                [body_param: TypedBody<J>,]
                [body_param: UntypedBody<J>,]
+               [raw_request: RawRequest,]
            ) -> Result<HttpResponse*, HttpError>
   --> tests/fail/bad_endpoint1.rs:20:1
    |

dropshot/tests/fail/bad_endpoint11.stderr

@@ -5,6 +5,7 @@ error: Endpoint handlers must have the following signature:
                [path_params: Path<P>,]
                [body_param: TypedBody<J>,]
                [body_param: UntypedBody<J>,]
+               [raw_request: RawRequest,]
            ) -> Result<HttpResponse*, HttpError>
   --> tests/fail/bad_endpoint11.rs:13:1
    |

dropshot/tests/fail/bad_endpoint13.stderr

@@ -5,6 +5,7 @@ error: Endpoint handlers must have the following signature:
                [path_params: Path<P>,]
                [body_param: TypedBody<J>,]
                [body_param: UntypedBody<J>,]
+               [raw_request: RawRequest,]
            ) -> Result<HttpResponse*, HttpError>
   --> tests/fail/bad_endpoint13.rs:19:1
    |

dropshot/tests/fail/bad_endpoint2.stderr

@@ -5,6 +5,7 @@ error: Endpoint handlers must have the following signature:
                [path_params: Path<P>,]
                [body_param: TypedBody<J>,]
                [body_param: UntypedBody<J>,]
+               [raw_request: RawRequest,]
            ) -> Result<HttpResponse*, HttpError>
   --> tests/fail/bad_endpoint2.rs:13:1
    |

dropshot/tests/fail/bad_endpoint8.stderr

@@ -5,6 +5,7 @@ error: Endpoint handlers must have the following signature:
                [path_params: Path<P>,]
                [body_param: TypedBody<J>,]
                [body_param: UntypedBody<J>,]
+               [raw_request: RawRequest,]
            ) -> Result<HttpResponse*, HttpError>
   --> tests/fail/bad_endpoint8.rs:20:1
    |