Feature/http api new approach

.github/workflows/php.yml

@@ -54,6 +54,36 @@ jobs:
         php: ['8.2', '8.3', '8.4']
         os: ['ubuntu-latest']
 
+    services:
+      mysql:
+        image: mariadb
+        env:
+          MYSQL_ROOT_PASSWORD: root
+          MYSQL_DATABASE: icinga_unittest
+          MYSQL_USER: icinga_unittest
+          MYSQL_PASSWORD: icinga_unittest
+        options: >-
+          --health-cmd "mariadb -s -uroot -proot -e'SHOW DATABASES;' 2> /dev/null | grep icinga_unittest > test"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 3306/tcp
+
+      pgsql:
+        image: postgres
+        env:
+          POSTGRES_USER: icinga_unittest
+          POSTGRES_PASSWORD: icinga_unittest
+          POSTGRES_DB: icinga_unittest
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432/tcp
+
     steps:
       - name: Checkout code base
         uses: actions/checkout@v4
@@ -75,7 +105,36 @@ jobs:
           git clone --depth 1 -b snapshot/nightly https://github.com/Icinga/icinga-php-library.git _libraries/ipl
           git clone --depth 1 -b snapshot/nightly https://github.com/Icinga/icinga-php-thirdparty.git _libraries/vendor
 
+      - name: Checkout Icinga Notifications Daemon
+        run: |
+          git clone --depth 1 -b main https://github.com/Icinga/icinga-notifications.git _notifications_daemon
+
+      - name: Initialize Icinga Web
+        run: |
+          mysql --host="127.0.0.1" --port="${{ job.services.mysql.ports['3306'] }}" --user="root" --password="root" \
+            -e "CREATE DATABASE icingaweb; CREATE USER icingaweb@'%' IDENTIFIED BY 'icingaweb'; GRANT ALL ON icingaweb.* TO icingaweb@'%';"
+          PGPASSWORD=icinga_unittest psql --host="127.0.0.1" --port="${{ job.services.pgsql.ports['5432'] }}" \
+            --username "icinga_unittest" -c "CREATE DATABASE icingaweb;"
+
       - name: PHPUnit
         env:
           ICINGAWEB_LIBDIR: _libraries
+          ICINGAWEB_PATH: _icingaweb2
+          ICINGA_NOTIFICATIONS_SCHEMA: _notifications_daemon/schema
+          MYSQL_TESTDB: icinga_unittest
+          MYSQL_TESTDB_HOST: 127.0.0.1
+          MYSQL_TESTDB_PORT: ${{ job.services.mysql.ports['3306'] }}
+          MYSQL_TESTDB_USER: icinga_unittest
+          MYSQL_TESTDB_PASSWORD: icinga_unittest
+          MYSQL_ICINGAWEBDB: icingaweb
+          MYSQL_ICINGAWEBDB_PASSWORD: icingaweb
+          MYSQL_ICINGAWEBDB_USER: icingaweb
+          PGSQL_TESTDB: icinga_unittest
+          PGSQL_TESTDB_HOST: 127.0.0.1
+          PGSQL_TESTDB_PORT: ${{ job.services.pgsql.ports['5432'] }}
+          PGSQL_TESTDB_USER: icinga_unittest
+          PGSQL_TESTDB_PASSWORD: icinga_unittest
+          PGSQL_ICINGAWEBDB: icingaweb
+          PGSQL_ICINGAWEBDB_PASSWORD: icinga_unittest
+          PGSQL_ICINGAWEBDB_USER: icinga_unittest
         run: phpunit --bootstrap _icingaweb2/test/php/bootstrap.php

application/clicommands/OpenapiCommand.php

@@ -0,0 +1,157 @@
+<?php
+
+/* Icinga Notifications Web | (c) 2025 Icinga GmbH | GPLv2 */
+
+namespace Icinga\Module\Notifications\Clicommands;
+
+use FilesystemIterator;
+use Icinga\Application\Icinga;
+use Icinga\Cli\Command;
+use Icinga\Module\Notifications\Api\OpenApiPreprocessor\AddGlobal401Response;
+use Icinga\Module\Notifications\Common\PsrLogger;
+use OpenApi\Generator;
+use RecursiveDirectoryIterator;
+use RecursiveIteratorIterator;
+use RuntimeException;
+use SplFileInfo;
+use Throwable;
+
+class OpenapiCommand extends Command
+{
+    /**
+     * Generate an OpenAPI JSON file from PHP attributes.
+     *
+     * This command scans a directory for PHP files and generates an OpenAPI JSON file using swagger-php.
+     * The paths are relative to the notifications module directory.
+     *
+     * USAGE:
+     *
+     *   icingacli notifications openapi generate [OPTIONS]
+     *
+     * OPTIONS
+     *
+     * --dir <path/>                            Set the path to the directory to scan for PHP files.
+*                                               Default: /library/Notifications/Api/
+     *
+     * --exclude <comma seperated strings>      Exclude files matching these strings. Wildcard is `*`
+     *
+     * --include <comma seperated strings>      Include files matching these strings. Wildcard is `*`
+     *
+     * --output <path/>                         Set the path to the output file.
+     *                                          Default: /doc/api/api-v1-public.json
+     *
+     * --api-version <version string>           Set the API version.
+     *                                          Default: v1
+     *                                          If the output path is set the --api-version option is ignored.
+     *
+     * --oad-version <version string>           Set the OpenAPI version.
+     *                                          Default: 3.1.0
+     */
+    public function generateAction(): void
+    {
+        $directoryInNotifications = $this->params->get('dir', '/library/Notifications/Api/');
+        $exclude = $this->params->get('exclude');
+        $include = $this->params->get('include');
+        $outputPath = $this->params->get('output');
+        $apiVersion = $this->params->get('api-version', 'v1');
+        $oadVersion = $this->params->get('oad-version', '3.1.0');
+
+        $notificationsPath = Icinga::app()->getModuleManager()->getModule('notifications')->getBaseDir();
+        $directory = $notificationsPath . $directoryInNotifications;
+
+        $baseDirectory = realpath($directory);
+        if ($baseDirectory === false || ! is_dir($baseDirectory)) {
+            throw new RuntimeException("Invalid directory: {$directory}");
+        }
+
+        $exclude = isset($exclude) ? array_map('trim', explode(',', $exclude)) : [];
+        $include = isset($include) ? array_map('trim', explode(',', $include)) : [];
+        $outputPath = $notificationsPath . ($outputPath ?? '/doc/api/api-' . $apiVersion . '-public.json');
+
+        $files = $this->collectPhpFiles($baseDirectory, $exclude, $include);
+
+        echo "→ Scanning directory: $baseDirectory\n";
+        echo "→ Found " . count($files) . " PHP files\n";
+
+        $generator = new Generator(new PsrLogger());
+        $generator->setVersion($oadVersion);
+        $generator->getProcessorPipeline()->add(new AddGlobal401Response());
+
+        try {
+            $openapi = $generator->generate($files);
+
+            $json = $openapi->toJson(
+                JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_INVALID_UTF8_IGNORE | JSON_PRETTY_PRINT
+            );
+
+            $dir = dirname($outputPath);
+            if (! is_dir($dir)) {
+                mkdir($dir, 0755, true);
+            }
+
+            file_put_contents($outputPath, $json);
+
+            echo "OpenAPI documentation written to: $outputPath\n";
+        } catch (Throwable $e) {
+            fwrite(STDERR, "Error generating OpenAPI: " . $e->getMessage() . "\n");
+            exit(1);
+        }
+    }
+
+    /**
+     * Recursively scan a directory for PHP files.
+     */
+    protected function collectPhpFiles(string $baseDirectory, array $exclude, array $include): array
+    {
+        $baseDirectory = rtrim($baseDirectory, '/') . '/';
+        if (! is_dir($baseDirectory)) {
+            throw new RuntimeException("Directory $baseDirectory does not exist");
+        }
+        if (! is_readable($baseDirectory)) {
+            throw new RuntimeException("Directory $baseDirectory is not readable");
+        }
+
+        $files = [];
+        $iterator = new RecursiveIteratorIterator(
+            new RecursiveDirectoryIterator($baseDirectory, FilesystemIterator::SKIP_DOTS)
+        );
+
+        /** @var SplFileInfo $file */
+        foreach ($iterator as $file) {
+            if (! $file->isFile() || $file->getExtension() !== 'php') {
+                continue;
+            }
+
+            $path = $file->getPathname();
+
+            if ($exclude !== [] && $this->matchesAnyPattern($path, $exclude)) {
+                continue;
+            }
+
+            if ($include !== [] && ! $this->matchesAnyPattern($path, $include)) {
+                continue;
+            }
+
+            $files[] = $path;
+        }
+
+        if (empty($files)) {
+            throw new RuntimeException("No PHP files found in $baseDirectory");
+        }
+
+        return $files;
+    }
+
+    protected function matchesAnyPattern(string $string, array $patterns): bool
+    {
+        foreach ($patterns as $pattern) {
+            // Escape regex special chars except for '*'
+            $regex = '/^' . str_replace('\*', '.*', preg_quote($pattern, '/')) . '$/';
+            if (preg_match($regex, $string)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}

application/controllers/ApiController.php

@@ -0,0 +1,76 @@
+<?php
+
+/* Icinga Notifications Web | (c) 2025 Icinga GmbH | GPLv2 */
+
+namespace Icinga\Module\Notifications\Controllers;
+
+use Exception;
+use Icinga\Exception\Http\HttpBadRequestException;
+use Icinga\Module\Notifications\Api\Middleware\DispatchMiddleware;
+use Icinga\Module\Notifications\Api\Middleware\EndpointExecutionMiddleware;
+use Icinga\Module\Notifications\Api\Middleware\ErrorHandlingMiddleware;
+use Icinga\Module\Notifications\Api\Middleware\LegacyRequestConversionMiddleware;
+use Icinga\Module\Notifications\Api\Middleware\MiddlewarePipeline;
+use Icinga\Module\Notifications\Api\Middleware\RoutingMiddleware;
+use Icinga\Module\Notifications\Api\Middleware\ValidationMiddleware;
+use Icinga\Security\SecurityException;
+use Icinga\Web\Request;
+use ipl\Web\Compat\CompatController;
+use Psr\Http\Message\ResponseInterface;
+
+class ApiController extends CompatController
+{
+    /**
+     * Handle API requests and route them to the appropriate endpoint class.
+     *
+     * Processes API requests for the Notifications module, serving as the main entry point for all API interactions.
+     *
+     * @return never
+     * @throws SecurityException
+     */
+    public function indexAction(): never
+    {
+        $this->assertPermission('notifications/api');
+
+        $pipeline = new MiddlewarePipeline([
+            new ErrorHandlingMiddleware(),
+            new LegacyRequestConversionMiddleware($this->getRequest()),
+            new RoutingMiddleware(),
+            new DispatchMiddleware(),
+            new ValidationMiddleware(),
+            new EndpointExecutionMiddleware(),
+        ]);
+
+        $this->emitResponse($pipeline->execute());
+
+        exit;
+    }
+
+    /**
+     * Emit the HTTP response to the client.
+     *
+     * @param ResponseInterface $response The response object to emit.
+     *
+     * @return void
+     */
+    protected function emitResponse(ResponseInterface $response): void
+    {
+        do {
+            ob_end_clean();
+        } while (ob_get_level() > 0);
+
+        http_response_code($response->getStatusCode());
+
+        foreach ($response->getHeaders() as $name => $values) {
+            foreach ($values as $value) {
+                header(sprintf('%s: %s', $name, $value), false);
+            }
+        }
+        header('Content-Type: application/json');
+
+        $body = $response->getBody();
+        while (! $body->eof()) {
+            echo $body->read(8192);
+        }
+    }
+}

application/forms/ChannelForm.php

@@ -25,6 +25,7 @@
 use ipl\Validator\EmailAddressValidator;
 use ipl\Web\Common\CsrfCounterMeasure;
 use ipl\Web\Compat\CompatForm;
+use Ramsey\Uuid\Uuid;
 
 /**
  * @phpstan-type ChannelOptionConfig array{
@@ -214,6 +215,7 @@ public function addChannel(): void
         $channel = $this->getValues();
         $channel['config'] = json_encode($this->filterConfig($channel['config']), JSON_FORCE_OBJECT);
         $channel['changed_at'] = (int) (new DateTime())->format("Uv");
+        $channel['external_uuid'] = Uuid::uuid4()->toString();
 
         $this->db->transaction(function (Connection $db) use ($channel): void {
             $db->insert('channel', $channel);

application/forms/ContactGroupForm.php

@@ -23,6 +23,7 @@
 use ipl\Web\FormDecorator\IcingaFormDecorator;
 use ipl\Web\FormElement\TermInput;
 use ipl\Web\FormElement\TermInput\Term;
+use Ramsey\Uuid\Uuid;
 
 class ContactGroupForm extends CompatForm
 {
@@ -187,7 +188,15 @@ public function addGroup(): int
         $this->db->beginTransaction();
 
         $changedAt = (int) (new DateTime())->format("Uv");
-        $this->db->insert('contactgroup', ['name' => trim($data['group_name']), 'changed_at' => $changedAt]);
+
+        $this->db->insert(
+            'contactgroup',
+            [
+                'name'          => trim($data['group_name']),
+                'changed_at'    => $changedAt,
+                'external_uuid' => Uuid::uuid4()->toString()
+            ]
+        );
 
         $groupIdentifier = $this->db->lastInsertId();
 

configuration.php

@@ -42,6 +42,11 @@
     $this->translate('Allow to configure contact groups')
 );
 
+$this->providePermission(
+    'notifications/api',
+    $this->translate('Allow to modify configuration via API')
+);
+
 $this->provideRestriction(
     'notifications/filter/objects',
     $this->translate('Restrict access to the objects that match the filter')

doc/20-REST-API.md

@@ -0,0 +1,27 @@
+# REST API
+
+Icinga Notifications Web provides a REST API that allows you to manage notification-related resources programmatically.
+
+With this API, you can:
+- Manage **contacts** and **contact groups**
+- Read available **notification channels**
+
+This API enables easy integration with external tools, automation workflows, and configuration management systems.
+
+## API Versioning
+
+The API follows a **versioned** structure to ensure backward compatibility and predictable upgrades.
+
+The current and first stable version is: /icingaweb2/notifications/api/v1
+
+Future versions will be accessible under corresponding paths (for example, `/api/v2`), allowing you to migrate at your own pace.
+
+## API Description
+
+The complete API reference for version `v1` is available in [`api/v1.md`](api/v1.md).
+
+It contains an OpenAPI v3.1 description with detailed information about all endpoints, including:
+- Request and response schemas
+- Example payloads
+- Authentication requirements
+- Error handling