Skip to content

armgit / moli

Public Imported from GitHub
0

Best headless browser for AI agents. Lite, Fast, High-Compatibility. Built in Rust

docs(content-type): clarify parser selection

ldm0e684648346d5
diff --git a/moli-content-type/src/lib.rs b/moli-content-type/src/lib.rs
index bf53e96d7..019731cee 100644
--- a/moli-content-type/src/lib.rs
+++ b/moli-content-type/src/lib.rs
@@ -1,20 +1,21 @@
//! MIME parsing for two distinct browser contexts.
//!
-//! Choose the entry point from the source of the value:
+//! Choose the entry point from the browser algorithm being implemented:
//!
//! - [`parse_mime_type`] applies the WHATWG MIME parsing and serialization
-//! rules. Use it for standards-facing MIME operations such as Blob/File type
-//! handling, MIME classification, and interpreting an already selected MIME
-//! value.
+//! rules. Use it when a web-platform algorithm says to parse a MIME type,
+//! including Blob/File type handling, MIME classification and sniffing,
+//! Fetch response MIME handling, and media capability checks.
//! - [`parse_response_content_type`] matches Chromium's network-layer parsing
-//! of a raw HTTP response `Content-Type` field. Use it when transport
-//! metadata must retain Chromium behavior for values such as `charset` and
-//! multipart `boundary`.
+//! of an HTTP response `Content-Type` field. Use it only when reproducing
+//! Chromium transport-metadata behavior, such as selecting a response
+//! `charset` or multipart `boundary`.
//!
//! These parsers intentionally have different validity and recovery rules. A
-//! value accepted by one is not necessarily accepted by the other, so callers
-//! must select the parser from the value's origin rather than treating the two
-//! result types as interchangeable.
+//! response header can legitimately reach either parser depending on the
+//! operation: MIME classification uses [`parse_mime_type`], while transport
+//! charset selection uses [`parse_response_content_type`]. The result types
+//! are therefore not interchangeable.
mod response;
mod whatwg;
diff --git a/moli-content-type/src/response.rs b/moli-content-type/src/response.rs
index 718a650ea..1fc52be40 100644
--- a/moli-content-type/src/response.rs
+++ b/moli-content-type/src/response.rs
@@ -40,9 +40,10 @@ impl ResponseContentType {
///
/// This intentionally accepts malformed values seen on the network, including
/// an unterminated quoted parameter and an empty subtype. Use this only for
-/// response transport metadata, such as extracting `charset` or multipart
-/// `boundary`; standards-facing MIME operations must use
-/// [`crate::parse_mime_type`].
+/// Chromium transport-metadata behavior, such as selecting a response
+/// `charset` or multipart `boundary`. A value does not belong here merely
+/// because it came from a response header: web-platform MIME classification
+/// and sniffing use [`crate::parse_mime_type`].
pub fn parse_response_content_type(input: &str) -> Option<ResponseContentType> {
// Chromium treats an exact bare wildcard as meaningless, while retaining
// wildcard values that have parameters or even trailing whitespace.
diff --git a/moli-content-type/src/whatwg.rs b/moli-content-type/src/whatwg.rs
index 860bb1693..50dbbcf07 100644
--- a/moli-content-type/src/whatwg.rs
+++ b/moli-content-type/src/whatwg.rs
@@ -47,10 +47,10 @@ impl fmt::Display for MimeType {
/// Parses a standards-facing MIME value using WHATWG validation,
/// normalization, and parameter recovery rules.
///
-/// Use this for Web API MIME operations and for interpreting an already
-/// selected MIME value. Raw HTTP response `Content-Type` metadata must instead
-/// use [`crate::parse_response_content_type`] so its Chromium network behavior
-/// is preserved.
+/// Use this whenever a web-platform algorithm says to parse a MIME type. That
+/// includes MIME classification and sniffing even when the input originated
+/// in an HTTP response header. Use [`crate::parse_response_content_type`] only
+/// for Chromium's separate transport-metadata interpretation.
pub fn parse_mime_type(input: &str) -> Option<MimeType> {
input.parse().ok().map(|inner| MimeType { inner })
}