start of interface rework, some bug fixes

Author: clegginabox

src/AirlockInterface.php src/Airlock.phpsrc/AirlockInterface.php renamed to src/Airlock.php

@@ -12,7 +12,7 @@
  * An airlock controls how many users can access a resource simultaneously,
  * queuing additional users until a slot becomes available.
  */
-interface AirlockInterface
+interface Airlock
 {
     /**
      * Attempt to enter the airlock.
@@ -34,25 +34,6 @@ public function enter(string $identifier, int $priority = 0): EntryResult;
      */
     public function leave(string $identifier): void;
 
-    /**
-     * Release an acquired slot and notify the next queued user.
-     *
-     * Call this when the user finishes using the resource or their session ends.
-     *
-     * @param SealToken $token The access token received from enter()
-     */
-    public function release(SealToken $token): void;
-
-    /**
-     * Extend the lease on an acquired slot.
-     *
-     * @param SealToken $token The current access token
-     * @param float|null $ttlInSeconds New TTL, or null to use the default
-     *
-     * @return SealToken|null New token if refreshed, null if the lease expired
-     */
-    public function refresh(SealToken $token, ?float $ttlInSeconds = null): ?SealToken;
-
     /**
      * Get the current queue position for a waiting user.
      *

src/Bridge/Symfony/Mercure/SymfonyMercureHubFactory.php

@@ -4,7 +4,7 @@
 
 namespace Clegginabox\Airlock\Bridge\Symfony\Mercure;
 
-use Clegginabox\Airlock\AirlockInterface;
+use Clegginabox\Airlock\Airlock;
 use Symfony\Component\Mercure\Hub;
 use Symfony\Component\Mercure\HubInterface;
 use Symfony\Component\Mercure\Jwt\FactoryTokenProvider;
@@ -29,7 +29,7 @@ public static function create(string $hubUrl, string $jwtSecret): HubInterface
     public static function createForAirlock(
         string $hubUrl,
         string $jwtSecret,
-        AirlockInterface $airlock,
+        Airlock $airlock,
         string $identifier,
     ): HubInterface {
         $topic = $airlock->getTopic($identifier);

src/Bridge/Symfony/Seal/SymfonyLockSeal.php

@@ -5,10 +5,12 @@
 namespace Clegginabox\Airlock\Bridge\Symfony\Seal;
 
 use Clegginabox\Airlock\Exception\LeaseExpiredException;
+use Clegginabox\Airlock\Exception\SealReleasingException;
 use Clegginabox\Airlock\Seal\RefreshableSeal;
 use Clegginabox\Airlock\Seal\ReleasableSeal;
 use Clegginabox\Airlock\Seal\Seal;
 use Clegginabox\Airlock\Seal\SealToken;
+use Symfony\Component\Lock\Exception\LockReleasingException;
 use Symfony\Component\Lock\Key;
 use Symfony\Component\Lock\LockFactory;
 use Symfony\Component\Lock\LockInterface;
@@ -44,11 +46,21 @@ public function tryAcquire(): ?SealToken
     public function release(SealToken $token): void
     {
         if (!$token instanceof SymfonyLockToken) {
-            return;
+            throw new SealReleasingException(
+                sprintf('Invalid token type: %s. Expected %s', $token::class, SymfonyLockToken::class)
+            );
         }
 
-        $lock = $this->factory->createLockFromKey($token->getKey());
-        $lock->release();
+        try {
+            $lock = $this->factory->createLockFromKey($token->getKey());
+            $lock->release();
+        } catch (LockReleasingException $e) {
+            throw new SealReleasingException(
+                sprintf('Unable to release lock: %s', $e->getMessage()),
+                $e->getCode(),
+                $e
+            );
+        }
     }
 
     public function refresh(SealToken $token, ?float $ttlInSeconds = null): SealToken

src/OpportunisticAirlock.php

@@ -4,19 +4,16 @@
 
 namespace Clegginabox\Airlock;
 
-use Clegginabox\Airlock\Seal\RefreshableSeal;
-use Clegginabox\Airlock\Seal\ReleasableSeal;
 use Clegginabox\Airlock\Seal\Seal;
-use Clegginabox\Airlock\Seal\SealToken;
 
 /**
  * A waiting room implementation that uses polling to determine admission.
  * The first user to acquire the semaphore is admitted.
  */
-final readonly class OpportunisticAirlock implements AirlockInterface
+final readonly class OpportunisticAirlock implements Airlock
 {
     public function __construct(
-        private Seal&ReleasableSeal&RefreshableSeal $seal,
+        private Seal $seal,
     ) {
     }
 
@@ -35,16 +32,6 @@ public function leave(string $identifier): void
         // Nothing to do here
     }
 
-    public function release(SealToken $token): void
-    {
-        $this->seal->release($token);
-    }
-
-    public function refresh(SealToken $token, ?float $ttlInSeconds = null): SealToken
-    {
-        return $this->seal->refresh($token, $ttlInSeconds);
-    }
-
     public function getPosition(string $identifier): ?int
     {
         return null;

src/QueueAirlock.php

@@ -6,15 +6,14 @@
 
 use Clegginabox\Airlock\Notifier\AirlockNotifierInterface;
 use Clegginabox\Airlock\Queue\QueueInterface;
-use Clegginabox\Airlock\Seal\RefreshableSeal;
 use Clegginabox\Airlock\Seal\ReleasableSeal;
 use Clegginabox\Airlock\Seal\Seal;
 use Clegginabox\Airlock\Seal\SealToken;
 
-final readonly class QueueAirlock implements AirlockInterface
+final readonly class QueueAirlock implements Airlock, ReleasingAirlock
 {
     public function __construct(
-        private Seal&ReleasableSeal&RefreshableSeal $seal,
+        private Seal&ReleasableSeal $seal,
         private QueueInterface $queue,
         private AirlockNotifierInterface $notifier,
         private string $topicPrefix = '/waiting-room',
@@ -29,7 +28,7 @@ public function enter(string $identifier, int $priority = 0): EntryResult
         $position = $this->queue->add($identifier, $priority);
 
         // 2. Are we at the front of the line? (Position 1)
-        if ($position > 1) {
+        if ($position !== 1) {
             // No? Wait your turn.
             return EntryResult::queued($position, $this->topicFor($identifier));
         }
@@ -67,11 +66,6 @@ public function release(SealToken $token): void
         $this->notifier->notify($nextPassenger, $this->topicFor($nextPassenger));
     }
 
-    public function refresh(SealToken $token, ?float $ttlInSeconds = null): SealToken
-    {
-        return $this->seal->refresh($token, $ttlInSeconds);
-    }
-
     public function getPosition(string $identifier): ?int
     {
         return $this->queue->getPosition($identifier);

src/RefreshingAirlock.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Clegginabox\Airlock;
+
+use Clegginabox\Airlock\Seal\SealToken;
+
+interface RefreshingAirlock
+{
+    /**
+     * Extend the lease on an acquired slot.
+     *
+     * @param SealToken $token The current access token
+     * @param float|null $ttlInSeconds New TTL, or null to use the default
+     *
+     * @return SealToken|null New token if refreshed, null if the lease expired
+     */
+    public function refresh(SealToken $token, ?float $ttlInSeconds = null): ?SealToken;
+}

src/ReleasingAirlock.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Clegginabox\Airlock;
+
+use Clegginabox\Airlock\Seal\SealToken;
+
+interface ReleasingAirlock
+{
+    /**
+     * Release an acquired slot and notify the next queued user.
+     *
+     * Call this when the user finishes using the resource or their session ends.
+     *
+     * @param SealToken $token The access token received from enter()
+     */
+    public function release(SealToken $token): void;
+}

tests/Unit/Bridge/Symfony/Mercure/SymfonyMercureHubFactoryTest.php

@@ -4,7 +4,7 @@
 
 namespace Clegginabox\Airlock\Tests\Unit\Bridge\Symfony\Mercure;
 
-use Clegginabox\Airlock\AirlockInterface;
+use Clegginabox\Airlock\Airlock;
 use Clegginabox\Airlock\Bridge\Symfony\Mercure\SymfonyMercureHubFactory;
 use JsonException;
 use PHPUnit\Framework\TestCase;
@@ -23,7 +23,7 @@ public function testCreateReturnsHub(): void
 
     public function testCreateForAirlockScopesJwtToTopic(): void
     {
-        $airlock = $this->createMock(AirlockInterface::class);
+        $airlock = $this->createMock(Airlock::class);
         $airlock->expects($this->once())
             ->method('getTopic')
             ->with('user-123')

tests/Unit/Bridge/Symfony/Seal/SymfonyLockSealTest.php

@@ -7,6 +7,7 @@
 use Clegginabox\Airlock\Bridge\Symfony\Seal\SymfonyLockSeal;
 use Clegginabox\Airlock\Bridge\Symfony\Seal\SymfonyLockToken;
 use Clegginabox\Airlock\Exception\LeaseExpiredException;
+use Clegginabox\Airlock\Exception\SealReleasingException;
 use Clegginabox\Airlock\Seal\SealToken;
 use PHPUnit\Framework\Attributes\AllowMockObjectsWithoutExpectations;
 use PHPUnit\Framework\MockObject\MockObject;
@@ -98,13 +99,14 @@ public function testItReleasesLock(): void
     }
 
     #[AllowMockObjectsWithoutExpectations]
-    public function testReleaseWithInvalidTokenTypeDoesNothing(): void
+    public function testReleaseWithInvalidTokenThrows(): void
     {
         $invalidToken = $this->createMock(SealToken::class);
 
         $this->mockFactory->expects($this->never())
             ->method('createLockFromKey');
 
+        $this->expectException(SealReleasingException::class);
         $this->seal->release($invalidToken);
     }
 

tests/Unit/OpportunisticAirlockTest.php

@@ -82,24 +82,6 @@ public function testEnterWhenQueued(): void
         $this->assertEquals(-1, $entryResult->getPosition());
     }
 
-    public function testRelease(): void
-    {
-        $this->mockSeal->expects($this->once())
-            ->method('release')
-            ->with($this->mockSealToken);
-
-        $this->airlock->release($this->mockSealToken);
-    }
-
-    public function testRefresh(): void
-    {
-        $this->mockSeal->expects($this->once())
-            ->method('refresh')
-            ->with($this->mockSealToken);
-
-        $this->airlock->refresh($this->mockSealToken);
-    }
-
     #[AllowMockObjectsWithoutExpectations]
     public function testLeave(): void
     {