feat: implement audit log tables and methods (#129)

src/ahriman/core/database/migrations/m014_auditlog.py

@@ -0,0 +1,38 @@
+#
+# Copyright (c) 2021-2024 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+__all__ = ["steps"]
+
+
+steps = [
+    """
+    create table auditlog (
+        created integer not null,
+        repository text not null,
+        event text not null,
+        object_id text not null,
+        message text,
+        data json
+    )
+    """,
+    """
+    create index auditlog_created_repository_event_object_id
+    on auditlog (created, repository, event, object_id)
+    """,
+]

src/ahriman/core/database/operations/__init__.py

@@ -21,6 +21,7 @@ from ahriman.core.database.operations.auth_operations import AuthOperations
 from ahriman.core.database.operations.build_operations import BuildOperations
 from ahriman.core.database.operations.changes_operations import ChangesOperations
 from ahriman.core.database.operations.dependencies_operations import DependenciesOperations
+from ahriman.core.database.operations.event_operations import EventOperations
 from ahriman.core.database.operations.logs_operations import LogsOperations
 from ahriman.core.database.operations.package_operations import PackageOperations
 from ahriman.core.database.operations.patch_operations import PatchOperations

src/ahriman/core/database/operations/dependencies_operations.py

@@ -39,7 +39,7 @@ class DependenciesOperations(Operations):
             repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
 
         Returns:
-            Dependencies: changes for the package base if available
+            Dependencies: dependencies for the package base if available
         """
         repository_id = repository_id or self._repository_id
 

src/ahriman/core/database/operations/event_operations.py

@@ -0,0 +1,104 @@
+#
+# Copyright (c) 2021-2024 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from sqlite3 import Connection
+
+from ahriman.core.database.operations.operations import Operations
+from ahriman.models.event import Event, EventType
+from ahriman.models.repository_id import RepositoryId
+
+
+class EventOperations(Operations):
+    """
+    operations for audit log table
+    """
+
+    def event_get(self, event: str | EventType | None = None, object_id: str | None = None,
+                  limit: int = -1, offset: int = 0, repository_id: RepositoryId | None = None) -> list[Event]:
+        """
+        get list of events with filters applied
+
+        Args:
+            event(str | EventType | None, optional): filter by event type (Default value = None)
+            object_id(str | None, optional): filter by event object (Default value = None)
+            limit(int, optional): limit records to the specified count, -1 means unlimited (Default value = -1)
+            offset(int, optional): records offset (Default value = 0)
+            repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
+
+        Returns:
+            list[Event]: list of audit log events
+        """
+        repository_id = repository_id or self._repository_id
+
+        def run(connection: Connection) -> list[Event]:
+            return [
+                Event(
+                    event=row["event"],
+                    object_id=row["object_id"],
+                    message=row["message"],
+                    data=row["data"],
+                    created=row["created"],
+                ) for row in connection.execute(
+                    """
+                    select created, event, object_id, message, data from auditlog
+                    where (:event is null or event = :event)
+                      and (:object_id is null or object_id = :object_id)
+                      and repository = :repository
+                      order by created limit :limit offset :offset
+                    """,
+                    {
+                        "event": event,
+                        "object_id": object_id,
+                        "repository": repository_id.id,
+                        "limit": limit,
+                        "offset": offset,
+                    }
+                )
+            ]
+
+        return self.with_connection(run)
+
+    def event_insert(self, event: Event, repository_id: RepositoryId | None = None) -> None:
+        """
+        insert audit log event
+
+        Args:
+            event(Event): event to insert
+            repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
+        """
+        repository_id = repository_id or self._repository_id
+
+        def run(connection: Connection) -> None:
+            connection.execute(
+                """
+                insert into auditlog
+                (created, repository, event, object_id, message, data)
+                values
+                (:created, :repository, :event, :object_id, :message, :data)
+                """,
+                {
+                    "created": event.created,
+                    "repository": repository_id.id,
+                    "event": event.event,
+                    "object_id": event.object_id,
+                    "message": event.message,
+                    "data": event.data,
+                })
+
+        return self.with_connection(run, commit=True)

src/ahriman/core/database/sqlite.py

@@ -26,7 +26,7 @@ from typing import Self
 from ahriman.core.configuration import Configuration
 from ahriman.core.database.migrations import Migrations
 from ahriman.core.database.operations import AuthOperations, BuildOperations, ChangesOperations, \
-    DependenciesOperations, LogsOperations, PackageOperations, PatchOperations
+    DependenciesOperations, EventOperations, LogsOperations, PackageOperations, PatchOperations
 from ahriman.models.repository_id import RepositoryId
 
 
@@ -36,6 +36,7 @@ class SQLite(
         BuildOperations,
         ChangesOperations,
         DependenciesOperations,
+        EventOperations,
         LogsOperations,
         PackageOperations,
         PatchOperations):

src/ahriman/core/status/client.py

@@ -25,6 +25,7 @@ from ahriman.core.database import SQLite
 from ahriman.models.build_status import BuildStatus, BuildStatusEnum
 from ahriman.models.changes import Changes
 from ahriman.models.dependencies import Dependencies
+from ahriman.models.event import Event, EventType
 from ahriman.models.internal_status import InternalStatus
 from ahriman.models.log_record_id import LogRecordId
 from ahriman.models.package import Package
@@ -79,6 +80,37 @@ class Client:
 
         return make_local_client()
 
+    def event_add(self, event: Event) -> None:
+        """
+        create new event
+
+        Args:
+            event(Event): audit log event
+
+        Raises:
+            NotImplementedError: not implemented method
+        """
+        raise NotImplementedError
+
+    def event_get(self, event: str | EventType | None, object_id: str | None,
+                  limit: int = -1, offset: int = 0) -> list[Event]:
+        """
+        retrieve list of events
+
+        Args:
+            event(str | EventType | None): filter by event type
+            object_id(str | None): filter by event object
+            limit(int, optional): limit records to the specified count, -1 means unlimited (Default value = -1)
+            offset(int, optional): records offset (Default value = 0)
+
+        Returns:
+            list[Event]: list of audit log events
+
+        Raises:
+            NotImplementedError: not implemented method
+        """
+        raise NotImplementedError
+
     def package_changes_get(self, package_base: str) -> Changes:
         """
         get package changes

src/ahriman/core/status/local_client.py

@@ -22,6 +22,7 @@ from ahriman.core.status import Client
 from ahriman.models.build_status import BuildStatus, BuildStatusEnum
 from ahriman.models.changes import Changes
 from ahriman.models.dependencies import Dependencies
+from ahriman.models.event import Event, EventType
 from ahriman.models.log_record_id import LogRecordId
 from ahriman.models.package import Package
 from ahriman.models.pkgbuild_patch import PkgbuildPatch
@@ -48,6 +49,31 @@ class LocalClient(Client):
         self.database = database
         self.repository_id = repository_id
 
+    def event_add(self, event: Event) -> None:
+        """
+        create new event
+
+        Args:
+            event(Event): audit log event
+        """
+        self.database.event_insert(event, self.repository_id)
+
+    def event_get(self, event: str | EventType | None, object_id: str | None,
+                  limit: int = -1, offset: int = 0) -> list[Event]:
+        """
+        retrieve list of events
+
+        Args:
+            event(str | EventType | None): filter by event type
+            object_id(str | None): filter by event object
+            limit(int, optional): limit records to the specified count, -1 means unlimited (Default value = -1)
+            offset(int, optional): records offset (Default value = 0)
+
+        Returns:
+            list[Event]: list of audit log events
+        """
+        return self.database.event_get(event, object_id, limit, offset, self.repository_id)
+
     def package_changes_get(self, package_base: str) -> Changes:
         """
         get package changes

src/ahriman/core/status/watcher.py

@@ -27,6 +27,7 @@ from ahriman.core.status import Client
 from ahriman.models.build_status import BuildStatus, BuildStatusEnum
 from ahriman.models.changes import Changes
 from ahriman.models.dependencies import Dependencies
+from ahriman.models.event import Event, EventType
 from ahriman.models.log_record_id import LogRecordId
 from ahriman.models.package import Package
 from ahriman.models.pkgbuild_patch import PkgbuildPatch
@@ -68,6 +69,10 @@ class Watcher(LazyLogging):
         with self._lock:
             return list(self._known.values())
 
+    event_add: Callable[[Event], None]
+
+    event_get: Callable[[str | EventType | None, str | None, int, int], list[Event]]
+
     def load(self) -> None:
         """
         load packages from local database

src/ahriman/core/status/web_client.py

@@ -27,6 +27,7 @@ from ahriman.core.status import Client
 from ahriman.models.build_status import BuildStatus, BuildStatusEnum
 from ahriman.models.changes import Changes
 from ahriman.models.dependencies import Dependencies
+from ahriman.models.event import Event, EventType
 from ahriman.models.internal_status import InternalStatus
 from ahriman.models.log_record_id import LogRecordId
 from ahriman.models.package import Package
@@ -109,6 +110,15 @@ class WebClient(Client, SyncAhrimanClient):
         """
         return f"{self.address}/api/v1/packages/{urlencode(package_base)}/dependencies"
 
+    def _events_url(self) -> str:
+        """
+        get url for the events api
+
+        Returns:
+            str: full url for web service for events
+        """
+        return f"{self.address}/api/v1/events"
+
     def _logs_url(self, package_base: str) -> str:
         """
         get url for the logs api
@@ -157,6 +167,44 @@ class WebClient(Client, SyncAhrimanClient):
         """
         return f"{self.address}/api/v1/status"
 
+    def event_add(self, event: Event) -> None:
+        """
+        create new event
+
+        Args:
+            event(Event): audit log event
+        """
+        with contextlib.suppress(Exception):
+            self.make_request("POST", self._events_url(), params=self.repository_id.query(), json=event.view())
+
+    def event_get(self, event: str | EventType | None, object_id: str | None,
+                  limit: int = -1, offset: int = 0) -> list[Event]:
+        """
+        retrieve list of events
+
+        Args:
+            event(str | EventType | None): filter by event type
+            object_id(str | None): filter by event object
+            limit(int, optional): limit records to the specified count, -1 means unlimited (Default value = -1)
+            offset(int, optional): records offset (Default value = 0)
+
+        Returns:
+            list[Event]: list of audit log events
+        """
+        query = self.repository_id.query() + [("limit", str(limit)), ("offset", str(offset))]
+        if event is not None:
+            query.append(("event", str(event)))
+        if object_id is not None:
+            query.append(("object_id", object_id))
+
+        with contextlib.suppress(Exception):
+            response = self.make_request("GET", self._events_url(), params=query)
+            response_json = response.json()
+
+            return [Event.from_json(event) for event in response_json]
+
+        return []
+
     def package_changes_get(self, package_base: str) -> Changes:
         """
         get package changes
@@ -274,8 +322,9 @@ class WebClient(Client, SyncAhrimanClient):
         Returns:
             list[tuple[float, str]]: package logs
         """
+        query = self.repository_id.query() + [("limit", str(limit)), ("offset", str(offset))]
+
         with contextlib.suppress(Exception):
-            query = self.repository_id.query() + [("limit", str(limit)), ("offset", str(offset))]
             response = self.make_request("GET", self._logs_url(package_base), params=query)
             response_json = response.json()
 
@@ -291,10 +340,11 @@ class WebClient(Client, SyncAhrimanClient):
             package_base(str): package base
             version(str | None): package version to remove logs. If None set, all logs will be removed
         """
+        query = self.repository_id.query()
+        if version is not None:
+            query += [("version", version)]
+
         with contextlib.suppress(Exception):
-            query = self.repository_id.query()
-            if version is not None:
-                query += [("version", version)]
             self.make_request("DELETE", self._logs_url(package_base), params=query)
 
     def package_patches_get(self, package_base: str, variable: str | None) -> list[PkgbuildPatch]:
@@ -361,6 +411,7 @@ class WebClient(Client, SyncAhrimanClient):
             NotImplementedError: not implemented method
         """
         payload = {"status": status.value}
+
         with contextlib.suppress(Exception):
             self.make_request("POST", self._package_url(package_base),
                               params=self.repository_id.query(), json=payload)
@@ -380,6 +431,7 @@ class WebClient(Client, SyncAhrimanClient):
             "status": status.value,
             "package": package.view(),
         }
+
         with contextlib.suppress(Exception):
             self.make_request("POST", self._package_url(package.base),
                               params=self.repository_id.query(), json=payload)
@@ -407,5 +459,6 @@ class WebClient(Client, SyncAhrimanClient):
             status(BuildStatusEnum): current ahriman status
         """
         payload = {"status": status.value}
+
         with contextlib.suppress(Exception):
             self.make_request("POST", self._status_url(), params=self.repository_id.query(), json=payload)

src/ahriman/models/event.py

@@ -0,0 +1,89 @@
+#
+# Copyright (c) 2021-2024 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from dataclasses import dataclass, field, fields
+from enum import StrEnum
+from typing import Any, Self
+
+from ahriman.core.utils import dataclass_view, filter_json, utcnow
+
+
+class EventType(StrEnum):
+    """
+    predefined event types
+
+    Attributes:
+        PackageRemoved(EventType): (class attribute) package has been removed
+        PackageUpdated(EventType): (class attribute) package has been updated
+    """
+
+    PackageRemoved = "package-removed"
+    PackageUpdated = "package-updated"
+
+
+@dataclass(frozen=True)
+class Event:
+    """
+    audit log event
+
+    Attributes:
+        created(int): event timestamp
+        data(dict[str, Any]): event metadata
+        event(str | EventType): event type
+        message(str | None): event message if available
+        object_id(str): object identifier
+    """
+
+    event: str | EventType
+    object_id: str
+    message: str | None = None
+    data: dict[str, Any] = field(default_factory=dict)
+    created: int = field(default_factory=lambda: int(utcnow().timestamp()))
+
+    def __post_init__(self) -> None:
+        """
+        replace null data to empty dictionary
+        """
+        if self.event in EventType:
+            object.__setattr__(self, "event", EventType(self.event))
+        object.__setattr__(self, "data", self.data or {})
+
+    @classmethod
+    def from_json(cls, dump: dict[str, Any]) -> Self:
+        """
+        construct event from the json dump
+
+        Args:
+            dump(dict[str, Any]): json dump body
+
+        Returns:
+            Self: dependencies object
+        """
+        # filter to only known fields
+        known_fields = [pair.name for pair in fields(cls)]
+        return cls(**filter_json(dump, known_fields))
+
+    def view(self) -> dict[str, Any]:
+        """
+        generate json event view
+
+        Returns:
+            dict[str, Any]: json-friendly dictionary
+        """
+        return dataclass_view(self)

src/ahriman/web/schemas/__init__.py

@@ -24,6 +24,8 @@ from ahriman.web.schemas.changes_schema import ChangesSchema
 from ahriman.web.schemas.counters_schema import CountersSchema
 from ahriman.web.schemas.dependencies_schema import DependenciesSchema
 from ahriman.web.schemas.error_schema import ErrorSchema
+from ahriman.web.schemas.event_schema import EventSchema
+from ahriman.web.schemas.event_search_schema import EventSearchSchema
 from ahriman.web.schemas.file_schema import FileSchema
 from ahriman.web.schemas.info_schema import InfoSchema
 from ahriman.web.schemas.internal_status_schema import InternalStatusSchema

src/ahriman/web/schemas/event_schema.py

@@ -0,0 +1,47 @@
+#
+# Copyright (c) 2021-2024 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+from ahriman.models.event import EventType
+
+
+class EventSchema(Schema):
+    """
+    request/response event schema
+    """
+
+    created = fields.Integer(required=True, metadata={
+        "description": "Event creation timestamp",
+        "example": 1680537091,
+    })
+    event = fields.String(required=True, metadata={
+        "description": "Event type",
+        "example": EventType.PackageUpdated,
+    })
+    object_id = fields.String(required=True, metadata={
+        "description": "Event object identifier",
+        "example": "ahriman",
+    })
+    message = fields.String(metadata={
+        "description": "Event message if available",
+    })
+    data = fields.Dict(keys=fields.String(), metadata={
+        "description": "Event metadata if available",
+    })

src/ahriman/web/schemas/event_search_schema.py

@@ -0,0 +1,38 @@
+#
+# Copyright (c) 2021-2024 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import fields
+
+from ahriman.models.event import EventType
+from ahriman.web.schemas.pagination_schema import PaginationSchema
+
+
+class EventSearchSchema(PaginationSchema):
+    """
+    request event search schema
+    """
+
+    event = fields.String(metadata={
+        "description": "Event type",
+        "example": EventType.PackageUpdated,
+    })
+    object_id = fields.String(metadata={
+        "description": "Event object identifier",
+        "example": "ahriman",
+    })

src/ahriman/web/views/v1/auditlog/__init__.py

@@ -0,0 +1,19 @@
+#
+# Copyright (c) 2021-2024 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#

src/ahriman/web/views/v1/auditlog/events.py

@@ -0,0 +1,104 @@
+#
+# Copyright (c) 2021-2024 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+import aiohttp_apispec  # type: ignore[import-untyped]
+
+from aiohttp.web import HTTPBadRequest, HTTPNoContent, Response, json_response
+
+from ahriman.models.event import Event
+from ahriman.models.user_access import UserAccess
+from ahriman.web.schemas import AuthSchema, ErrorSchema, EventSchema, EventSearchSchema
+from ahriman.web.views.base import BaseView
+
+
+class EventsView(BaseView):
+    """
+    audit log view
+
+    Attributes:
+        GET_PERMISSION(UserAccess): (class attribute) get permissions of self
+        POST_PERMISSION(UserAccess): (class attribute) post permissions of self
+    """
+
+    GET_PERMISSION = POST_PERMISSION = UserAccess.Full
+    ROUTES = ["/api/v1/events"]
+
+    @aiohttp_apispec.docs(
+        tags=["Audit log"],
+        summary="Get events",
+        description="Retrieve events from audit log",
+        responses={
+            200: {"description": "Success response", "schema": EventSchema(many=True)},
+            400: {"description": "Bad data is supplied", "schema": ErrorSchema},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [GET_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
+    @aiohttp_apispec.querystring_schema(EventSearchSchema)
+    async def get(self) -> Response:
+        """
+        get events list
+
+        Returns:
+            Response: 200 with workers list on success
+        """
+        limit, offset = self.page()
+        event = self.request.query.get("event") or None
+        object_id = self.request.query.get("object_id") or None
+
+        events = self.service().event_get(event, object_id, limit, offset)
+        response = [event.view() for event in events]
+
+        return json_response(response)
+
+    @aiohttp_apispec.docs(
+        tags=["Audit log"],
+        summary="Create event",
+        description="Add new event to the audit log",
+        responses={
+            204: {"description": "Success response"},
+            400: {"description": "Bad data is supplied", "schema": ErrorSchema},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [POST_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
+    @aiohttp_apispec.json_schema(EventSchema)
+    async def post(self) -> None:
+        """
+        add new audit log event
+
+        Raises:
+            HTTPBadRequest: if bad data is supplied
+            HTTPNoContent: in case of success response
+        """
+        try:
+            data = await self.request.json()
+            event = Event.from_json(data)
+        except Exception as ex:
+            raise HTTPBadRequest(reason=str(ex))
+
+        self.service().event_add(event)
+
+        raise HTTPNoContent