feat(container): add singleton lifetime support

docs/1-essentials/05-container.md

@@ -224,7 +224,7 @@ final readonly class Client
 }
 ```
 
-Furthermore, an initializer method can be annotated as a `#[Singleton]`, meaning its return object will only ever be resolved once:
+Furthermore, an initializer method can be annotated as a `#[Singleton]`, meaning its return object will be reused for the singleton’s lifetime:
 
 ```php app/MarkdownInitializer.php
 use Tempest\Console\ConsoleCommand;
@@ -241,6 +241,55 @@ final readonly class MarkdownInitializer implements Initializer
 }
 ```
 
+### Singleton lifetimes
+
+By default, singletons use {`Tempest\Container\Lifetime::PROCESS`} as their lifetime: the container keeps the same instance for the lifetime of the process, including across requests in long-running applications.
+
+For objects that hold request-specific state, you can specify `Lifetime::REQUEST` instead:
+
+```php
+use Tempest\Container\Lifetime;
+use Tempest\Container\Singleton;
+
+#[Singleton(lifetime: Lifetime::REQUEST)]
+final class RequestContext
+{
+    public ?string $tenantId = null;
+}
+```
+
+The container reuses this instance within a request. When the container is reset, it clears the instance so that the next request receives a fresh one, this happens after every request in long-running applications.
+
+You can also set the lifetime when registering a singleton with the container. Use a factory for request-lifetime singletons so the container can create a fresh instance after each reset:
+
+```php
+use Tempest\Container\Lifetime;
+
+$container->singleton(
+    RequestContext::class,
+    fn () => new RequestContext(),
+    lifetime: Lifetime::REQUEST,
+);
+```
+
+Note that you can also declare the lifetime via initializers:
+
+```php
+use Tempest\Container\Container;
+use Tempest\Container\Initializer;
+use Tempest\Container\Lifetime;
+use Tempest\Container\Singleton;
+
+final class RequestContextInitializer implements Initializer
+{
+    #[Singleton(lifetime: Lifetime::REQUEST)]
+    public function initialize(Container $container): RequestContext
+    {
+        return new RequestContext();
+    }
+}
+```
+
 ### Tagged singletons
 
 In some cases, you want more control over singleton definitions.

packages/container/src/Container.php

@@ -16,7 +16,7 @@ public function register(string $className, callable $definition): self;
 
     public function unregister(string $className, bool $tagged = false): self;
 
-    public function singleton(string $className, mixed $definition, string|UnitEnum|null $tag = null): self;
+    public function singleton(string $className, mixed $definition, string|UnitEnum|null $tag = null, ?Lifetime $lifetime = null): self;
 
     public function config(object $config): self;
 

packages/container/src/GenericContainer.php

@@ -21,6 +21,7 @@
 use Tempest\Reflection\TypeReflector;
 use Throwable;
 use UnitEnum;
+use WeakMap;
 
 use const ARRAY_FILTER_USE_BOTH;
 
@@ -31,6 +32,12 @@ final class GenericContainer implements Container
     /** @var array<class-string<DynamicInitializer>, DynamicInitializer> */
     private array $resolvedDynamicInitializers = [];
 
