Fix HttpHeaders regressions and restore missing functionality

- Add `IAccessToken` and implement its methods in `AccessToken`
- Add `IHttpHeaders::authorize()`, reinstating previous
  `applyAccessToken()` grammar
- Fix issue where `HttpHeaders::filter()` doesn't operate on lowercase
  keys when `CALLBACK_USE_KEY` or `CALLBACK_USE_BOTH` are in use

Author: lkrms

src/Http/Auth/AccessToken.php

@@ -6,6 +6,7 @@
 use Lkrms\Contract\IImmutable;
 use Lkrms\Contract\IReadable;
 use Lkrms\Exception\InvalidArgumentException;
+use Lkrms\Http\Contract\IAccessToken;
 use Lkrms\Utility\Date;
 use DateTimeImmutable;
 use DateTimeInterface;
@@ -19,34 +20,25 @@
  * @property-read string[] $Scopes
  * @property-read array<string,mixed> $Claims
  */
-final class AccessToken implements IReadable, IImmutable
+final class AccessToken implements IAccessToken, IImmutable, IReadable
 {
     use TFullyReadable;
 
-    /**
-     * @var string
-     */
-    protected $Token;
+    protected string $Token;
 
-    /**
-     * @var string
-     */
-    protected $Type;
+    protected string $Type;
 
-    /**
-     * @var DateTimeImmutable|null
-     */
-    protected $Expires;
+    protected ?DateTimeImmutable $Expires;
 
     /**
      * @var string[]
      */
-    protected $Scopes;
+    protected array $Scopes;
 
     /**
      * @var array<string,mixed>
      */
-    protected $Claims;
+    protected array $Claims;
 
     /**
      * Creates a new AccessToken object
@@ -57,8 +49,13 @@ final class AccessToken implements IReadable, IImmutable
      * @param string[]|null $scopes
      * @param array<string,mixed>|null $claims
      */
-    public function __construct(string $token, string $type, $expires, ?array $scopes = null, ?array $claims = null)
-    {
+    public function __construct(
+        string $token,
+        string $type,
+        $expires,
+        ?array $scopes = null,
+        ?array $claims = null
+    ) {
         if (is_int($expires) && $expires < 0) {
             throw new InvalidArgumentException(sprintf(
                 'Invalid $expires: %d',
@@ -76,4 +73,20 @@ public function __construct(string $token, string $type, $expires, ?array $scope
         $this->Scopes = $scopes ?: [];
         $this->Claims = $claims ?: [];
     }
+
+    /**
+     * @inheritDoc
+     */
+    public function getToken(): string
+    {
+        return $this->Token;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getType(): string
+    {
+        return $this->Type;
+    }
 }

src/Http/Contract/IAccessToken.php

@@ -0,0 +1,16 @@
+<?php declare(strict_types=1);
+
+namespace Lkrms\Http\Contract;
+
+interface IAccessToken
+{
+    /**
+     * Get the object's token string
+     */
+    public function getToken(): string;
+
+    /**
+     * Get the token's type, e.g. "Bearer"
+     */
+    public function getType(): string;
+}

src/Http/Contract/IHttpHeaders.php

@@ -5,6 +5,7 @@
 use Lkrms\Contract\Arrayable;
 use Lkrms\Contract\ICollection;
 use Lkrms\Contract\IImmutable;
+use Lkrms\Http\Catalog\HttpHeader;
 
 /**
  * A collection of HTTP headers
@@ -51,13 +52,23 @@ public function set($key, $value);
     public function unset($key);
 
     /**
-     * Apply values to headers from an array or Traversable, optionally
-     * preserving existing values
+     * Merge the collection with the given headers, optionally preserving
+     * existing values
      *
      * @param Arrayable<string,string[]|string>|iterable<string,string[]|string> $items
      */
     public function merge($items, bool $preserveExisting = false);
 
+    /**
+     * Apply an access token to the collection
+     *
+     * @return static
+     */
+    public function authorize(
+        IAccessToken $token,
+        string $headerName = HttpHeader::AUTHORIZATION
+    );
+
     /**
      * Reduce the collection to headers received after the HTTP message body
      *

src/Http/HttpHeaders.php

@@ -5,9 +5,10 @@
 use Lkrms\Concern\Immutable;
 use Lkrms\Concern\ImmutableArrayAccess;
 use Lkrms\Concern\TReadableCollection;
-use Lkrms\Contract\Arrayable;
 use Lkrms\Contract\ICollection;
 use Lkrms\Exception\InvalidArgumentException;
+use Lkrms\Http\Catalog\HttpHeader;
+use Lkrms\Http\Contract\IAccessToken;
 use Lkrms\Http\Contract\IHttpHeaders;
 use Lkrms\Support\Catalog\RegularExpression as Regex;
 use Lkrms\Utility\Arr;
@@ -69,7 +70,7 @@ public function addLine(string $line, bool $strict = false)
 
         if ($line === "\r\n" || (!$strict && trim($line) === '')) {
             if ($strict && $this->Closed) {
-                throw new InvalidArgumentException('HTTP message cannot have empty line after body');
+                throw new InvalidArgumentException('HTTP message cannot have empty header after body');
             }
             return $this->with('Closed', true)->with('Carry', null);
         }
@@ -250,6 +251,19 @@ public function merge($items, bool $preserveExisting = false)
         return $this->replaceHeaders($headers, $index);
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function authorize(
+        IAccessToken $token,
+        string $headerName = HttpHeader::AUTHORIZATION
+    ) {
+        return $this->set(
+            $headerName,
+            sprintf('%s %s', $token->getType(), $token->getToken())
+        );
+    }
+
     /**
      * @inheritDoc
      */
@@ -285,21 +299,19 @@ public function filter(callable $callback, int $mode = ICollection::CALLBACK_USE
         $changed = false;
 
         foreach ($index as $nextLower => $headerIndex) {
-            $nextKey = null;
             $nextValue = null;
             foreach ($headerIndex as $i) {
                 $header = $this->Headers[$i];
                 $value = reset($header);
-                $nextKey ??= key($header);
                 if ($mode === ICollection::CALLBACK_USE_KEY) {
                     break;
                 }
                 $nextValue[] = $value;
             }
             $next = $mode === ICollection::CALLBACK_USE_KEY
-                ? $nextKey
+                ? $nextLower
                 : ($mode === ICollection::CALLBACK_USE_BOTH
-                    ? [$nextKey => $nextValue]
+                    ? [$nextLower => $nextValue]
                     : $nextValue);
             if ($count++) {
                 if (!$callback($item, $next, $prev)) {

tests/unit/Support/Http/HttpHeadersTest.php

@@ -2,10 +2,14 @@
 
 namespace Lkrms\Tests\Support\Http;
 
+use Lkrms\Contract\ICollection;
 use Lkrms\Exception\InvalidArgumentException;
+use Lkrms\Http\Auth\AccessToken;
 use Lkrms\Http\Catalog\HttpHeader;
+use Lkrms\Http\Catalog\HttpHeaderGroup;
 use Lkrms\Http\HttpHeaders;
 use Lkrms\Support\Catalog\MimeType;
+use Lkrms\Utility\Arr;
 use LogicException;
 
 final class HttpHeadersTest extends \Lkrms\Tests\TestCase
@@ -160,7 +164,7 @@ public static function addLineProvider(): array
                 true,
             ],
             '[strict] trailing header #4' => [
-                InvalidArgumentException::class . ',HTTP message cannot have empty line after body',
+                InvalidArgumentException::class . ',HTTP message cannot have empty header after body',
                 ["foo: bar\r\n", "\r\n", "baz: qux\r\n", "\r\n"],
                 true,
                 true,
@@ -258,6 +262,27 @@ public function testEmptyValue(): void
         );
     }
 
+    public function testFilter(): void
+    {
+        $index = Arr::toIndex(Arr::lower(HttpHeaderGroup::SENSITIVE));
+        $token = new AccessToken('foo.bar.baz', 'Bearer', time() + 3600);
+        $headers = (new HttpHeaders())
+            ->authorize($token)
+            ->set(HttpHeader::ACCEPT, '*/*');
+        $this->assertSame([
+            'Authorization' => ['Bearer foo.bar.baz'],
+            'Accept' => ['*/*'],
+        ], $headers->getHeaders());
+        $headers = $headers
+            ->filter(
+                fn(string $key) => !($index[$key] ?? false),
+                ICollection::CALLBACK_USE_KEY
+            );
+        $this->assertSame([
+            'Accept' => ['*/*'],
+        ], $headers->getHeaders());
+    }
+
     public function testOffsetSet(): void
     {
         $headers = new HttpHeaders();