feat(app): fresh module-platform, provider, middleware, rule and support implementation

app/Platform/Modules/Console/InstallModuleCommand.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace App\Platform\Modules\Console;
+
+use App\Platform\Modules\Runtime\ModuleInstaller;
+use Illuminate\Console\Command;
+
+/**
+ * Finishes an installation whose module files are already sitting on disk.
+ */
+class InstallModuleCommand extends Command
+{
+    /** @var string */
+    protected $signature = 'install:module {module} {version}';
+
+    /** @var string */
+    protected $description = 'Install cloned module.';
+
+    public function __construct()
+    {
+        parent::__construct();
+    }
+
+    /**
+     * Hand the module name and version to the runtime installer.
+     */
+    public function handle(): int
+    {
+        $name = $this->argument('module');
+        $version = $this->argument('version');
+
+        ModuleInstaller::complete($name, $version);
+
+        return self::SUCCESS;
+    }
+}

app/Platform/Modules/Events/ModuleDisabledEvent.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Platform\Modules\Events;
+
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+/**
+ * Announces that a module has been switched off for this installation.
+ */
+class ModuleDisabledEvent
+{
+    use Dispatchable;
+    use InteractsWithSockets;
+    use SerializesModels;
+
+    /**
+     * Subject of the announcement. Deliberately untyped: the property and the
+     * constructor parameter are a published contract for module listeners.
+     */
+    public $module;
+
+    public function __construct($module)
+    {
+        $this->module = $module;
+    }
+}

app/Platform/Modules/Events/ModuleEnabledEvent.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Platform\Modules\Events;
+
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+/**
+ * Announces that a module has been switched on for this installation.
+ */
+class ModuleEnabledEvent
+{
+    use Dispatchable;
+    use InteractsWithSockets;
+    use SerializesModels;
+
+    /**
+     * Subject of the announcement. Deliberately untyped: the property and the
+     * constructor parameter are a published contract for module listeners.
+     */
+    public $module;
+
+    public function __construct($module)
+    {
+        $this->module = $module;
+    }
+}

app/Platform/Modules/Events/ModuleInstalledEvent.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Platform\Modules\Events;
+
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+/**
+ * Announces that a module's files, migrations and registry row are in place.
+ */
+class ModuleInstalledEvent
+{
+    use Dispatchable;
+    use InteractsWithSockets;
+    use SerializesModels;
+
+    /**
+     * Subject of the announcement. Deliberately untyped: the property and the
+     * constructor parameter are a published contract for module listeners.
+     */
+    public $module;
+
+    public function __construct($module)
+    {
+        $this->module = $module;
+    }
+}

app/Platform/Modules/Http/Controllers/Assets/ScriptController.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace App\Platform\Modules\Http\Controllers\Assets;
+
+use App\Platform\Http\Controller;
+use App\Platform\Modules\Runtime\ModuleAssetVersion;
+use DateTime;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+use InvoiceShelf\Modules\Registry as ModuleRegistry;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+
+class ScriptController extends Controller
+{
+    /**
+     * Stream one script that a module published from its ServiceProvider::boot()
+     * through \InvoiceShelf\Modules\Registry::registerScript($name, $path).
+     *
+     * A "v" query value equal to the hash of the bytes being served earns a
+     * year-long immutable cache; every other request is answered no-store so a
+     * rebuilt asset is never hidden behind a stale copy.
+     *
+     * @throws NotFoundHttpException
+     */
+    public function __invoke(Request $request, string $script): Response
+    {
+        $path = ModuleRegistry::scriptFor($script);
+
+        abort_if($path === null || ! is_file($path), 404);
+
+        $contents = file_get_contents($path);
+
+        abort_if(! is_string($contents), 404);
+
+        $version = ModuleAssetVersion::forContents($contents);
+        $requested = $request->query('v');
+        $matchesServedBytes = is_string($requested) && hash_equals($version, $requested);
+
+        $response = response($contents, 200, ['Content-Type' => 'application/javascript'])
+            ->setLastModified(DateTime::createFromFormat('U', (string) filemtime($path)));
+
+        $response->headers->set(
+            'Cache-Control',
+            $matchesServedBytes ? 'public, max-age=31536000, immutable' : 'no-store'
+        );
+
+        return $response;
+    }
+}

