Nodarx/server
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Projects Releases Activity

refactor(modules): configure integrations through runtime contexts

Browse Source 
Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
This commit is contained in:
Sebastian Krupinski
2026-08-31 22:40:25 -04:00
parent 9fcfe32ea7
commit 8cedd8a18a
16 changed files with 378 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files
core/lib/Controllers/InitController.php
+10 -5
View File
@@ -6,6 +6,7 @@ use KTXC\Http\Request\Request;
use KTXC\Http\Response\JsonResponse;
use KTXC\L10N\LocaleResolver;
use KTXC\Module\ModuleManager;
use KTXC\Module\Configuration\BrowserModuleContext;
use KTXC\Security\Authorization\PermissionChecker;
use KTXC\Service\UserAccountsService;
use KTXC\Context\IdentityContextInterface;
@@ -30,7 +31,11 @@ class InitController extends ControllerAbstract
$configuration = [];
// modules - filter by permissions
$configuration['modules'] = [];
$browserContext = new BrowserModuleContext(
$this->tenantContext->requireIdentifier(),
$this->identityContext->requireIdentifier(),
);
foreach ($this->moduleManager->list(true, true) as $module) {
// Check if user has permission to view this module
// Allow access if user has: {module_handle}, {module_handle}.*, or * permission
@@ -39,12 +44,12 @@ class InitController extends ControllerAbstract
continue;
}
$integrations = $module->registerBI();
if ($integrations !== null) {
$configuration['modules'][$handle] = $integrations;
}
$module->configure($browserContext);
}
$configuration['modules'] = $browserContext->modules();
$configuration = array_merge($configuration, $browserContext->configuration());
// localization
$configuration['l10n'] = [
'locale' => $this->localeResolver->resolve($request),
core/lib/Module/Configuration/BrowserModuleContext.php
+93
View File
@@ -0,0 +1,93 @@
<?php
declare(strict_types=1);
namespace KTXC\Module\Configuration;
use InvalidArgumentException;
use LogicException;
use KTXF\Module\Configuration\BrowserModuleContextInterface;
use KTXF\Module\Configuration\ModuleContextType;
use KTXF\Module\ModuleInstanceInterface;
final class BrowserModuleContext implements BrowserModuleContextInterface
{
private const RESERVED_KEYS = ['modules', 'tenant', 'user', 'l10n'];
/** @var array<string,array<string,mixed>> */
private array $modules = [];
/** @var array<string,mixed> */
private array $configuration = [];
public function __construct(
private readonly string $tenantIdentifier,
private readonly string $identityIdentifier,
) {
}
public function type(): ModuleContextType
{
return ModuleContextType::Browser;
}
public function registerModule(
ModuleInstanceInterface $module,
string $namespace,
?string $boot = null,
): void {
if (trim($namespace) === '' || ($boot !== null && trim($boot) === '')) {
throw new InvalidArgumentException('Browser namespace must not be empty and boot path must be null or non-empty');
}
$handle = $module->handle();
if (isset($this->modules[$handle])) {
throw new LogicException("Browser module '{$handle}' is already registered");
}
$entry = [
'handle' => $handle,
'namespace' => $namespace,
'version' => $module->version(),
'label' => $module->label(),
'author' => $module->author(),
'description' => $module->description(),
];
if ($boot !== null) {
$entry['boot'] = $boot;
}
$this->modules[$handle] = $entry;
}
public function set(string $key, mixed $value): void
{
if (trim($key) === '') {
throw new InvalidArgumentException('Browser configuration key must not be empty');
}
if (in_array($key, self::RESERVED_KEYS, true) || array_key_exists($key, $this->configuration)) {
throw new LogicException("Browser configuration '{$key}' is already reserved or registered");
}
$this->configuration[$key] = $value;
}
public function tenantIdentifier(): string
{
return $this->tenantIdentifier;
}
public function identityIdentifier(): string
{
return $this->identityIdentifier;
}
public function modules(): array
{
return $this->modules;
}
public function configuration(): array
{
return $this->configuration;
}
}
core/lib/Module/Configuration/ConsoleModuleContext.php
+34
View File
@@ -0,0 +1,34 @@
<?php
declare(strict_types=1);
namespace KTXC\Module\Configuration;
use InvalidArgumentException;
use KTXF\Module\Configuration\ConsoleModuleContextInterface;
use KTXF\Module\Configuration\ModuleContextType;
final class ConsoleModuleContext implements ConsoleModuleContextInterface
{
/** @var array<class-string,true> */
private array $commands = [];
public function type(): ModuleContextType
{
return ModuleContextType::Console;
}
public function registerCommand(string $command): void
{
if (trim($command) === '') {
throw new InvalidArgumentException('Console command class must not be empty');
}
$this->commands[$command] = true;
}
public function commands(): array
{
return array_keys($this->commands);
}
}
core/lib/Module/Module.php
+22 -11
View File
@@ -4,6 +4,7 @@ namespace KTXC\Module;
use KTXC\Console\Firewall\FirewallMaintenanceCommand;
use KTXC\Console\Firewall\FirewallSetupCommand;
use KTXC\Preview\PreviewManager;
use KTXC\Service\FirewallService;
use KTXC\Service\SystemFirewallLogService;
use KTXC\Service\SystemFirewallRuleService;
@@ -25,8 +26,9 @@ use KTXC\Security\Event\RateLimitExceededEvent;
use KTXC\Security\Event\SuspiciousActivityEvent;
use KTXF\Event\DeliveryMode;
use KTXF\Event\EventListenerRegistrarInterface;
use KTXF\Module\ModuleBrowserInterface;
use KTXF\Module\ModuleConsoleInterface;
use KTXF\Module\Configuration\BrowserModuleContextInterface;
use KTXF\Module\Configuration\ConsoleModuleContextInterface;
use KTXF\Module\Configuration\ModuleContextInterface;
use KTXF\Module\ModuleInstanceAbstract;
/**
@@ -34,10 +36,11 @@ use KTXF\Module\ModuleInstanceAbstract;
*
* Provides core system functionality and permissions
*/
class Module extends ModuleInstanceAbstract implements ModuleConsoleInterface, ModuleBrowserInterface
class Module extends ModuleInstanceAbstract
{
public function __construct(
private readonly EventListenerRegistrarInterface $events,
private readonly PreviewManager $previews,
) {
}
@@ -213,9 +216,20 @@ class Module extends ModuleInstanceAbstract implements ModuleConsoleInterface, M
];
}
public function registerCI(): array
public function configure(ModuleContextInterface $context): void
{
return [
if ($context instanceof BrowserModuleContextInterface) {
$context->set(
'preview',
$this->previews->availability($context->tenantIdentifier()),
);
}
if (!$context instanceof ConsoleModuleContextInterface) {
return;
}
foreach ([
FirewallSetupCommand::class,
FirewallMaintenanceCommand::class,
\KTXC\Console\Event\EventsDebugCommand::class,
@@ -240,11 +254,8 @@ class Module extends ModuleInstanceAbstract implements ModuleConsoleInterface, M
\KTXC\Console\Role\RoleDeleteCommand::class,
\KTXC\Console\Role\RoleAssignCommand::class,
\KTXC\Console\Role\RoleRevokeCommand::class,
];
}
public function registerBI(): array
{
return [];
] as $command) {
$context->registerCommand($command);
}
}
}
core/lib/Module/ModuleObject.php
+3 -15
View File
@@ -4,8 +4,7 @@ namespace KTXC\Module;
use JsonSerializable;
use KTXC\Module\Store\ModuleEntry;
use KTXF\Module\ModuleBrowserInterface;
use KTXF\Module\ModuleConsoleInterface;
use KTXF\Module\Configuration\ModuleContextInterface;
use KTXF\Module\ModuleInstanceInterface;
/**
@@ -175,20 +174,9 @@ class ModuleObject implements JsonSerializable
$this->instance?->upgrade();
}
public function registerBI(): array | null
public function configure(ModuleContextInterface $context): void
{
if ($this->instance instanceof ModuleBrowserInterface) {
return $this->instance->registerBI();
}
return null;
}
public function registerCI(): array | null
{
if ($this->instance instanceof ModuleConsoleInterface) {
return $this->instance->registerCI();
}
return null;
$this->instance?->configure($context);
}
}
core/lib/Runtime/Console/ConsoleRuntime.php
+6 -8
View File
@@ -7,8 +7,8 @@ namespace KTXC\Runtime\Console;
use KTXC\Application\Execution\ExecutionDescriptor;
use KTXC\Kernel;
use KTXC\KernelInterface;
use KTXC\Module\Configuration\ConsoleModuleContext;
use KTXC\Module\ModuleManager;
use KTXF\Module\ModuleConsoleInterface;
use Psr\Container\ContainerInterface;
use Symfony\Component\Console\Application as ConsoleApplication;
use Symfony\Component\Console\Attribute\AsCommand;
@@ -34,15 +34,13 @@ final class ConsoleRuntime
/** @var ModuleManager $moduleManager */
$moduleManager = $container->get(ModuleManager::class);
$moduleContext = new ConsoleModuleContext();
foreach ($moduleManager->list() as $module) {
$instance = $module->instance();
if (!$instance instanceof ModuleConsoleInterface) {
continue;
}
$module->configure($moduleContext);
}
foreach ($instance->registerCI() as $commandClass) {
$this->registerCommand($console, $container, $commandClass);
}
foreach ($moduleContext->commands() as $commandClass) {
$this->registerCommand($console, $container, $commandClass);
}
return $console->run($input, $output);
shared/lib/Module/Configuration/BrowserModuleContextInterface.php
+28
View File
@@ -0,0 +1,28 @@
<?php
declare(strict_types=1);
namespace KTXF\Module\Configuration;
use KTXF\Module\ModuleInstanceInterface;
interface BrowserModuleContextInterface extends ModuleContextInterface
{
public function registerModule(
ModuleInstanceInterface $module,
string $namespace,
?string $boot = null,
): void;
public function set(string $key, mixed $value): void;
public function tenantIdentifier(): string;
public function identityIdentifier(): string;
/** @return array<string,array<string,mixed>> */
public function modules(): array;
/** @return array<string,mixed> */
public function configuration(): array;
}
shared/lib/Module/Configuration/ConsoleModuleContextInterface.php
+14
View File
@@ -0,0 +1,14 @@
<?php
declare(strict_types=1);
namespace KTXF\Module\Configuration;
interface ConsoleModuleContextInterface extends ModuleContextInterface
{
/** @param class-string $command */
public function registerCommand(string $command): void;
/** @return list<class-string> */
public function commands(): array;
}
shared/lib/Module/Configuration/ModuleContextInterface.php
+10
View File
@@ -0,0 +1,10 @@
<?php
declare(strict_types=1);
namespace KTXF\Module\Configuration;
interface ModuleContextInterface
{
public function type(): ModuleContextType;
}
shared/lib/Module/Configuration/ModuleContextType.php
+11
View File
@@ -0,0 +1,11 @@
<?php
declare(strict_types=1);
namespace KTXF\Module\Configuration;
enum ModuleContextType: string
{
case Browser = 'browser';
case Console = 'console';
}
shared/lib/Module/ModuleBrowserInterface.php
-13
View File
@@ -1,13 +0,0 @@
<?php
declare(strict_types=1);
namespace KTXF\Module;
/**
* Module Browser Interface
*/
interface ModuleBrowserInterface
{
public function registerBI(): array;
}
shared/lib/Module/ModuleConsoleInterface.php
-13
View File
@@ -1,13 +0,0 @@
<?php
declare(strict_types=1);
namespace KTXF\Module;
/**
* Module Console Interface
*/
interface ModuleConsoleInterface
{
public function registerCI(): array;
}
shared/lib/Module/ModuleInstanceAbstract.php
+7
View File
@@ -2,6 +2,8 @@
namespace KTXF\Module;
use KTXF\Module\Configuration\ModuleContextInterface;
abstract class ModuleInstanceAbstract implements ModuleInstanceInterface
{
// mandatory methods that must be implemented by each concrete module
@@ -46,6 +48,11 @@ abstract class ModuleInstanceAbstract implements ModuleInstanceInterface
// Override in specific modules if needed
}
public function configure(ModuleContextInterface $context): void
{
// Override when the module supplies browser or console integrations.
}
/**
* Permissions provided by this module
*
shared/lib/Module/ModuleInstanceInterface.php
+7
View File
@@ -2,8 +2,15 @@
namespace KTXF\Module;
use KTXF\Module\Configuration\ModuleContextInterface;
interface ModuleInstanceInterface
{
/**
* Declare the integrations supplied by this module.
*/
public function configure(ModuleContextInterface $context): void;
/**
* Get module version
*/
tests/php/Unit/Module/CoreModuleTest.php
+48 -6
View File
@@ -8,6 +8,10 @@ use KTXC\Console\Firewall\FirewallMaintenanceCommand;
use KTXC\Console\Firewall\FirewallSetupCommand;
use KTXC\Console\Event\EventsDebugCommand;
use KTXC\Module\Module;
use KTXC\Module\Configuration\BrowserModuleContext;
use KTXC\Module\Configuration\ConsoleModuleContext;
use KTXC\Preview\PreviewManager;
use KTXC\Resource\ProviderManager;
use KTXC\Service\FirewallService;
use KTXC\Service\SystemFirewallRuleService;
use KTXC\Service\SystemFirewallLogService;
@@ -15,6 +19,8 @@ use KTXC\Service\TenantFirewallLogService;
use KTXC\Service\TenantFirewallStatusService;
use KTXC\Service\SystemFirewallStatusService;
use KTXC\Service\TenantFirewallRuleService;
use KTXC\Service\TenantService;
use KTXC\SystemStore\SystemStoreManager;
use KTXC\Event\EventListenerRegistry;
use KTXC\Security\Event\AccessDeniedEvent;
use KTXC\Security\Event\AuthenticationFailedEvent;
@@ -32,6 +38,8 @@ use KTXF\Event\DeliveryMode;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\Attributes\TestDox;
use PHPUnit\Framework\TestCase;
use Psr\Container\ContainerInterface;
use Psr\Log\LoggerInterface;
final class CoreModuleTest extends TestCase
{
@@ -40,7 +48,7 @@ final class CoreModuleTest extends TestCase
public function registersListeners(): void
{
$registry = new EventListenerRegistry();
$module = new Module($registry);
$module = $this->module($registry);
$module->boot();
$definitions = $registry->definitions();
@@ -83,18 +91,21 @@ final class CoreModuleTest extends TestCase
#[TestDox('Core exposes the event registry debug command')]
public function exposesDebugCommand(): void
{
$module = new Module(new EventListenerRegistry());
$module = $this->module();
$context = new ConsoleModuleContext();
$module->configure($context);
$commands = $context->commands();
self::assertContains(EventsDebugCommand::class, $module->registerCI());
self::assertContains(FirewallSetupCommand::class, $module->registerCI());
self::assertContains(FirewallMaintenanceCommand::class, $module->registerCI());
self::assertContains(EventsDebugCommand::class, $commands);
self::assertContains(FirewallSetupCommand::class, $commands);
self::assertContains(FirewallMaintenanceCommand::class, $commands);
}
#[Test]
#[TestDox('Core registers dedicated system firewall permissions')]
public function registersSystemFirewallPermissions(): void
{
$permissions = (new Module(new EventListenerRegistry()))->permissions();
$permissions = $this->module()->permissions();
self::assertArrayHasKey(SystemFirewallRuleService::PERMISSION_READ, $permissions);
self::assertArrayHasKey(SystemFirewallRuleService::PERMISSION_MANAGE, $permissions);
@@ -107,4 +118,35 @@ final class CoreModuleTest extends TestCase
self::assertArrayHasKey(SystemFirewallStatusService::PERMISSION_MAINTENANCE_READ, $permissions);
self::assertArrayHasKey(SystemFirewallStatusService::PERMISSION_SETTINGS_MANAGE, $permissions);
}
#[Test]
#[TestDox('Core resolves preview browser configuration')]
public function resolvesPreviewBrowserConfiguration(): void
{
$module = $this->module();
$context = new BrowserModuleContext('tenant-id', 'identity-id');
$module->configure($context);
self::assertSame([
'preview' => [
'enabled' => false,
'storage' => false,
'generation' => false,
],
], $context->configuration());
}
private function module(?EventListenerRegistry $registry = null): Module
{
$tenants = $this->createStub(TenantService::class);
$providers = new ProviderManager($this->createStub(ContainerInterface::class));
$previews = new PreviewManager(
$tenants,
$providers,
new SystemStoreManager($tenants, $providers),
$this->createStub(LoggerInterface::class),
);
return new Module($registry ?? new EventListenerRegistry(), $previews);
}
}
tests/php/Unit/Module/ModuleContextTest.php
+85
View File
@@ -0,0 +1,85 @@
<?php
declare(strict_types=1);
namespace KTXT\Unit\Module;
use KTXC\Module\Configuration\BrowserModuleContext;
use KTXC\Module\Configuration\ConsoleModuleContext;
use KTXF\Module\Configuration\BrowserModuleContextInterface;
use KTXF\Module\Configuration\ConsoleModuleContextInterface;
use KTXF\Module\Configuration\ModuleContextInterface;
use KTXF\Module\Configuration\ModuleContextType;
use KTXF\Module\ModuleInstanceAbstract;
use LogicException;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;
final class ModuleContextTest extends TestCase
{
#[Test]
public function moduleRegistersItselfWithTheActiveContext(): void
{
$module = new TestContextModule();
$browser = new BrowserModuleContext('tenant-id', 'identity-id');
$console = new ConsoleModuleContext();
$module->configure($browser);
$module->configure($console);
self::assertSame(
[
'test_context' => [
'handle' => 'test_context',
'namespace' => 'TestContext',
'version' => '0.0.1',
'label' => 'Test Context',
'author' => 'Ktrix',
'description' => 'Tests module contexts',
'boot' => 'static/module.mjs',
],
],
$browser->modules(),
);
self::assertSame(
['test' => ['tenant' => 'tenant-id', 'identity' => 'identity-id']],
$browser->configuration(),
);
self::assertSame(['ExampleCommand'], $console->commands());
self::assertSame(ModuleContextType::Browser, $browser->type());
self::assertSame(ModuleContextType::Console, $console->type());
}
#[Test]
public function rejectsDuplicateBrowserConfigurationKeys(): void
{
$context = new BrowserModuleContext('tenant-id', 'identity-id');
$context->set('test', true);
$this->expectException(LogicException::class);
$context->set('test', false);
}
}
final class TestContextModule extends ModuleInstanceAbstract
{
public function handle(): string { return 'test_context'; }
public function version(): string { return '0.0.1'; }
public function label(): string { return 'Test Context'; }
public function description(): string { return 'Tests module contexts'; }
public function author(): string { return 'Ktrix'; }
public function configure(ModuleContextInterface $context): void
{
if ($context instanceof BrowserModuleContextInterface) {
$context->registerModule($this, 'TestContext', 'static/module.mjs');
$context->set('test', [
'tenant' => $context->tenantIdentifier(),
'identity' => $context->identityIdentifier(),
]);
}
if ($context instanceof ConsoleModuleContextInterface) {
$context->registerCommand('ExampleCommand');
$context->registerCommand('ExampleCommand');
}
}
}