From d3fd0d4cdbcfb5803bd9876fa8b58ca02cc95d34 Mon Sep 17 00:00:00 2001
From: pmendes <pmendes@cloudflare.com>
Date: Tue, 15 Oct 2024 12:48:48 +0100
Subject: [PATCH] Document extractors and related types

---
 crates/daphne-server/src/router/extractor.rs | 23 +++++++++++++++++++-
 crates/daphne/src/messages/request.rs        |  7 ++++++
 2 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/crates/daphne-server/src/router/extractor.rs b/crates/daphne-server/src/router/extractor.rs
index 399c27bc..48ec4502 100644
--- a/crates/daphne-server/src/router/extractor.rs
+++ b/crates/daphne-server/src/router/extractor.rs
@@ -24,6 +24,7 @@ use serde::Deserialize;
 
 use super::{AxumDapResponse, DaphneService};
 
+/// Trait used to decode a DAP http body.
 pub trait DecodeFromDapHttpBody: Sized {
     fn decode_from_http_body(bytes: Bytes, meta: &DapRequestMeta) -> Result<Self, DapAbort>;
 }
@@ -37,7 +38,9 @@ macro_rules! impl_decode_from_dap_http_body {
                     meta: &DapRequestMeta,
                 ) -> Result<Self, DapAbort> {
                     let mut cursor = Cursor::new(bytes.as_ref());
+                    // check that media type matches.
                     meta.get_checked_media_type(DapMediaType::$type)?;
+                    // decode the body
                     $type::decode_with_param(&meta.version, &mut cursor)
                         .map_err(|e| DapAbort::from_codec_error(e, meta.task_id))
                 }
@@ -53,29 +56,42 @@ impl_decode_from_dap_http_body!(
     CollectionReq,
 );
 
+/// Using `()` ignores the body of a request.
 impl DecodeFromDapHttpBody for () {
     fn decode_from_http_body(_bytes: Bytes, _meta: &DapRequestMeta) -> Result<Self, DapAbort> {
         Ok(())
     }
 }
 
+/// Parsers that allow us to have to deduce the resource parser to use based on the resource passed
+/// in through the `R` type parameter in [`DapRequestExtractor`] and
+/// [`UnauthenticatedDapRequestExtractor`].
 mod resource_parsers {
     use daphne::messages::request::resource;
     use serde::{de::DeserializeOwned, Deserialize};
 
     #[derive(Deserialize)]
     pub struct AggregationJobIdParser {
+        /// this field name defines the parameter name in the route matcher because we use
+        /// `#[serde(flatten)]` in the
+        /// `UnauthenticatedDapRequestExtractor::from_request::PathParams::resource_parser` field.
         agg_job_id: resource::AggregationJobId,
     }
 
     #[derive(Deserialize)]
     pub struct CollectionJobIdParser {
+        /// this field name defines the parameter name in the route matcher because we use
+        /// `#[serde(flatten)]` in the
+        /// `UnauthenticatedDapRequestExtractor::from_request::PathParams::resource_parser` field.
         collect_job_id: resource::CollectionJobId,
     }
 
+    /// This parser has no fields, so `#[serde(flatten)]` correctly omits this field from the
+    /// fields it requires.
     #[derive(Deserialize)]
     pub struct NoneParser;
 
+    /// Trait that lets us go from resource to resource parser.
     pub trait Resource: Sized + Send + Sync {
         type Parser: Into<Self> + Send + Sync + DeserializeOwned;
     }
@@ -99,7 +115,8 @@ mod resource_parsers {
     impl_parser!(NoneParser             => resource::None             |_| resource::None);
 }
 
-/// An axum extractor capable of parsing a [`DapRequest`].
+/// An axum extractor capable of parsing a [`DapRequest`]. See [`DapRequest`] for an explanation on
+/// the type parameters.
 #[derive(Debug)]
 pub(super) struct UnauthenticatedDapRequestExtractor<P, R>(pub DapRequest<P, R>);
 
@@ -208,6 +225,10 @@ pub mod dap_sender {
 /// An axum extractor capable of parsing a [`DapRequest`].
 ///
 /// This extractor asserts that the request is authenticated.
+///
+/// # Type and const parameters
+/// - `SENDER`: The role that is expected to send this request. See [`dap_sender`] for possible values.
+/// - `P` and `R`: See [`DapRequest`] for an explanation these type parameters.
 #[derive(Debug)]
 pub(super) struct DapRequestExtractor<const SENDER: dap_sender::DapSender, P, R = resource::None>(
     pub DapRequest<P, R>,
diff --git a/crates/daphne/src/messages/request.rs b/crates/daphne/src/messages/request.rs
index 6929dac7..0b507c16 100644
--- a/crates/daphne/src/messages/request.rs
+++ b/crates/daphne/src/messages/request.rs
@@ -49,6 +49,13 @@ impl DapRequestMeta {
 }
 
 /// DAP request.
+///
+/// # Type parameters
+/// - `P`: is the payload of the request.
+/// - `R`: is the resource id this request points to. Possible values of this are:
+///     - [`AggregationJobId`](resource::AggregationJobId)
+///     - [`CollectionJobId`](resource::CollectionJobId)
+///     - [`None`](resource::None)
 #[derive(Debug)]
 #[cfg_attr(test, derive(Default))]
 pub struct DapRequest<P, R = resource::None> {