add methods to entity context (#158)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Added a method to signal an entity using a callable, enabling more
flexible signaling.
* Introduced the ability to retrieve a snapshot of an entity's current
state.

* **Documentation**
* Improved PHPDoc comments and type annotations for better clarity and
type safety.

* **Style**
* Made minor formatting and style improvements for consistency and
readability.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Signed-off-by: Robert Landers <landers.robert@gmail.com>

Author: withinboredom

src/EntityContext.php

@@ -41,9 +41,11 @@
 use Bottledcode\DurablePhp\Events\WithOrchestration;
 use Bottledcode\DurablePhp\Exceptions\Unwind;
 use Bottledcode\DurablePhp\Glue\Provenance;
+use Bottledcode\DurablePhp\Proxy\SpyException;
 use Bottledcode\DurablePhp\Proxy\SpyProxy;
 use Bottledcode\DurablePhp\State\EntityHistory;
 use Bottledcode\DurablePhp\State\EntityId;
+use Bottledcode\DurablePhp\State\EntityState;
 use Bottledcode\DurablePhp\State\Ids\StateId;
 use Closure;
 use Crell\Serde\Attributes\ClassSettings;
@@ -111,29 +113,6 @@ public function setState(mixed $value): void
         $this->state = $value;
     }
 
-    public function signalEntity(
-        EntityId $entityId,
-        string $operation,
-        array $input = [],
-        ?DateTimeImmutable $scheduledTime = null,
-    ): void {
-        $event = $this->addFrom(
-            WithEntity::forInstance(
-                StateId::fromEntityId($entityId),
-                RaiseEvent::forOperation($operation, $input),
-            ),
-        );
-        if ($scheduledTime) {
-            $event = WithDelay::forEvent($scheduledTime, $event);
-        }
-        $this->eventDispatcher->fire($event);
-    }
-
-    private function addFrom(Event $event): Event
-    {
-        return WithFrom::forEvent($this->from, $event);
-    }
-
     public function getId(): EntityId
     {
         return $this->id;
@@ -161,6 +140,11 @@ public function startNewOrchestration(string $orchestration, array $input = [],
         );
     }
 
+    private function addFrom(Event $event): Event
+    {
+        return WithFrom::forEvent($this->from, $event);
+    }
+
     public function delay(Closure $self, DateTimeInterface $until = new DateTimeImmutable()): void
     {
         $classReflector = new ReflectionClass($this->history->getState());
@@ -283,4 +267,47 @@ public function revokeRole(string $role): void
             ),
         );
     }
+
+    public function signal(EntityId $entityId, callable $signal): void
+    {
+        $proxy = $this->spyProxy->define($entityId->name);
+        $operationName = null;
+        $arguments = null;
+        $proxy = new $proxy($operationName, $arguments);
+        try {
+            $proxy($signal);
+
+            if ($operationName === null || $arguments === null) {
+                return;
+            }
+        } catch (SpyException) {
+            $this->signalEntity($entityId, $operationName, $arguments ?? []);
+        }
+    }
+
+    public function signalEntity(
+        EntityId $entityId,
+        string $operation,
+        array $input = [],
+        ?DateTimeImmutable $scheduledTime = null,
+    ): void {
+        $event = $this->addFrom(
+            WithEntity::forInstance(
+                StateId::fromEntityId($entityId),
+                RaiseEvent::forOperation($operation, $input),
+            ),
+        );
+        if ($scheduledTime) {
+            $event = WithDelay::forEvent($scheduledTime, $event);
+        }
+        $this->eventDispatcher->fire($event);
+    }
+
+    public function getSnapshot(EntityId $entityId): EntityState
+    {
+        $state = $this->eventDispatcher->getState(StateId::fromEntityId($entityId));
+        assert($state instanceof EntityHistory);
+
+        return $state->getState();
+    }
 }

src/EntityContextInterface.php

@@ -26,6 +26,7 @@
 
 use Bottledcode\DurablePhp\Events\Shares\Operation;
 use Bottledcode\DurablePhp\State\EntityId;
+use Bottledcode\DurablePhp\State\EntityState;
 use Closure;
 use Crell\Serde\Attributes\ClassNameTypeMap;
 use DateTimeImmutable;
@@ -102,6 +103,26 @@ public function getId(): EntityId;
      */
     public function getOperation(): string;
 
+    /**
+     * Call the entity with a single signal
+     *
+     * @template T of EntityState
+     *
+     * @param  EntityId<T>  $entityId
+     * @param  callable(T): void  $signal
+     */
+    public function signal(EntityId $entityId, callable $signal): void;
+
+    /**
+     * Retrieve a snapshot of the remote entity state
+     *
+     * @template T of EntityState
+     *
+     * @param  EntityId<T>  $entityId
+     * @return EntityState<T>
+     */
+    public function getSnapshot(EntityId $entityId): EntityState;
+
     public function startNewOrchestration(string $orchestration, array $input = [], ?string $id = null): void;
 
     public function delayUntil(

src/Proxy/Generator.php

@@ -34,8 +34,13 @@
 
 abstract class Generator
 {
-    public function __construct(protected string|null $cacheDir = null) {}
+    public function __construct(protected ?string $cacheDir = null) {}
 
+    /**
+     * Ensures that the given interface is implemented
+     *
+     * @throws \ReflectionException
+     */
     public function define(string $interface): string
     {
         $name = $this->getName($class = new ReflectionClass($interface));
@@ -45,14 +50,15 @@ public function define(string $interface): string
             $cacheFile = $this->cacheDir . DIRECTORY_SEPARATOR . $name . '.php';
             if (file_exists($cacheFile)) {
                 require_once $cacheFile;
+
                 return '\\' . $namespace . '\\' . $name;
             }
         }
 
         $reflection = new ReflectionClass($interface);
         $fullname = $this->getInterfaceNamespace($reflection) . '\\' . $this->getName($reflection);
 
-        if (!class_exists($fullname)) {
+        if (! class_exists($fullname)) {
             eval($output = $this->generate($interface));
             if ($cacheFile) {
                 file_put_contents($cacheFile, "<?php\n{$output}");
@@ -106,6 +112,7 @@ function (ReflectionMethod $method) {
                 $hooks[] = $this->pureMethod($hook, true);
             }
             $hooks[] = '}';
+
             return implode(
                 "\n",
                 array_filter(
@@ -115,6 +122,7 @@ function (ReflectionMethod $method) {
             );
         }, $props);
         $props = implode("\n", $props);
+
         return <<<EOT
             {$namespace}
             
@@ -139,6 +147,7 @@ protected function getTypes(ReflectionIntersectionType|ReflectionNamedType|Refle
             if ($type->isBuiltin()) {
                 return $nullable . $type->getName();
             }
+
             return $nullable . '\\' . $type->getName();
         }
 

src/State/EntityId.php

@@ -28,10 +28,13 @@
 use Withinboredom\Record;
 
 /**
- * @template T
+ * @template T of EntityState
  */
 readonly class EntityId extends Record implements Stringable
 {
+    /**
+     * @var class-string<T>
+     */
     public protected(set) string $name;
 
     public protected(set) string $id;