Review referenced RFCs for compliance, clarity and currency

- Rename `Regex::UUID` to `UUID_V4`
- Add `Regex::UUID` to match all UUIDs and adopt in
  `AbstractSyncProvider::isValidIdentifier()`
- Http: Adopt terminology and behaviour of latest RFCs
  - Especially:
    - \[RFC7230] and \[RFC7231] -> \[RFC9112] and \[RFC9110]
    - \[RFC5987] -> \[RFC8187]
  - Replace "header line" with "field line" where appropriate
  - Add and implement `HeadersInterface` methods `hasBadWhitespace()`
    and `hasObsoleteLineFolding()`
  - In `Headers::addLine()`, don't throw `InvalidHeaderException` when
    bad whitespace is received and `$strict = true`
  - Rearrange `HasHttpRegex`
  - Fix `AbstractRequest` issue where request target type `origin-form`
    may be incorrectly detected when the given URI has an empty path

Author: lkrms

src/Toolkit/Contract/Http/HeadersInterface.php

@@ -27,10 +27,10 @@ interface HeadersInterface extends
     public function __construct($items = []);
 
     /**
-     * Parse and apply a header line or continuation thereof
+     * Parse and apply a header field line or continuation thereof
      *
      * To initialise an instance from an HTTP stream or message, call this
-     * method once per header line after the request or status line, including
+     * method once per field line after the request or status line, including
      * the CRLF sequence at the end of each line. After receiving an empty line
      * (`"\r\n"`), {@see hasEmptyLine()} returns `true`, and any headers
      * received via {@see addLine()} are applied as trailers.
@@ -43,10 +43,20 @@ public function __construct($items = []);
     public function addLine(string $line);
 
     /**
-     * Check if an empty header line has been received via addLine()
+     * Check if an empty line has been received via addLine()
      */
     public function hasEmptyLine(): bool;
 
