Add events API

This commit adds a new API endpoint to retrieve
the latest events. It allows users to specify pagination
parameters such as 'from_id', 'to_id', and 'size'.

Both 'from_id' and 'to_id' could refer to the timestamp
in milliseconds where the event was created.

Signed-off-by: Jose Javier Merchante <jjmerchante@bitergia.com>

Author: jjmerchante

releases/unreleased/events-api-endpoint.yml

@@ -0,0 +1,11 @@
+---
+title: Events API endpoint
+category: added
+author: Jose Javier Merchante <jjmerchante@bitergia.com>
+issue: null
+notes: >
+  Add a new API endpoint for retrieving the latest events
+  created. Users can control pagination using parameters
+  like 'from_id', 'to_id', and 'size'. Both 'from_id' and
+  'to_id' accept timestamps in milliseconds corresponding
+  to when each event was created.

src/grimoirelab/core/app/urls.py

@@ -15,6 +15,7 @@
 
 from grimoirelab.core.scheduler.urls import urlpatterns as sched_urlpatterns
 from grimoirelab.core.datasources.urls import ecosystems_urlpatterns
+from grimoirelab.core.events.urls import events_urlpatterns
 
 urlpatterns = [
     path("login", api_login, name="api_login"),
@@ -34,6 +35,8 @@
                         SortingHatGraphQLView.as_view(graphiql=settings.DEBUG, schema=schema)
                     ),
                 ),
+                # Events API
+                path("events/", include(events_urlpatterns)),
             ]
         ),
     ),

src/grimoirelab/core/events/__init__.py

@@ -0,0 +1,107 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) GrimoireLab Contributors
+#
+# 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 json
+
+from django.conf import settings
+from rest_framework import response, views
+from django_rq import get_connection
+from rest_framework.exceptions import ValidationError
+from rest_framework import serializers
+from drf_spectacular.utils import extend_schema, OpenApiParameter, OpenApiTypes
+
+
+MAX_PAGE_SIZE = 100
+DEFAULT_PAGE_SIZE = 25
+
+
+class EventSerializer(serializers.Serializer):
+    entry_id = serializers.CharField()
+    event = serializers.JSONField()
+
+
+class EventStream(views.APIView):
+    """
+    API endpoint that allows to get the latest events in the stream.
+    By default, it returns the latest events in the stream.
+
+    Old events are removed from the stream based on the retention policy configured.
+    """
+
+    serializer_class = EventSerializer
+
+    @extend_schema(
+        responses=EventSerializer(many=True),
+        parameters=[
+            OpenApiParameter(
+                name="from_id",
+                type=OpenApiTypes.STR,
+                description=(
+                    "Start ID (inclusive) to read events from. "
+                    "Can be a Redis Stream ID (e.g. '1609459200000-0') or a "
+                    "timestamp in milliseconds. Use for paginating forward."
+                ),
+                required=False,
+            ),
+            OpenApiParameter(
+                name="to_id",
+                type=OpenApiTypes.STR,
+                description=(
+                    "End ID (inclusive) to read events up to. "
+                    "Can be a Redis Stream ID or a timestamp in milliseconds."
+                ),
+                required=False,
+            ),
+            OpenApiParameter(
+                name="size",
+                default=25,
+                type=OpenApiTypes.INT,
+                description=f"Maximum number of events to return (default {DEFAULT_PAGE_SIZE}, max {MAX_PAGE_SIZE}).",
+                required=False,
+            ),
+        ],
+    )
+    def get(self, request, format=None):
+        events_stream = settings.GRIMOIRELAB_EVENTS_STREAM_NAME
+        from_id = request.query_params.get("from_id", None)
+        to_id = request.query_params.get("to_id", None)
+        try:
+            size = int(request.query_params.get("size", DEFAULT_PAGE_SIZE))
+            if size < 1 or size > MAX_PAGE_SIZE:
+                raise ValueError
+        except ValueError:
+            raise ValidationError("'size' parameter must be an integer between 1 and 100.")
+
+        connection = get_connection()
+        if from_id is None and to_id is None:
+            # Get the latest events
+            entries = connection.xrevrange(events_stream, max="+", min="-", count=size)
+            entries = reversed(entries)
+        else:
+            entries = connection.xrange(
+                events_stream, min=from_id or "-", max=to_id or "+", count=size
+            )
+
+        events = []
+        for entry in entries:
+            entry_id = entry[0].decode("utf-8")
+            entry_data = json.loads(entry[1][b"data"])
+            event = {"entry_id": entry_id, "event": entry_data}
+            events.append(event)
+
+        return response.Response(events)

src/grimoirelab/core/events/api.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) GrimoireLab Contributors
+#
+# 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 os
+
+from django.apps import AppConfig
+
+
+class EventsConfig(AppConfig):
+    name = "grimoirelab.core.events"
+    path = os.path.dirname(os.path.abspath(__file__))

src/grimoirelab/core/events/apps.py

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) GrimoireLab Contributors
+#
+# 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 django.urls import path
+
+from . import api
+
+events_urlpatterns = [
+    path("stream/", api.EventStream.as_view(), name="event-stream"),
+]