Support two-way traversal in blob feed API (#1286)

Layr-Labs · Feb 20, 2025 · 0207000 · 0207000
1 parent 257c70d
commit 0207000
Show file tree

Hide file tree

Showing 6 changed files with 281 additions and 130 deletions.
diff --git a/disperser/dataapi/docs/v2/V2_docs.go b/disperser/dataapi/docs/v2/V2_docs.go
@@ -126,29 +126,35 @@ const docTemplateV2 = `{
                 "tags": [
                     "Blobs"
                 ],
-                "summary": "Fetch blob feed",
+                "summary": "Fetch blob feed in specified direction",
                 "parameters": [
                     {
                         "type": "string",
-                        "description": "Fetch blobs up to the end time (ISO 8601 format: 2006-01-02T15:04:05Z) [default: now]",
-                        "name": "end",
+                        "description": "Direction to fetch: 'forward' (oldest to newest, ASC order) or 'backward' (newest to oldest, DESC order) [default: forward]",
+                        "name": "direction",
                         "in": "query"
                     },
                     {
-                        "type": "integer",
-                        "description": "Fetch blobs starting from an interval (in seconds) before the end time [default: 3600]",
-                        "name": "interval",
+                        "type": "string",
+                        "description": "Fetch blobs before this time, exclusive (ISO 8601 format, example: 2006-01-02T15:04:05Z) [default: now]",
+                        "name": "before",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Fetch blobs after this time, exclusive (ISO 8601 format, example: 2006-01-02T15:04:05Z); must be smaller than ` + "`" + `before` + "`" + ` [default: before-1h]",
+                        "name": "after",
                         "in": "query"
                     },
                     {
                         "type": "string",
-                        "description": "Fetch blobs starting from the pagination token (exclusively). Overrides the interval param if specified [default: empty]",
-                        "name": "pagination_token",
+                        "description": "Pagination cursor (opaque string from previous response); for 'forward' direction, overrides ` + "`" + `after` + "`" + ` and fetches blobs from ` + "`" + `cursor` + "`" + ` to ` + "`" + `before` + "`" + `; for 'backward' direction, overrides ` + "`" + `before` + "`" + ` and fetches blobs from ` + "`" + `cursor` + "`" + ` to ` + "`" + `after` + "`" + ` (all bounds exclusive) [default: empty]",
+                        "name": "cursor",
                         "in": "query"
                     },
                     {
                         "type": "integer",
-                        "description": "The maximum number of blobs to fetch. System max (1000) if limit \u003c= 0 [default: 20; max: 1000]",
+                        "description": "Maximum number of blobs to return; if limit \u003c= 0 or \u003e1000, it's treated as 1000 [default: 20; max: 1000]",
                         "name": "limit",
                         "in": "query"
                     }
@@ -1092,7 +1098,7 @@ const docTemplateV2 = `{
                         "$ref": "#/definitions/v2.BlobInfo"
                     }
                 },
-                "pagination_token": {
+                "cursor": {
                     "type": "string"
                 }
             }

diff --git a/disperser/dataapi/docs/v2/V2_swagger.json b/disperser/dataapi/docs/v2/V2_swagger.json
@@ -123,29 +123,35 @@
                 "tags": [
                     "Blobs"
                 ],