+    /**
+     * Check if a line with bad whitespace has been received via addLine()
+     */
+    public function hasBadWhitespace(): bool;
+
+    /**
+     * Check if obsolete line folding has been received via addLine()
+     */
+    public function hasObsoleteLineFolding(): bool;
+
     /**
      * Apply a value to a header, preserving any existing values
      *
@@ -108,8 +118,8 @@ public function trailers();
     public function withoutTrailers();
 
     /**
-     * Get header names and values in their original order as a list of header
-     * fields, preserving the original case of each header
+     * Get header names and values in their original order as a list of field
+     * lines, preserving the original case of each header
      *
      * If `$emptyFormat` is given, it is used for headers with an empty value.
      *

src/Toolkit/Curler/Curler.php

@@ -1156,12 +1156,12 @@ static function ($handle, $infile, int $length) use ($body): string {
                 }
             }
         } elseif (self::REQUEST_METHOD_HAS_BODY[$method] ?? false) {
-            // [RFC7230], Section 3.3.2: "A user agent SHOULD send a
-            // Content-Length in a request message when no Transfer-Encoding is
-            // sent and the request method defines a meaning for an enclosed
-            // payload body. For example, a Content-Length header field is
-            // normally sent in a POST request even when the value is 0
-            // (indicating an empty payload body)."
+            // [RFC9110], Section 8.6 ("Content-Length"): "A user agent SHOULD
+            // send Content-Length in a request when the method defines a
+            // meaning for enclosed content and it is not sending
+            // Transfer-Encoding. For example, a user agent normally sends
+            // Content-Length in a POST request even when the value is 0
+            // (indicating empty content)"
             $request = $request->withHeader(self::HEADER_CONTENT_LENGTH, '0');
         }
 

src/Toolkit/Http/HasHttpRegex.php

@@ -7,10 +7,15 @@
  */
 interface HasHttpRegex
 {
-    public const HTTP_TOKEN = '(?:(?i)[-0-9a-z!#$%&\'*+.^_`|~]++)';
+    public const AUTHORITY_FORM_REGEX = '/^(([-a-z0-9!$&\'()*+,.;=_~]|%[0-9a-f]{2})++|\[[0-9a-f:]++\]):[0-9]++$/iD';
+    public const HOST_REGEX = '/^(([-a-z0-9!$&\'()*+,.;=_~]|%[0-9a-f]{2})++|\[[0-9a-f:]++\])$/iD';
+    public const HTTP_FIELD_NAME_REGEX = self::HTTP_TOKEN_REGEX;
+    public const HTTP_FIELD_VALUE_REGEX = '/^([\x21-\x7e\x80-\xff]++(?:\h++[\x21-\x7e\x80-\xff]++)*+)?$/D';
     public const HTTP_TOKEN_REGEX = '/^[-0-9a-z!#$%&\'*+.^_`|~]++$/iD';
+    public const HTTP_TOKEN = '(?:(?i)[-0-9a-z!#$%&\'*+.^_`|~]++)';
+    public const SCHEME_REGEX = '/^[a-z][-a-z0-9+.]*$/iD';
 
-    public const HTTP_HEADER_FIELD_REGEX = <<<'REGEX'
+    public const HTTP_FIELD_LINE_REGEX = <<<'REGEX'
 / ^
 (?(DEFINE)
   (?<token> [-0-9a-z!#$%&'*+.^_`|~]++ )
@@ -25,9 +30,6 @@ interface HasHttpRegex
 $ /ixD
 REGEX;
 
-    public const HTTP_HEADER_FIELD_NAME_REGEX = self::HTTP_TOKEN_REGEX;
-    public const HTTP_HEADER_FIELD_VALUE_REGEX = '/^([\x21-\x7e\x80-\xff]++(?:\h++[\x21-\x7e\x80-\xff]++)*+)?$/D';
-
     public const URI_REGEX = <<<'REGEX'
 ` ^
 (?(DEFINE)
@@ -64,8 +66,4 @@ interface HasHttpRegex
 (?: \# (?<fragment> (?: (?&pchar) | [?/] )* ) )?+
 $ `ixD
 REGEX;
-
-    public const SCHEME_REGEX = '/^[a-z][-a-z0-9+.]*$/iD';
-    public const HOST_REGEX = '/^(([-a-z0-9!$&\'()*+,.;=_~]|%[0-9a-f]{2})++|\[[0-9a-f:]++\])$/iD';
-    public const AUTHORITY_FORM_REGEX = '/^(([-a-z0-9!$&\'()*+,.;=_~]|%[0-9a-f]{2})++|\[[0-9a-f:]++\]):[0-9]++$/iD';
 }

src/Toolkit/Http/Headers.php

@@ -58,6 +58,8 @@ class Headers implements HeadersInterface, IteratorAggregate, HasHttpRegex
 
     private bool $IsParser;
     private bool $HasEmptyLine = false;
+    private bool $HasBadWhitespace = false;
+    private bool $HasObsoleteLineFolding = false;
 
     /**
      * Trailing whitespace carried over from the previous line
@@ -101,7 +103,7 @@ public static function from($headersOrPayload): self
                 "\r\n",
                 explode("\r\n\r\n", $headersOrPayload, 2)[0] . "\r\n",
             ));
-            // Parse header lines
+            // Parse field lines
             $instance = new static();
             foreach ($lines as $line) {
                 $instance = $instance->addLine("$line\r\n");
@@ -114,7 +116,7 @@ public static function from($headersOrPayload): self
     /**
      * @inheritDoc
      *
-     * @param bool $strict If `true`, strict \[RFC7230] compliance is enforced.
+     * @param bool $strict If `true`, strict \[RFC9112] compliance is enforced.
      */
     public function addLine(string $line, bool $strict = false)
     {
@@ -138,43 +140,50 @@ private function doAddLine(string $line, bool $strict)
     {
         if ($strict && substr($line, -2) !== "\r\n") {
             throw new InvalidHeaderException(
-                'HTTP header line must end with CRLF',
+                'HTTP field line must end with CRLF',
             );
         }
 
         if ($line === "\r\n" || (!$strict && trim($line) === '')) {
             if ($strict && $this->HasEmptyLine) {
                 throw new InvalidHeaderException(
-                    'HTTP message cannot have empty header line after body',
+                    'HTTP message cannot have empty field line after body',
                 );
             }
             return $this->with('Carry', null)->with('HasEmptyLine', true);
         }
 
         if ($strict) {
             $line = substr($line, 0, -2);
-            if (
-                !Regex::match(self::HTTP_HEADER_FIELD_REGEX, $line, $matches, \PREG_UNMATCHED_AS_NULL)
-                || $matches['bad_whitespace'] !== null
-            ) {
+            if (!Regex::match(self::HTTP_FIELD_LINE_REGEX, $line, $matches, \PREG_UNMATCHED_AS_NULL)) {
                 throw new InvalidHeaderException(
-                    sprintf('Invalid HTTP header field: %s', $line),
+                    sprintf('Invalid HTTP field line: %s', $line),
                 );
             }
 
-            // As per [RFC7230] Section 3.2.4, "replace each received obs-fold
-            // with one or more SP octets prior to interpreting the field value"
+            // As per [RFC9112] Section 5.2 ("Obsolete Line Folding"), "replace
+            // each received obs-fold with one or more SP octets"
             $instance = $this->with('Carry', (string) $matches['carry']);
             if ($matches['extended'] !== null) {
                 if ($this->Carry === null) {
                     throw new InvalidHeaderException(
-                        sprintf('Invalid HTTP header line folding: %s', $line),
+                        sprintf('Invalid HTTP field line folding: %s', $line),
                     );
                 }
                 $line = $this->Carry . ' ' . $matches['extended'];
                 return $instance->extendPreviousLine($line);
             }
 
+            // [RFC9112] Section 5.1 ("Field Line Parsing"):
+            // - "No whitespace is allowed between the field name and colon"
+            // - "A server MUST reject ... any received request message that
+            //   contains whitespace between a header field name and colon"
+            // - "A proxy MUST remove any such whitespace from a response
+            //   message before forwarding the message downstream"
+            if ($matches['bad_whitespace'] !== null) {
+                $instance = $instance->with('HasBadWhitespace', true);
+            }
+
             /** @var string */
             $name = $matches['name'];
             /** @var string */
@@ -190,7 +199,7 @@ private function doAddLine(string $line, bool $strict)
         if (strpos(" \t", $line[0]) !== false) {
             if ($this->Carry === null) {
                 throw new InvalidHeaderException(
-                    sprintf('Invalid HTTP header line folding: %s', $line),
+                    sprintf('Invalid HTTP field line folding: %s', $line),
                 );
             }
             $line = $this->Carry . ' ' . trim($line);
@@ -200,16 +209,15 @@ private function doAddLine(string $line, bool $strict)
         $split = explode(':', $line, 2);
         if (count($split) !== 2) {
             throw new InvalidHeaderException(
-                sprintf('Invalid HTTP header field: %s', $line),
+                sprintf('Invalid HTTP field line: %s', $line),
             );
         }
 
-        // [RFC7230] Section 3.2.4:
-        // - "No whitespace is allowed between the header field-name and colon."
-        // - "A proxy MUST remove any such whitespace from a response message
-        //   before forwarding the message downstream."
         $name = rtrim($split[0]);
         $value = trim($split[1]);
+        if ($name !== $split[0]) {
+            $instance = $instance->with('HasBadWhitespace', true);
+        }
         return $instance->addValue($name, $value)->maybeIndexLastHeader();
     }
 
@@ -223,7 +231,9 @@ private function extendPreviousLine(string $line)
         $k = array_key_last($headers);
         [, $value] = $this->Headers[$k];
         $headers[$k][1] = ltrim($value . $line);
-        return $this->maybeReplaceHeaders($headers, $this->Index);
+        return $this
+            ->with('HasObsoleteLineFolding', true)
+            ->maybeReplaceHeaders($headers, $this->Index);
     }
 
     /**
@@ -249,6 +259,22 @@ public function hasEmptyLine(): bool
         return $this->HasEmptyLine;
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function hasBadWhitespace(): bool
+    {
+        return $this->HasBadWhitespace;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function hasObsoleteLineFolding(): bool
+    {
+        return $this->HasObsoleteLineFolding;
+    }
+
     /**
      * @inheritDoc
      */
@@ -698,7 +724,7 @@ public function getHeaderValues(string $name): array
         $line = $this->getHeaderLine($name);
         return $line === ''
             ? []
-            // [RFC7230] Section 7: "a recipient MUST parse and ignore a
+            // [RFC9110] Section 5.6.1.2: "A recipient MUST parse and ignore a
             // reasonable number of empty list elements"
             : Str::splitDelimited(',', $line);
     }
@@ -831,8 +857,8 @@ private function getIndexHeaders(array $index): array
      */
     private function filterIndex(array $index): array
     {
-        // [RFC7230] Section 5.4: "a user agent SHOULD generate Host as the
-        // first header field following the request-line"
+        // [RFC9110] Section 7.2: "A user agent that sends Host SHOULD send it
+        // as the first field in the header section of a request"
         return isset($index['host'])
             ? ['host' => $index['host']] + $index
             : $index;
@@ -919,7 +945,7 @@ private function filterItems(iterable $items): iterable
 
     private function filterName(string $name): string
     {
-        if (!Regex::match(self::HTTP_HEADER_FIELD_NAME_REGEX, $name)) {
+        if (!Regex::match(self::HTTP_FIELD_NAME_REGEX, $name)) {
             throw new InvalidArgumentException(
                 sprintf('Invalid header name: %s', $name),
             );
@@ -930,7 +956,7 @@ private function filterName(string $name): string
     private function filterValue(string $value): string
     {
         $value = Regex::replace('/\r\n\h++/', ' ', trim($value, " \t"));
-        if (!Regex::match(self::HTTP_HEADER_FIELD_VALUE_REGEX, $value)) {
+        if (!Regex::match(self::HTTP_FIELD_VALUE_REGEX, $value)) {
             throw new InvalidArgumentException(
                 sprintf('Invalid header value: %s', $value),
             );

src/Toolkit/Http/HttpUtil.php

@@ -230,10 +230,10 @@ public static function isRequestMethod(string $method): bool
      * Check if a string contains only a host and port number, separated by a
      * colon
      *
-     * \[RFC7230] Section 5.3.3 (authority-form): "When making a CONNECT request
-     * to establish a tunnel through one or more proxies, a client MUST send
-     * only the target URI's authority component (excluding any userinfo and its
-     * "@" delimiter) as the request-target."
+     * \[RFC9112] Section 3.2.3 ("authority-form"): "When making a CONNECT
+     * request to establish a tunnel through one or more proxies, a client MUST
+     * send only the host and port of the tunnel destination as the
+     * request-target."
      */
     public static function isAuthorityForm(string $target): bool
     {
@@ -268,7 +268,7 @@ public static function mediaTypeIs(string $type, string $mimeType): bool
     }
 
     /**
-     * Get an HTTP date as per [RFC7231] Section 7.1.1.1
+     * Get an HTTP date as per [RFC9110] Section 5.6.7 ("Date/Time Formats")
      */
     public static function getDate(?DateTimeInterface $date = null): string
     {
@@ -279,7 +279,7 @@ public static function getDate(?DateTimeInterface $date = null): string
 
     /**
      * Get a product identifier suitable for User-Agent and Server headers as
-     * per [RFC7231] Section 5.5.3
+     * per [RFC9110] Section 10.1.5 ("User-Agent")
      */
     public static function getProduct(): string
     {
@@ -305,7 +305,7 @@ public static function getMultipartMediaType(MultipartStreamInterface $stream):
 
     /**
      * Escape and double-quote a string unless it is a valid HTTP token, as per
-     * [RFC7230] Section 3.2.6
+     * [RFC9110] Section 5.6.4 ("Quoted Strings")
      */
     public static function maybeQuoteString(string $string): string
     {
@@ -315,15 +315,17 @@ public static function maybeQuoteString(string $string): string
     }
 
     /**
-     * Escape and double-quote a string as per [RFC7230] Section 3.2.6
+     * Escape and double-quote a string as per [RFC9110] Section 5.6.4 ("Quoted
+     * Strings")
      */
     public static function quoteString(string $string): string
     {
         return '"' . str_replace(['\\', '"'], ['\\\\', '\"'], $string) . '"';
     }
 
     /**
-     * Unescape and remove quotes from a string as per [RFC7230] Section 3.2.6
+     * Unescape and remove quotes from a string as per [RFC9110] Section 5.6.4
+     * ("Quoted Strings")
      */
     public static function unquoteString(string $string): string
     {

src/Toolkit/Http/Message/AbstractRequest.php

@@ -66,7 +66,7 @@ public function getRequestTarget(): string
             return $this->RequestTarget;
         }
 
-        // As per [RFC7230] Section 5.3.1 ("origin-form")
+        // As per [RFC9112] Section 3.2.1 ("origin-form")
         $query = $this->Uri->getComponents()['query'] ?? null;
         return Str::coalesce($this->Uri->getPath(), '/')
             . ($query === null ? '' : '?' . $query);
@@ -130,7 +130,7 @@ private function filterRequestTarget(string $requestTarget): ?string
             return null;
         }
 
-        // As per [RFC7230] Section 5.3 ("Request Target")
+        // As per [RFC9112] Section 3.2 ("Request Target")
         /** @disregard P1006 */
         if (
             // "asterisk-form"
@@ -141,7 +141,10 @@ private function filterRequestTarget(string $requestTarget): ?string
                 // "absolute-form"
                 isset($parts['scheme'])
                 // "origin-form"
-                || !array_diff_key($parts, ['path' => null, 'query' => null])
+                || (
+                    isset($parts['path'])
+                    && !array_diff_key($parts, ['path' => null, 'query' => null])
+                )
             ))
         ) {
             return $requestTarget;

src/Toolkit/Http/Message/MultipartStream.php

@@ -69,9 +69,11 @@ public function __construct(array $parts = [], ?string $boundary = null)
             if ($filename !== null && $filename !== $asciiFilename) {
                 $disposition[] = sprintf(
                     "filename*=UTF-8''%s",
-                    // Percent-encode as per [RFC5987] Section 3.2 ("Parameter
-                    // Value Character Set and Language Information")
+                    // Percent-encode as per [RFC8187] Section 3.2 ("Parameter
+                    // Value Character Encoding and Language Information")
                     Regex::replaceCallback(
+                        // HTTP token characters except "*", "'", "%" and those
+                        // left alone by `rawurlencode()`
                         '/[^!#$&+^`|]++/',
                         fn($matches) => rawurlencode($matches[0]),
                         $filename,