fix: docs

Makefile

@@ -181,7 +181,7 @@ ssg.watch: node_modules
 		--signal SIGTERM \
 		--watch ./app \
 		--watch ./docs/pages \
-		--watch ./resonance \
+		--watch ./src \
 		--watch ./resources \
 		--exec '$(MAKE) ssg || exit 1'
 

docs/pages/docs/features/security/oauth2/persistent-data/index.md

@@ -10,4 +10,23 @@ description: >
 
 # Persistent Data
 
-{{docs/features/security/oauth2/persistent-data/*!docs/features/security/oauth2/persistent-data/index}}
+# Usage
+
+Instead of implementing several repositories, you can implement just the 
+`OAuth2EntityRepositoryInterface` that is compatible with all the grant types.
+
+It's primary purpose is to cast OAuth2 data into your application's Doctrine
+entities.
+
+Method | Description
+-|-
+`convertAccessToken`  | convert internal access token model into your entity
+`convertAuthCode`     | convert internal auth code model into your entity
+`convertRefreshToken` | convert internal refresh token model into your entity
+`findAccessToken`     | convert internal access token model into your entity
+`findAuthCode`        | find auth code in your database, return your entity
+`findClient`          | find client in your database, return your entity
+`findRefreshToken`    | find refresh token in your database, return your entity
+`findUser`            | find user in your database, return your entity
+`toAccessToken`       | find access token in your database, return your entity
+`toClientEntity`      | find client in your database, return your entity

docs/pages/docs/features/timers/cron/index.md

@@ -0,0 +1,54 @@
+---
+collections: 
+    - documents
+layout: dm:document
+parent: docs/features/timers/index
+title: CRON
+description: >
+    Learn how to schedule tasks with CRON notation.
+---
+
+# CRON
+
+## Usage
+
+### Running Scheduler
+
+You need to invoke the `cron` command:
+
+```php
+$ php bin/resonance.php cron
+```
+
+That command should be a long-running processs, it *MUST NOT* be executed every 
+minute, because Resonance has it's own built-in CRON scheduler.
+
+### Implementing CRON Jobs
+
+Your class has to implement `CronJobInterface` (or extend `CronJob`) and have 
+`ScheduledWithCron` attribute.
+
+It also needs to belong to the `CronJob` collection.
+
+For example:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Distantmagic\Resonance\Attribute\ScheduledWithCron;
+use Distantmagic\Resonance\Attribute\Singleton;
+use Distantmagic\Resonance\CronJob;
+use Distantmagic\Resonance\SingletonCollection;
+
+#[ScheduledWithCron('* * * * *')]
+#[Singleton(collection: SingletonCollection::CronJob)]
+readonly class EveryMinute extends CronJob
+{
+    public function onCronTick(): void
+    {
+        swoole_error_log(SWOOLE_LOG_DEBUG, 'minute passed');
+    }
+}
+```

docs/pages/docs/features/timers/index.md

@@ -0,0 +1,13 @@
+---
+collections: 
+    - documents
+layout: dm:document
+parent: docs/features/index
+title: Timers
+description: >
+    Learn how to schedule cyclical tasks.
+---
+
+# Timers
+
+{{docs/features/timers/*/index}}

docs/pages/docs/features/timers/tick-timer/index.md

