⚡ improve performance on status endpoint; add from/to filter (#4805)

Author: MrKrisKrisu

API_CHANGELOG.md

@@ -42,6 +42,20 @@ Check back here regularly to stay ahead of removals.
 
 ---
 
+# 2026-05-18
+
+**`GET /api/v1/status`: new `from`/`to` parameters and performance fix:**
+The endpoint now accepts optional `from` and `to` date parameters (ISO 8601 date format, e.g. `2024-01-01`) to control the departure time window.
+Without parameters, the window defaults to the last 7 days up to now+20 minutes.
+The window between `from` and `to` must not exceed 365 days. 
+Exception: when `user_id` is set to the authenticated user's own ID, no time limit applies and `from`/`to` are fully optional.
+The previously implicit hard upper bound of `now()+20min` is now the default value of `to` and can be overridden.
+Results are ordered by departure descending (previously: status creation date descending).
+
+(Background: This query was very painful on the production database and causes some headache...)
+
+---
+
 # 2026-05-14
 
 **New endpoint `GET /api/v1/tags/suggestions`:**

app/Http/Controllers/API/v1/StatusController.php

@@ -366,7 +366,7 @@ public function getLivePositionForStatus($ids): AnonymousResourceCollection
     #[OA\Get(
         path: '/status',
         operationId: 'listStatuses',
-        description: 'Returns paginated list of statuses, filtered by given parameters',
+        description: 'Returns cursor-paginated statuses filtered by given parameters. The departure window (from..to) defaults to the last 7 days and must not exceed 365 days.',
         summary: '[Auth optional] List and filter statuses',
         tags: ['Status'],
         parameters: [
@@ -384,6 +384,22 @@ public function getLivePositionForStatus($ids): AnonymousResourceCollection
                 schema: new OA\Schema(type: 'integer'),
                 example: 42,
             ),
+            new OA\Parameter(
+                name: 'from',
+                description: 'Lower bound for departure (date, e.g. 2024-01-01). Defaults to 7 days before "to".',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'string', format: 'date'),
+                example: '2024-01-01',
+            ),
+            new OA\Parameter(
+                name: 'to',
+                description: 'Upper bound for departure (date, e.g. 2024-01-31). Defaults to now+20min. Range from..to must not exceed 365 days.',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'string', format: 'date'),
+                example: '2024-01-31',
+            ),
             new OA\Parameter(
                 name: 'origin_text',
                 description: 'Filter by origin station name',
@@ -432,47 +448,80 @@ public function getLivePositionForStatus($ids): AnonymousResourceCollection
     public function list(Request $request): AnonymousResourceCollection
     {
         $validated = $request->validate([
-            // generic filters
             'body' => ['nullable', 'string', 'max:32'],
             'user_id' => ['nullable', 'integer', 'exists:users,id'],
-
-            // Filters for origin/destination
+            'from' => ['nullable', 'date'],
+            'to' => ['nullable', 'date'],
             'origin_text' => ['nullable', 'string', 'max:64'],
             'origin_id' => ['nullable', 'integer', 'exists:train_stations,id'],
             'destination_text' => ['nullable', 'string', 'max:64'],
             'destination_id' => ['nullable', 'integer', 'exists:train_stations,id'],
         ]);
 
         $user = auth()->user();
-        $query = Status::query()->orderByDesc('created_at');
+        $isOwnSearch = isset($validated['user_id']) && (int) $validated['user_id'] === $user->id;
+
+        if ($isOwnSearch) {
+            // own search ignores day limit (=> less checkins to search)
+            $to = isset($validated['to']) ? Carbon::parse($validated['to'])->endOfDay() : null;
+            $from = isset($validated['from']) ? Carbon::parse($validated['from'])->startOfDay() : null;
+
+            if ($from !== null && $to !== null && $from->isAfter($to)) {
+                throw ValidationException::withMessages(['from' => [__('errors.date-range-order')]]);
+            }
+        } else {
+            $to = isset($validated['to']) ? Carbon::parse($validated['to'])->endOfDay() : now()->addMinutes(20);
+            $from = isset($validated['from']) ? Carbon::parse($validated['from'])->startOfDay() : $to->copy()->subDays(7);
+
+            if ($from->isAfter($to)) {
+                throw ValidationException::withMessages(['from' => [__('errors.date-range-order')]]);
+            }
+            if ($from->diffInDays($to) > 365) {
+                throw ValidationException::withMessages(['from' => [__('errors.date-range-max')]]);
+            }
+        }
+
+        $query = Status::query()->orderByDesc('train_checkins.departure');
 
         if (isset($validated['body'])) {
             $query->where('body', 'like', '%' . $validated['body'] . '%');
         }
 
-        $query->join('train_checkins', 'train_checkins.status_id', '=', 'statuses.id')
+        $hasOriginFilter = isset($validated['origin_text']) || isset($validated['origin_id']);
+        $hasDestinationFilter = isset($validated['destination_text']) || isset($validated['destination_id']);
+
+        $checkinJoin = in_array(DB::connection()->getDriverName(), ['mysql', 'mariadb'], true)
+            ? DB::raw('`train_checkins` FORCE INDEX (idx_tc_departure_status)')
+            : 'train_checkins'; // force best index in mysql and mariadb, but fall back here for sqlite / tests
+
+        $query->join($checkinJoin, 'train_checkins.status_id', '=', 'statuses.id')
             ->join('users', 'statuses.user_id', '=', 'users.id')
-            ->join('train_stopovers as origin_stopover', 'train_checkins.origin_stopover_id', '=', 'origin_stopover.id')
-            ->join('train_stations as origin_station', 'origin_stopover.train_station_id', '=', 'origin_station.id')
-            ->join('train_stopovers as destination_stopover', 'train_checkins.destination_stopover_id', '=', 'destination_stopover.id')
-            ->join('train_stations as destination_station', 'destination_stopover.train_station_id', '=', 'destination_station.id')
-            ->when(isset($validated['origin_text']), function ($q) use ($validated) {
-                $q->where('origin_station.name', 'like', '%' . $validated['origin_text'] . '%');
-            })
-            ->when(isset($validated['origin_id']), function ($q) use ($validated) {
-                $q->where('origin_station.id', $validated['origin_id']);
-            })
-            ->when(isset($validated['destination_text']), function ($q) use ($validated) {
-                $q->where('destination_station.name', 'like', '%' . $validated['destination_text'] . '%');
-            })
-            ->when(isset($validated['destination_id']), function ($q) use ($validated) {
-                $q->where('destination_station.id', $validated['destination_id']);
-            })
-            ->when(isset($validated['user_id']), function ($q) use ($validated) {
-                $q->where('users.id', $validated['user_id']);
-            })
+            ->when($hasOriginFilter, fn ($q) => $q
+                ->join('train_stopovers as origin_stopover', 'train_checkins.origin_stopover_id', '=', 'origin_stopover.id')
+                ->join('train_stations as origin_station', 'origin_stopover.train_station_id', '=', 'origin_station.id')
+            )
+            ->when($hasDestinationFilter, fn ($q) => $q
+                ->join('train_stopovers as destination_stopover', 'train_checkins.destination_stopover_id', '=', 'destination_stopover.id')
+                ->join('train_stations as destination_station', 'destination_stopover.train_station_id', '=', 'destination_station.id')
+            )
+            ->when(isset($validated['origin_text']), fn ($q) => $q
+                ->where('origin_station.name', 'like', '%' . $validated['origin_text'] . '%')
+            )
+            ->when(isset($validated['origin_id']), fn ($q) => $q
+                ->where('origin_station.id', $validated['origin_id'])
+            )
+            ->when(isset($validated['destination_text']), fn ($q) => $q
+                ->where('destination_station.name', 'like', '%' . $validated['destination_text'] . '%')
+            )
+            ->when(isset($validated['destination_id']), fn ($q) => $q
+                ->where('destination_station.id', $validated['destination_id'])
+            )
+            ->when(isset($validated['user_id']), fn ($q) => $q
+                ->where('users.id', $validated['user_id'])
+            )
             ->where(\App\Http\Controllers\Backend\Transport\StatusController::filterStatusVisibility($user))
-            ->where('train_checkins.departure', '<', now()->addMinutes(20))
+            ->when($from !== null, fn ($q) => $q->where('train_checkins.departure', '>=', $from))
+            ->when($to !== null, fn ($q) => $q->where('train_checkins.departure', '<=', $to))
             ->whereNotIn('statuses.user_id', $user->mutedUsers()->select('muted_id'))
             ->whereNotIn('statuses.user_id', $user->blockedUsers()->select('blocked_id'))
             ->whereNotIn('statuses.user_id', $user->blockedByUsers()->select('user_id'))

lang/de.json

@@ -196,6 +196,8 @@
   "error.bad-request": "Die Anfrage ist ungültig.",
   "error.login": "Falsche Anmeldedaten",
   "error.status.not-authorized": "Du bist nicht berechtigt, diesen Status zu sehen.",
+  "errors.date-range-max": "Der Zeitraum zwischen \"von\" und \"bis\" darf maximal 365 Tage betragen.",
+  "errors.date-range-order": "\"von\" muss vor \"bis\" liegen.",
   "errors.403.alt_text": "Ein Bahnhof im dichten Nebel. In der Ferne sieht man mehrere rote Signale",
   "errors.403.lead": "Mayday, mayday, mayday, du hast keine Berechtigung für diesen Inhalt.",
   "errors.404.alt_text": "Bild einer alten Bahnstrecke im grünen Wald. Auf den Schwellen befindet sich Moos und das Gebüsch wächst über die Gleise.",

lang/en.json

@@ -196,6 +196,8 @@
   "error.bad-request": "The request is invalid.",
   "error.login": "Wrong credentials",
   "error.status.not-authorized": "You're not authorised to see this status.",
+  "errors.date-range-max": "The date range between \"from\" and \"to\" must not exceed 365 days.",
+  "errors.date-range-order": "\"from\" must be before \"to\".",
   "errors.403.alt_text": "A train station in thick fog. Several red signals can be seen in the distance.",
   "errors.403.lead": "Mayday, mayday, mayday, you don’t have permission to access this content.",
   "errors.404.alt_text": "Image of an old railway line in a green forest. There is moss on the sleepers and bushes are growing over the tracks.",

lang/fr.json

@@ -194,6 +194,8 @@
   "error.bad-request": "La requête est invalide.",
   "error.login": "Données de connexion incorrectes",
   "error.status.not-authorized": "Tu n'es pas autorisé·e à voir cet enregistrement.",
+  "errors.date-range-max": "La plage de dates entre « from » et « to » ne doit pas dépasser 365 jours.",
+  "errors.date-range-order": "« from » doit être antérieur à « to ».",
   "errors.403.alt_text": "Une gare dans un épais brouillard. Au loin, on aperçoit plusieurs signaux fermés.",
   "errors.403.lead": "Mayday, mayday, mayday, tu n'as pas l'autorisation d'accéder à ce contenu.",
   "errors.404.alt_text": "Image d'une ancienne voie ferrée dans une forêt verdoyante. Il y a de la mousse sur les traverses et des buissons poussent sur les rails.",

resources/types/Api.gen.ts

@@ -4595,7 +4595,7 @@ export class Api<
       }),
 
     /**
-     * @description Returns paginated list of statuses, filtered by given parameters
+     * @description Returns cursor-paginated statuses filtered by given parameters. The departure window (from..to) defaults to the last 7 days and must not exceed 365 days.
      *
      * @tags Status
      * @name ListStatuses
@@ -4614,6 +4614,18 @@ export class Api<
          * @example 42
          */
         user_id?: number;