-                "summary": "Fetch blob feed",
+                "summary": "Fetch blob feed in specified direction",
                 "parameters": [
                     {
                         "type": "string",
-                        "description": "Fetch blobs up to the end time (ISO 8601 format: 2006-01-02T15:04:05Z) [default: now]",
-                        "name": "end",
+                        "description": "Direction to fetch: 'forward' (oldest to newest, ASC order) or 'backward' (newest to oldest, DESC order) [default: forward]",
+                        "name": "direction",
                         "in": "query"
                     },
                     {
-                        "type": "integer",
-                        "description": "Fetch blobs starting from an interval (in seconds) before the end time [default: 3600]",
-                        "name": "interval",
+                        "type": "string",
+                        "description": "Fetch blobs before this time, exclusive (ISO 8601 format, example: 2006-01-02T15:04:05Z) [default: now]",
+                        "name": "before",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Fetch blobs after this time, exclusive (ISO 8601 format, example: 2006-01-02T15:04:05Z); must be smaller than `before` [default: before-1h]",
+                        "name": "after",
                         "in": "query"
                     },
                     {
                         "type": "string",
-                        "description": "Fetch blobs starting from the pagination token (exclusively). Overrides the interval param if specified [default: empty]",
-                        "name": "pagination_token",
+                        "description": "Pagination cursor (opaque string from previous response); for 'forward' direction, overrides `after` and fetches blobs from `cursor` to `before`; for 'backward' direction, overrides `before` and fetches blobs from `cursor` to `after` (all bounds exclusive) [default: empty]",
+                        "name": "cursor",
                         "in": "query"
                     },
                     {
                         "type": "integer",
-                        "description": "The maximum number of blobs to fetch. System max (1000) if limit \u003c= 0 [default: 20; max: 1000]",
+                        "description": "Maximum number of blobs to return; if limit \u003c= 0 or \u003e1000, it's treated as 1000 [default: 20; max: 1000]",
                         "name": "limit",
                         "in": "query"
                     }
@@ -1089,7 +1095,7 @@
                         "$ref": "#/definitions/v2.BlobInfo"
                     }
                 },
-                "pagination_token": {
+                "cursor": {
                     "type": "string"
                 }
             }

diff --git a/disperser/dataapi/docs/v2/V2_swagger.yaml b/disperser/dataapi/docs/v2/V2_swagger.yaml
@@ -299,7 +299,7 @@ definitions:
         items:
           $ref: '#/definitions/v2.BlobInfo'
         type: array
-      pagination_token:
+      cursor:
         type: string
     type: object
   v2.BlobInfo:
@@ -677,23 +677,30 @@ paths:
   /blobs/feed:
     get:
       parameters:
-      - description: 'Fetch blobs up to the end time (ISO 8601 format: 2006-01-02T15:04:05Z)
-          [default: now]'
+      - description: 'Direction to fetch: ''forward'' (oldest to newest, ASC order)
+          or ''backward'' (newest to oldest, DESC order) [default: forward]'
         in: query
-        name: end
+        name: direction
         type: string
-      - description: 'Fetch blobs starting from an interval (in seconds) before the
-          end time [default: 3600]'
+      - description: 'Fetch blobs before this time, exclusive (ISO 8601 format, example:
+          2006-01-02T15:04:05Z) [default: now]'
         in: query
-        name: interval
-        type: integer
-      - description: 'Fetch blobs starting from the pagination token (exclusively).
-          Overrides the interval param if specified [default: empty]'
+        name: before
+        type: string
+      - description: 'Fetch blobs after this time, exclusive (ISO 8601 format, example:
+          2006-01-02T15:04:05Z); must be smaller than `before` [default: before-1h]'
+        in: query
+        name: after
+        type: string
+      - description: 'Pagination cursor (opaque string from previous response); for
+          ''forward'' direction, overrides `after` and fetches blobs from `cursor`
+          to `before`; for ''backward'' direction, overrides `before` and fetches
+          blobs from `cursor` to `after` (all bounds exclusive) [default: empty]'
         in: query
-        name: pagination_token
+        name: cursor
         type: string
-      - description: 'The maximum number of blobs to fetch. System max (1000) if limit
-          <= 0 [default: 20; max: 1000]'
+      - description: 'Maximum number of blobs to return; if limit <= 0 or >1000, it''s
+          treated as 1000 [default: 20; max: 1000]'
         in: query
         name: limit
         type: integer
@@ -716,7 +723,7 @@ paths:
           description: 'error: Server error'
           schema:
             $ref: '#/definitions/v2.ErrorResponse'
-      summary: Fetch blob feed
+      summary: Fetch blob feed in specified direction
       tags:
       - Blobs
   /metrics/summary: