feat: add timelock

Author: innocenzi

packages/clock/src/GenericClock.php

@@ -41,10 +41,9 @@ public function milliseconds(): int
 
     public function sleep(int|Duration $milliseconds): void
     {
-        if ($milliseconds instanceof Duration) {
-            $milliseconds = (int) $milliseconds->getTotalMilliseconds();
-        }
-
-        usleep($milliseconds * MILLISECONDS_PER_SECOND);
+        usleep(match (true) {
+            is_int($milliseconds) => $milliseconds * MILLISECONDS_PER_SECOND,
+            $milliseconds instanceof Duration => (int) $milliseconds->getTotalMicroseconds(),
+        });
     }
 }

packages/cryptography/composer.json

@@ -8,6 +8,9 @@
         "tempest/container": "dev-main",
         "tempest/support": "dev-main"
     },
+    "suggest": {
+        "tempest/clock": "For time-lock support"
+    },
     "autoload": {
         "psr-4": {
             "Tempest\\Cryptography\\": "src"

packages/cryptography/src/Timelock.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Tempest\Cryptography;
+
+use Tempest\Clock\Clock;
+use Tempest\DateTime\Duration;
+
+final class Timelock
+{
+    public function __construct(
+        private readonly Clock $clock,
+    ) {}
+
+    /**
+     * Whether or not a time-locked operation can return early.
+     */
+    public bool $canReturnEarly = false;
+
+    /**
+     * Performs an operation that is time-locked to a specific duration.
+     *
+     * @template TCallReturnType
+     *
+     * @param (callable($this): TCallReturnType) $callback
+     * @param Duration $duration
+     * @return TCallReturnType
+     */
+    public function invoke(callable $callback, Duration $duration): mixed
+    {
+        $exception = null;
+        $start = microtime(as_float: true);
+
+        try {
+            $result = $callback($this);
+        } catch (\Throwable $thrown) {
+            $exception = $thrown;
+        }
+
+        $remainderInMicroseconds = intval($duration->getTotalMicroseconds() - ((microtime(true) - $start) * 1_000_000));
+
+        if (! $this->canReturnEarly && $remainderInMicroseconds > 0) {
+            $this->clock->sleep(Duration::microseconds($remainderInMicroseconds));
+        }
+
+        if ($exception) {
+            throw $exception;
+        }
+
+        return $result;
+    }
+}

packages/cryptography/src/TimelockInitializer.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Tempest\Cryptography;
+
+use Tempest\Clock\Clock;
+use Tempest\Container\Container;
+use Tempest\Container\Initializer;
+
+final class TimelockInitializer implements Initializer
+{
+    public function initialize(Container $container): Timelock
+    {
+        return new Timelock($container->get(Clock::class));
+    }
+}

packages/cryptography/tests/TimelockTest.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace Tempest\Cryptography\Tests;
+
+use PHPUnit\Framework\TestCase;
+use Tempest\Clock\Clock;
+use Tempest\Clock\GenericClock;
+use Tempest\Clock\MockClock;
+use Tempest\Cryptography\Timelock;
+use Tempest\DateTime\Duration;
+
+final class TimelockTest extends TestCase
+{
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        if (! interface_exists(Clock::class)) {
+            $this->markTestSkipped('The Clock interface is not available. This test requires the `tempest/clock` package.');
+        }
+    }
+
+    public function test_callback_is_executed(): void
+    {
+        $clock = new GenericClock();
+        $result = new Timelock($clock)->invoke(fn () => 'hello', Duration::zero());
+
+        $this->assertSame('hello', $result);
+    }
+
+    public function test_locks_for_duration(): void
+    {
+        $clock = new GenericClock();
+        $start = microtime(true);
+
+        $timelock = new Timelock($clock);
+        $timelock->invoke(fn () => null, Duration::milliseconds(100));
+
+        $elapsed = microtime(true) - $start;
+
+        $this->assertGreaterThanOrEqual(0.1, $elapsed, 'The timelock did not wait for the specified duration.');
+        $this->assertLessThan(0.2, $elapsed, 'The timelock waited for too long.');
+    }
+
+    public function test_return_early(): void
+    {
+        $clock = new GenericClock();
+        $timelock = new Timelock($clock);
+
+        $start = microtime(true);
+        $timelock->invoke(
+            callback: fn (Timelock $lock) => $lock->canReturnEarly = true,
+            duration: Duration::milliseconds(100),
+        );
+        $elapsed = microtime(true) - $start;
+
+        $this->assertLessThan(0.1, $elapsed, 'The timelock did not return early as expected.');
+    }
+
+    public function test_throws_exception_after_delay(): void
+    {
+        $clock = new GenericClock();
+        $timelock = new Timelock($clock);
+
+        $start = microtime(true);
+
+        try {
+            $timelock->invoke(
+                callback: fn () => throw new \RuntimeException('This is an error.'),
+                duration: Duration::milliseconds(100),
+            );
+        } catch (\RuntimeException) {
+            $elapsed = microtime(true) - $start;
+            $this->assertGreaterThanOrEqual(0.1, $elapsed, 'The exception was thrown before the timelock duration elapsed.');
+        }
+    }
+
+    public function test_uses_clock_to_sleep(): void
+    {
+        $clock = new MockClock();
+        $timelock = new Timelock($clock);
+
+        $ms = $clock->timestamp()->getMilliseconds();
+
+        $timelock->invoke(
+            callback: fn () => null,
+            duration: Duration::milliseconds(300),
+        );
+
+        $elapsed = $clock->timestamp()->getMilliseconds() - $ms;
+
+        $this->assertSame(300, $elapsed);
+    }
+}

tests/Integration/Cryptography/TimelockTest.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Tests\Tempest\Integration\Cryptography;
+
+use Tempest\Cryptography\Timelock;
+use Tempest\DateTime\Duration;
+use Tests\Tempest\Integration\FrameworkIntegrationTestCase;
+
+final class TimelockTest extends FrameworkIntegrationTestCase
+{
+    public function test_uses_mocked_clock(): void
+    {
+        $clock = $this->clock();
+        $timelock = $this->container->get(Timelock::class);
+
+        $ms = $clock->timestamp()->getMilliseconds();
+        $timelock->invoke(
+            callback: fn () => null,
+            duration: Duration::milliseconds(10_000),
+        );
+        $elapsed = $clock->timestamp()->getMilliseconds() - $ms;
+
+        $this->assertSame(10_000, $elapsed);
+    }
+}