+    /** @var WeakMap<object, Lifetime> */
+    private WeakMap $singletonLifetimes;
+
+    /** @var array<string, Lifetime> */
+    private array $registeredSingletonLifetimes = [];
+
     public function __construct(
         /** @var ArrayIterator<array-key, mixed> $definitions */
         private(set) ArrayIterator $definitions = new ArrayIterator(),
@@ -55,6 +62,7 @@ public function __construct(
 
         private(set) ?DependencyChain $chain = null,
     ) {
+        $this->singletonLifetimes = new WeakMap();
         $this->singleton(Container::class, $this);
         $this->singleton(ContainerInterface::class, $this);
         $this->singleton(GenericContainer::class, $this);
@@ -146,6 +154,7 @@ public function unregister(string $className, bool $tagged = false): self
         unset($this->definitions[$className]);
         unset($this->singletonDefinitions[$className]);
         unset($this->resolvedSingletons[$className]);
+        unset($this->registeredSingletonLifetimes[$className]);
 
         if ($tagged) {
             foreach ($this->singletonDefinitions as $key => $definition) {
@@ -154,6 +163,7 @@ public function unregister(string $className, bool $tagged = false): self
                 }
 
                 unset($this->singletonDefinitions[$key]);
+                unset($this->registeredSingletonLifetimes[$key]);
             }
 
             foreach ($this->resolvedSingletons as $key => $definition) {
@@ -173,14 +183,24 @@ public function has(string $className, string|UnitEnum|null $tag = null): bool
         return isset($this->definitions[$className]) || isset($this->singletonDefinitions[$this->resolveTaggedName($className, $tag)]);
     }
 
-    public function singleton(string $className, mixed $definition, string|UnitEnum|null $tag = null): self
+    public function singleton(string $className, mixed $definition, string|UnitEnum|null $tag = null, ?Lifetime $lifetime = null): self
     {
         if ($definition instanceof HasTag) {
             $tag = $definition->tag;
         }
 
         $dependencyName = $this->resolveTaggedName($className, $tag);
 
+        if ($lifetime instanceof Lifetime) {
+            $this->registeredSingletonLifetimes[$dependencyName] = $lifetime;
+
+            if (is_object($definition) && ! $definition instanceof Closure) {
+                $this->singletonLifetimes[$definition] = $lifetime;
+            }
+        } else {
+            unset($this->registeredSingletonLifetimes[$dependencyName]);
+        }
+
         $this->singletonDefinitions[$dependencyName] = $definition;
         unset($this->resolvedSingletons[$dependencyName]);
 
@@ -393,12 +413,21 @@ private function resolveDependency(string $className, string|UnitEnum|null $tag
 
         // Check if the class has been registered as a singleton.
         if ($singletonDefinition = $this->singletonDefinitions[$dependencyName] ?? null) {
-            $this->resolveChain()->add($class);
+            // Only closures need to be tracked: an already constructed instance cannot take part in a cycle.
+            if ($singletonDefinition instanceof Closure) {
+                $this->resolveChain()->add($class);
+
+                try {
+                    $instance = $singletonDefinition($this);
+                } finally {
+                    $this->resolveChain()->pop();
+                }
+            } else {
+                $instance = $singletonDefinition;
+            }
 
-            try {
-                $instance = $singletonDefinition instanceof Closure ? $singletonDefinition($this) : $singletonDefinition;
-            } finally {
-                $this->resolveChain()->pop();
+            if (isset($this->registeredSingletonLifetimes[$dependencyName])) {
+                $this->singletonLifetimes[$instance] = $this->registeredSingletonLifetimes[$dependencyName];
             }
 
             $this->resolvedSingletons[$dependencyName] = $instance;
@@ -432,9 +461,12 @@ private function resolveDependency(string $className, string|UnitEnum|null $tag
                 $this->resolveChain()->pop();
             }
 
-            $singleton = $initializerClass->getAttribute(Singleton::class) ?? $initializerClass->getMethod('initialize')->getAttribute(Singleton::class);
+            $singleton = $initializerClass->getAttribute(Singleton::class) ?? $initializerClass
+                ->getMethod('initialize')
+                ->getAttribute(Singleton::class) ?? $class->getAttribute(Singleton::class);
 
             if ($singleton !== null) {
+                $this->singletonLifetimes[$object] = $singleton->lifetime;
                 $this->singleton($className, $object, $tag);
             }
 
@@ -531,8 +563,9 @@ private function autowire(string $className, string|UnitEnum|null $tag, mixed ..
         if (
             ! $classReflector->getType()->matches(Initializer::class)
             && ! $classReflector->getType()->matches(DynamicInitializer::class)
-            && $classReflector->hasAttribute(Singleton::class)
+            && ($singleton = $classReflector->getAttribute(Singleton::class)) !== null
         ) {
+            $this->singletonLifetimes[$instance] = $singleton->lifetime;
             $this->singleton($className, $instance, $tag);
         }
 
@@ -776,7 +809,6 @@ public function addResettable(string|ClassReflector $resettableClass): Container
 
     public function reset(): self
     {
-        $this->resolvedSingletons = new ArrayIterator();
         $this->resolvedDynamicInitializers = [];
 
         foreach ($this->resettables as $resettableClass) {
@@ -786,6 +818,25 @@ public function reset(): self
             $resettable->reset();
         }
 
+        foreach ([$this->singletonDefinitions, $this->resolvedSingletons] as $singletons) {
+            foreach ($singletons->getArrayCopy() as $dependencyName => $instance) {
+                // Factories remain registered so the next request can create a fresh instance.
+                if (! is_object($instance)) {
+                    continue;
+                }
+
+                if ($instance instanceof Closure) {
+                    continue;
+                }
+
+                $this->singletonLifetimes[$instance] ??= new ClassReflector($instance)->getAttribute(Singleton::class)->lifetime ?? Lifetime::PROCESS;
+
+                if ($this->singletonLifetimes[$instance] === Lifetime::REQUEST) {
+                    unset($singletons[$dependencyName]);
+                }
+            }
+        }
+
         return $this;
     }
 

packages/container/src/Lifetime.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Container;
+
+enum Lifetime
+{
+    /** Keep a singleton alive as long as the process is running */
+    case PROCESS;
+
+    /** Keep a singleton alive within the lifetime of a request */
+    case REQUEST;
+}

packages/container/src/Singleton.php

@@ -12,5 +12,6 @@
     public function __construct(
         public ?string $tag = null,
         public bool $dynamicTags = false,
+        public Lifetime $lifetime = Lifetime::PROCESS,
     ) {}
 }