+        /**
+         * Lower bound for departure (date, e.g. 2024-01-01). Defaults to 7 days before "to".
+         * @format date
+         * @example "2024-01-01"
+         */
+        from?: string;
+        /**
+         * Upper bound for departure (date, e.g. 2024-01-31). Defaults to now+20min. Range from..to must not exceed 365 days.
+         * @format date
+         * @example "2024-01-31"
+         */
+        to?: string;
         /**
          * Filter by origin station name
          * @example "Central Station"

storage/api-docs/api-docs.json

@@ -5747,7 +5747,7 @@
                     "Status"
                 ],
                 "summary": "[Auth optional] List and filter statuses",
-                "description": "Returns paginated list of statuses, filtered by given parameters",
+                "description": "Returns cursor-paginated statuses filtered by given parameters. The departure window (from..to) defaults to the last 7 days and must not exceed 365 days.",
                 "operationId": "listStatuses",
                 "parameters": [
                     {
@@ -5768,6 +5768,28 @@
                         },
                         "example": 42
                     },
+                    {
+                        "name": "from",
+                        "in": "query",
+                        "description": "Lower bound for departure (date, e.g. 2024-01-01). Defaults to 7 days before \"to\".",
+                        "required": false,
+                        "schema": {
+                            "type": "string",
+                            "format": "date"
+                        },
+                        "example": "2024-01-01"
+                    },
+                    {
+                        "name": "to",
+                        "in": "query",
+                        "description": "Upper bound for departure (date, e.g. 2024-01-31). Defaults to now+20min. Range from..to must not exceed 365 days.",
+                        "required": false,
+                        "schema": {
+                            "type": "string",
+                            "format": "date"
+                        },
+                        "example": "2024-01-31"
+                    },
                     {
                         "name": "origin_text",
                         "in": "query",