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,32 @@ 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: 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: test/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/controllers/ApiController.php

@@ -0,0 +1,149 @@
+<?php
+
+namespace Icinga\Module\Notifications\Controllers;
+
+use Exception;
+use GuzzleHttp\Psr7\Response;
+use GuzzleHttp\Psr7\ServerRequest;
+use Icinga\Application\Logger;
+use Icinga\Exception\Http\HttpBadRequestException;
+use Icinga\Exception\Http\HttpExceptionInterface;
+use Icinga\Exception\IcingaException;
+use Icinga\Exception\Json\JsonEncodeException;
+use Icinga\Module\Notifications\Api\V1\OpenApi;
+use Icinga\Util\Json;
+use Icinga\Web\Request;
+use ipl\Stdlib\Str;
+use ipl\Web\Compat\CompatController;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+use Throwable;
+use Zend_Controller_Request_Exception;
+
+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 JsonEncodeException
+     */
+    public function indexAction(): never
+    {
+        try {
+            $this->assertPermission('notifications/api');
+
+            $request = $this->getRequest();
+            if (
+                ! $request->isApiRequest()
+                && strtolower($request->getParam('endpoint')) !== (new OpenApi())->getEndpoint() // for browser query
+            ) {
+                $this->httpBadRequest('No API request');
+            }
+
+            $params = $request->getParams();
+            $version = ucfirst($params['version']);
+            $endpoint = ucfirst(Str::camel($params['endpoint']));
+            $identifier = $params['identifier'] ?? null;
+
+            $module = (($moduleName = $request->getModuleName()) !== null)
+                ? 'Module\\' . ucfirst($moduleName) . '\\'
+                : '';
+            $className = sprintf('Icinga\\%sApi\\%s\\%s', $module, $version, $endpoint);
+
+            // TODO: works only for V1 right now
+            if (! class_exists($className) || ! is_subclass_of($className, RequestHandlerInterface::class)) {
+                $this->httpNotFound("Endpoint $endpoint does not exist.");
+            }
+
+            $httpMethod = $request->getMethod();
+            $serverRequest = (new ServerRequest(
+                $httpMethod,
+                $request->getRequestUri(),
+                serverParams: $request->getServer(),
+            ))
+                ->withAttribute('identifier', $identifier);
+
+            if ($contentType = $request->getHeader('Content-Type')) {
+                $serverRequest = $serverRequest->withHeader('Content-Type', $contentType);
+            }
+
+            if ($httpMethod === 'POST' || $httpMethod === 'PUT') {
+                $serverRequest = $serverRequest->withParsedBody($this->getRequestBody($request));
+            }
+
+            $response = (new $className())->handle($serverRequest);
+        } catch (HttpExceptionInterface $e) {
+            $response = new Response(
+                $e->getStatusCode(),
+                array_merge($e->getHeaders(), ['Content-Type' => 'application/json']),
+                Json::sanitize(['message' => $e->getMessage()])
+            );
+        } catch (Throwable $e) {
+            Logger::error($e);
+            Logger::debug(IcingaException::getConfidentialTraceAsString($e));
+            $response = new Response(
+                500,
+                ['Content-Type' => 'application/json'],
+                Json::sanitize(['message' => 'An error occurred, please chack the log.'])
+            );
+        } finally {
+            $this->emitResponse($response);
+        }
+
+        exit;
+    }
+
+    /**
+     * Validate that the request has an appropriate body.
+     *
+     * @param Request $request The request object to validate.
+     *
+     * @return ?array The validated JSON content as an associative array.
+     *
+     * @throws HttpBadRequestException
+     */
+    private function getRequestBody(Request $request): ?array
+    {
+        try {
+            $data = $request->getPost();
+            if ($data !== null && ! is_array($data)) {
+                $this->httpBadRequest('Invalid request body: given content is not a valid JSON');
+            }
+        } catch (Exception) {
+            $this->httpBadRequest('Invalid request body: given content is not a valid JSON');
+        }
+
+        return $data;
+    }
+
+    /**
+     * 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

@@ -24,6 +24,7 @@
 use ipl\Validator\EmailAddressValidator;
 use ipl\Web\Common\CsrfCounterMeasure;
 use ipl\Web\Compat\CompatForm;
+use Ramsey\Uuid\Uuid;
 
 /**
  * @phpstan-type ChannelOptionConfig array{
@@ -213,6 +214,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\Compat\CompatForm;
 use ipl\Web\FormElement\TermInput;
 use ipl\Web\FormElement\TermInput\Term;
+use Ramsey\Uuid\Uuid;
 
 class ContactGroupForm extends CompatForm
 {
@@ -181,7 +182,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')

library/Notifications/Api/ApiCore.php

@@ -0,0 +1,125 @@
+<?php
+
+/* Icinga Notifications Web | (c) 2025 Icinga GmbH | GPLv2 */
+
+namespace Icinga\Module\Notifications\Api;
+
+use GuzzleHttp\Psr7\Response;
+use Icinga\Exception\Http\HttpException;
+use Icinga\Module\Notifications\Common\HttpMethod;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Message\StreamInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+use ValueError;
+
+/**
+ * Abstract base class for API endpoints.
+ *
+ * This class provides the base functionality for handling API requests,
+ */
+abstract class ApiCore
+{
+    /**
+     * Endpoint based request handling.
+     *
+     * @param ServerRequestInterface $request
+     *
+     * @return ResponseInterface
+     */
+    abstract protected function handleRequest(ServerRequestInterface $request): ResponseInterface;
+
+    /**
+     * Get the name of the API endpoint.
+     *
+     * @return string
+     */
+    abstract public function getEndpoint(): string;
+
+    /**
+     * The main entry point for processing API requests.
+     *
+     * @param ServerRequestInterface $request The incoming server request.
+     *
+     * @return ResponseInterface The response generated by the invoked method.
+     *
+     * @throws HttpException If the requested method does not exist.
+     */
+    public function handle(ServerRequestInterface $request): ResponseInterface
+    {
+        try {
+            $httpMethod = HttpMethod::fromRequest($request);
+        } catch (ValueError) {
+            throw (new HttpException(405, sprintf('HTTP method %s is not supported', $request->getMethod())))
+                ->setHeader('Allow', implode(', ', $this->getAllowedMethods()));
+        }
+
+        $request = $request->withAttribute('httpMethod', $httpMethod);
+
+        if (! in_array($httpMethod->uppercase(), $this->getAllowedMethods())) {
+            throw (new HttpException(
+                405,
+                sprintf('Method %s is not supported for endpoint %s', $httpMethod->uppercase(), $this->getEndpoint())
+            ))
+                ->setHeader('Allow', implode(', ', $this->getAllowedMethods()));
+        }
+
+        $this->assertValidRequest($request);
+
+        return $this->handleRequest($request);
+    }
+
+    /**
+     * Validate the incoming request.
+     *
+     * Override to implement specific request validation logic.
+     *
+     * @param ServerRequestInterface $request The incoming server request to validate.
+     *
+     * @return void
+     */
+    protected function assertValidRequest(ServerRequestInterface $request): void
+    {
+    }
+
+    /**
+     * Get allowed HTTP methods for the API.
+     *
+     * @return array
+     */
+    protected function getAllowedMethods(): array
+    {
+        $methods = [];
+
+        foreach (HttpMethod::cases() as $method) {
+            if (method_exists($this, $method->lowercase())) {
+                $methods[] = $method->uppercase();
+            }
+        }
+
+        return $methods;
+    }
+
+    /**
+     * Create a Response object.
+     *
+     * @param int $status The HTTP status code.
+     * @param array $headers An associative array of HTTP headers.
+     * @param ?(StreamInterface|resource|string) $body The response body.
+     * @param string $version The HTTP version.
+     * @param ?string $reason The reason phrase (optional).
+     *
+     * @return ResponseInterface
+     */
+    protected function createResponse(
+        int $status = 200,
+        array $headers = [],
+        $body = null,
+        string $version = '1.1',
+        ?string $reason = null
+    ): ResponseInterface {
+        $headers['Content-Type'] = 'application/json';
+
+        return new Response($status, $headers, $body, $version, $reason);
+    }
+}