app/Platform/Modules/Http/Controllers/Assets/StyleController.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace App\Platform\Modules\Http\Controllers\Assets;
+
+use App\Platform\Http\Controller;
+use App\Platform\Modules\Runtime\ModuleAssetVersion;
+use DateTime;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+use InvoiceShelf\Modules\Registry as ModuleRegistry;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+
+class StyleController extends Controller
+{
+    /**
+     * Stream one stylesheet that a module published from its
+     * ServiceProvider::boot() through
+     * \InvoiceShelf\Modules\Registry::registerStyle($name, $path).
+     *
+     * A "v" query value equal to the hash of the bytes being served earns a
+     * year-long immutable cache; every other request is answered no-store so a
+     * rebuilt asset is never hidden behind a stale copy.
+     *
+     * @throws NotFoundHttpException
+     */
+    public function __invoke(Request $request, string $style): Response
+    {
+        $path = ModuleRegistry::styleFor($style);
+
+        abort_if($path === null || ! is_file($path), 404);
+
+        $contents = file_get_contents($path);
+
+        abort_if(! is_string($contents), 404);
+
+        $version = ModuleAssetVersion::forContents($contents);
+        $requested = $request->query('v');
+        $matchesServedBytes = is_string($requested) && hash_equals($version, $requested);
+
+        $response = response($contents, 200, ['Content-Type' => 'text/css'])
+            ->setLastModified(DateTime::createFromFormat('U', (string) filemtime($path)));
+
+        $response->headers->set(
+            'Cache-Control',
+            $matchesServedBytes ? 'public, max-age=31536000, immutable' : 'no-store'
+        );
+
+        return $response;
+    }
+}

app/Platform/Modules/Http/Requests/UploadModuleRequest.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace App\Platform\Modules\Http\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class UploadModuleRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, list<string>>
+     */
+    public function rules(): array
+    {
+        return [
+            'avatar' => ['required', 'file', 'mimes:zip', 'max:20000'],
+            'module' => ['required', 'string', 'max:100'],
+        ];
+    }
+}

app/Platform/Modules/Http/Resources/ModuleCollection.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace App\Platform\Modules\Http\Resources;
+
+use Illuminate\Contracts\Support\Arrayable;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\ResourceCollection;
+
+class ModuleCollection extends ResourceCollection
+{
+    /**
+     * Hand back the default mapping over the wrapped module resources.
+     *
+     * @param  Request  $request
+     * @return array|Arrayable|\JsonSerializable
+     */
+    public function toArray($request): array
+    {
+        $modules = parent::toArray($request);
+
+        return $modules;
+    }
+}

app/Platform/Modules/Models/Module.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace App\Platform\Modules\Models;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * Registry row describing one module known to this installation.
+ */
+class Module extends Model
+{
+    use HasFactory;
+
+    protected $table = 'modules';
+
+    protected $guarded = ['id'];
+
+    /**
+     * @return array<string, string>
+     */
+    protected function casts(): array
+    {
+        return [
+            'installed' => 'boolean',
+            'enabled' => 'boolean',
+            'last_failed_at' => 'datetime',
+        ];
+    }
+}

app/Platform/Modules/Runtime/ModuleInstaller.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace App\Platform\Modules\Runtime;
+
+use App\Platform\Modules\Events\ModuleEnabledEvent;
+use App\Platform\Modules\Events\ModuleInstalledEvent;
+use App\Platform\Modules\Models\Module as ModelsModule;
+use Illuminate\Support\Facades\Artisan;
+use Nwidart\Modules\Facades\Module;
+
+class ModuleInstaller
+{
+    /**
+     * Migrate and activate a module already present on disk, write its registry
+     * row, then announce the install and the activation.
+     */
+    public static function complete($module, $version): bool
+    {
+        Module::register();
+
+        Artisan::call(sprintf('module:migrate %s --force', $module));
+        Artisan::call(sprintf('module:enable %s', $module));
+
+        $record = ModelsModule::updateOrCreate(
+            ['name' => $module],
+            ['version' => $version, 'installed' => true, 'enabled' => true]
+        );
+
+        event(new ModuleInstalledEvent($record));
+        event(new ModuleEnabledEvent($record));
+
+        return true;
+    }
+}