@@ -0,0 +1,41 @@
+---
+collections: 
+    - documents
+layout: dm:document
+parent: docs/features/timers/index
+title: Tick Timer
+description: >
+    Learn how to schedule tasks that trigger every N seconds.
+---
+
+# Tick Timer
+
+## Usage
+
+For example:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Distantmagic\Resonance\Attribute\ScheduledWithTickTimer;
+use Distantmagic\Resonance\Attribute\Singleton;
+use Distantmagic\Resonance\TickTimerJobInterface;
+use Distantmagic\Resonance\SingletonCollection;
+
+#[ScheduledWithTickTimer(5)]
+#[Singleton(collection: SingletonCollection::TickTimerJob)]
+readonly class EveryFiveSeconds extends TickTimerJobInterface
+{
+    public function onTimerTick(): void
+    {
+        swoole_error_log(SWOOLE_LOG_DEBUG, '5 seconds passed');
+    }
+
+    public function shouldRegister(): bool
+    {
+        return true;
+    }
+}
+```

src/CoroutineCommand.php

@@ -7,6 +7,7 @@
 use Symfony\Component\Console\Command\Command as SymfonyCommand;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
+use Throwable;
 
 use function Swoole\Coroutine\run;
 
@@ -25,15 +26,28 @@ public function __construct()
 
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
+        /**
+         * @var null|Throwable
+         */
+        $exception = null;
+
         $result = 0;
 
         /**
          * @var bool
          */
-        $coroutineResult = run(function () use ($input, $output, &$result) {
-            $result = $this->executeInCoroutine($input, $output);
+        $coroutineResult = run(function () use (&$exception, $input, $output, &$result) {
+            try {
+                $result = $this->executeInCoroutine($input, $output);
+            } catch (Throwable $throwable) {
+                $exception = $throwable;
+            }
         });
 
+        if ($exception) {
+            throw $exception;
+        }
+
         if (!$coroutineResult) {
             return Command::FAILURE;
         }

src/DependencyInjectionContainer.php

@@ -198,11 +198,14 @@ public function registerSingletons(): void
         foreach ($this->dependencyProviders as $providedClassName => $dependencyProvider) {
             if ($dependencyProvider->grantsFeature && !$this->wantedFeatures->contains($dependencyProvider->grantsFeature)) {
                 $this->disabledFeatureProviders->put($providedClassName, $dependencyProvider->grantsFeature);
-                $this->dependencyProviders->remove($providedClassName);
             } elseif ($dependencyProvider->collection) {
                 $this->addToCollection($dependencyProvider->collection, $dependencyProvider);
             }
         }
+
+        foreach ($this->disabledFeatureProviders->keys() as $providedClassName) {
+            $this->dependencyProviders->remove($providedClassName);
+        }
     }
 
     private function addToCollection(SingletonCollectionInterface $collectionName, DependencyProvider $dependencyProvider): void

src/EsbuildMetaBuilder.php

@@ -9,6 +9,7 @@
 use Generator;
 use LogicException;
 use RuntimeException;
+use Swoole\Coroutine;
 
 #[Singleton]
 readonly class EsbuildMetaBuilder
@@ -136,7 +137,13 @@ private function getEsbuildMetaContents(string $esbuildMetafile): string
             throw new RuntimeException('Esbuild meta manifest is not readable: '.$esbuildMetafile);
         }
 
-        return file_get_contents($esbuildMetafile);
+        $contents = Coroutine::readFile($esbuildMetafile);
+
+        if (!is_string($contents)) {
+            throw new RuntimeException('Unable to read esbuild manifest: '.$esbuildMetafile);
+        }
+
+        return $contents;
     }
 
     private function getEsbuildMetaDecoded(string $esbuildMetafile): object

src/SingletonProvider/ConfigurationProvider/OAuth2ConfigurationProvider.php

@@ -6,11 +6,14 @@
 
 use Defuse\Crypto\Key;
 use Distantmagic\Resonance\Attribute\Singleton;
+use Distantmagic\Resonance\Feature;
 use Distantmagic\Resonance\OAuth2Configuration;
 use Distantmagic\Resonance\SingletonProvider\ConfigurationProvider;
 use League\OAuth2\Server\CryptKey;
 use Nette\Schema\Expect;
 use Nette\Schema\Schema;
+use RuntimeException;
+use Swoole\Coroutine;
 
 /**
  * @template-extends ConfigurationProvider<OAuth2Configuration, object{
@@ -23,7 +26,10 @@
  *     session_key_state: string,
  * }>
  */
-#[Singleton(provides: OAuth2Configuration::class)]
+#[Singleton(
+    grantsFeature: Feature::OAuth2,
+    provides: OAuth2Configuration::class,
+)]
 final readonly class OAuth2ConfigurationProvider extends ConfigurationProvider
 {
     protected function getConfigurationKey(): string
@@ -46,8 +52,14 @@ protected function getSchema(): Schema
 
     protected function provideConfiguration($validatedData): OAuth2Configuration
     {
+        $encryptionKeyContent = Coroutine::readFile($validatedData->encryption_key);
+
+        if (!is_string($encryptionKeyContent)) {
+            throw new RuntimeException('Unable to read encrpytion key file: '.$validatedData->encryption_key);
+        }
+
         return new OAuth2Configuration(
-            encryptionKey: Key::loadFromAsciiSafeString(file_get_contents($validatedData->encryption_key)),
+            encryptionKey: Key::loadFromAsciiSafeString($encryptionKeyContent),
             jwtSigningKeyPrivate: new CryptKey(
                 DM_ROOT.'/'.$validatedData->jwt_signing_key_private,
                 $validatedData->jwt_signing_key_passphrase,

src/StaticPageLayoutAggregate.php

@@ -6,6 +6,7 @@
 
 use Ds\Map;
 use Generator;
+use Throwable;
 
 readonly class StaticPageLayoutAggregate
 {
@@ -24,10 +25,17 @@ public function __construct()
      */
     public function render(StaticPage $staticPage): Generator
     {
-        yield from $this
-            ->selectLayout($staticPage)
-            ->renderStaticPage($staticPage)
-        ;
+        try {
+            yield from $this
+                ->selectLayout($staticPage)
+                ->renderStaticPage($staticPage)
+            ;
+        } catch (Throwable $throwable) {
+            throw new StaticPageRenderingException(sprintf(
+                'Error while rendering static page: %s',
+                $staticPage->getBasename(),
+            ), 0, $throwable);
+        }
     }
 
     public function selectLayout(StaticPage $staticPage): StaticPageLayoutInterface