events: Add filtering by id and ids

Signed-off-by: Denys Fedoryshchenko <denys.f@collabora.com>

Author: nuclearcat

api/main.py

@@ -435,6 +435,7 @@ async def get_events(request: Request):
        - kind: Event kind to filter events
        - state: Event state to filter events
        - result: Event result to filter events
+       - id / ids: Event document id(s) to filter events
        - recursive: Retrieve node together with event
     This API endpoint is under development and may change in future.
     """
@@ -446,6 +447,39 @@ async def get_events(request: Request):
     state = query_params.pop('state', None)
     result = query_params.pop('result', None)
     from_ts = query_params.pop('from', None)
+    # Support filtering by MongoDB _id.
+    # Accept `id=<hex>` for a single id or `ids=a,b,c` for multiple ids.
+    # Using `id` as query param is safe here because we remove it from the
+    # filter before passing to Mongo.
+    event_id = query_params.pop('id', None)
+    event_ids = query_params.pop('ids', None)
+    if event_id and event_ids:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Provide either id or ids, not both"
+        )
+    if event_id:
+        try:
+            query_params['_id'] = ObjectId(event_id)
+        except (errors.InvalidId, TypeError) as exc:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Invalid id format"
+            ) from exc
+    elif event_ids:
+        try:
+            ids_list = [ObjectId(x.strip()) for x in event_ids.split(',') if x.strip()]
+        except (errors.InvalidId, TypeError) as exc:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Invalid ids format"
+            ) from exc
+        if not ids_list:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="ids must contain at least one id"
+            )
+        query_params['_id'] = {'$in': ids_list}
     if from_ts:
         if isinstance(from_ts, str):
             from_ts = datetime.fromisoformat(from_ts)

doc/events-migration.md

@@ -102,6 +102,19 @@ each event document but do not affect existing queries:
 Existing queries filtering on `timestamp`, `data.kind`, `data.state`, etc.
 continue to work unchanged.
 
+Supported query parameters for `/events`:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `from` | string (ISO timestamp) | Return events with `timestamp` greater than this value. |
+| `kind` | string | Filter by `data.kind` (e.g., `job`, `node`). |
+| `state` | string | Filter by `data.state`. |
+| `result` | string | Filter by `data.result`. |
+| `limit` | integer | Maximum number of events to return. |
+| `recursive` | bool | Attach related node info to each event (max `limit` 1000). |
+| `id` | string (Mongo ObjectId) | Filter by a single event document id. |
+| `ids` | string (comma‑separated ObjectIds) | Filter by multiple event document ids. |
+
 ## Subscriber ID Guidelines
 
 The `subscriber_id` should be: