feat: add store v3 specification

2024-04-04 10:43:54 -04:00 · 2024-04-04 10:43:54 -04:00 · d576ea54ca
parent c0a97a5043 a7b75bf006
commit d576ea54ca
4 changed files with 203 additions and 28 deletions
--- a/api-spec/legacystoreapi.yaml
+++ b/api-spec/legacystoreapi.yaml
@ -0,0 +1,137 @@
+# /store/v1/messages:
+get:
+  summary: Gets message history
+  description: >
+    Retrieves WakuV2 message history. The returned history
+    can be potentially filtered by optional request parameters.
+  operationId: getMessageHistory
+  tags:
+    - legacy_store
+  parameters:
+    - name: peerAddr
+      in: query
+      schema:
+        type: string
+      description: >
+        P2P fully qualified peer multiaddress
+        in the format `(ip4|ip6)/tcp/p2p/$peerId` and URL-encoded.
+      example: '%2Fip4%2F127.0.0.1%2Ftcp%2F60001%2Fp2p%2F16Uiu2HAmVFXtAfSj4EiR7mL2KvL4EE2wztuQgUSBoj2Jx2KeXFLN'
+
+    - name: pubsubTopic
+      in: query
+      schema:
+        type: string
+      description: >
+        The pubsub topic on which a WakuMessage is published.
+        If left empty, no filtering is applied.
+        It is also intended for pagination purposes.
+        It should be a URL-encoded string.
+      example: 'my%20pubsub%20topic'
+
+    - name: contentTopics
+      in: query
+      schema: string
+      description: >
+        Comma-separated list of content topics. When specified,
+        only WakuMessages that are linked to any of the given
+        content topics will be delivered in the get response.
+        It should be a URL-encoded-comma-separated string.
+      example: 'my%20first%20content%20topic%2Cmy%20second%20content%20topic%2Cmy%20third%20content%20topic'
+
+    - name: startTime
+      in: query
+      schema:
+        type: string
+      description: >
+        The inclusive lower bound on the timestamp of
+        queried WakuMessages. This field holds the
+        Unix epoch time in nanoseconds as a 64-bits
+        integer value.
+      example: '1680590945000000000'
+
+    - name: endTime
+      in: query
+      schema:
+        type: string
+      description: >
+        The inclusive upper bound on the timestamp of
+        queried WakuMessages. This field holds the
+        Unix epoch time in nanoseconds as a 64-bits
+        integer value.
+      example: '1680590945000000000'
+
+    - name: senderTime
+      in: query
+      schema:
+        type: string
+      description: >
+        Cursor field intended for pagination purposes.
+        Represents the Unix time in nanoseconds at which a message was generated.
+        It could be empty for retrieving the first page,
+        and will be returned from the GET response so that
+        it can be part of the next page request.
+      example: '1680590947000000000'
+
+    - name: storeTime
+      in: query
+      schema:
+        type: string
+      description: >
+        Cursor field intended for pagination purposes.
+        Represents the Unix time in nanoseconds at which a message was stored.
+        It could be empty for retrieving the first page,
+        and will be returned from the GET response so that
+        it can be part of the next page request.
+      example: '1680590945000000000'
+
+    - name: digest
+      in: query
+      schema:
+        type: string
+      description: >
+        Cursor field intended for pagination purposes.
+        URL-base64-encoded string computed as a hash of the
+        a message content topic plus a message payload.
+        It could be empty for retrieving the first page,
+        and will be returned from the GET response so that
+        it can be part of the next page request.
+      example: 'Gc4ACThW5t2QQO82huq3WnDv%2FapPPJpD%2FwJfxDxAnR0%3D'
+
+    - name: pageSize
+      in: query
+      schema:
+        type: string
+      description: >
+        Number of messages to retrieve per page
+      example: '5'
+
+    - name: ascending
+      in: query
+      schema:
+        type: string
+      description: >
+        "true" for paging forward, "false" for paging backward
+      example: "true"
+
+  responses:
+    '200':
+      description: WakuV2 message history.
+      content:
+        application/json:
+          schema:
+            $ref: './schemas/apitypes.yaml#/StoreResponse'
+    '400':
+      description: Bad request error.
+      content:
+        text/plain:
+          type: string
+    '412':
+      description: Precondition failed.
+      content:
+        text/plain:
+          type: string
+    '500':
+      description: Internal server error.
+      content:
+        text/plain:
+          type: string
--- a/api-spec/openapi.yaml
+++ b/api-spec/openapi.yaml
@ -21,6 +21,8 @@ tags:
  - name: relay
    description: Control of the relaying of messages. See [11/WAKU2-RELAY](https://rfc.vac.dev/spec/11/) RFC
  - name: store
+    description: Retrieve the message history. #TODO See [13/WAKU2-STORE]() RFC
+  - name: legacy_store
    description: Retrieve the message history. See [13/WAKU2-STORE](https://rfc.vac.dev/spec/13/) RFC
  - name: filter
    description: Control of the content filtering. See [12/WAKU2-FILTER](https://rfc.vac.dev/spec/12/) RFC
@ -50,6 +52,8 @@ paths:
  /relay/v1/auto/subscriptions:
    $ref: "./relayapi_auto_subscriptions.yaml"
  /store/v1/messages:
+    $ref: "./legacystoreapi.yaml"
+  /store/v3/messages:
    $ref: "./storeapi.yaml"
  /filter/v1/subscriptions:
    $ref: "./filterapi_v1_subscriptions.yaml"
--- a/api-spec/schemas/apitypes.yaml
+++ b/api-spec/schemas/apitypes.yaml
@ -118,12 +118,48 @@ WakuMessage:
      format: int64
    ephemeral:
      type: boolean
+    proof:
+      type: string
    meta:
      type: string
      format: byte
  required:
      - payload
      - contentTopic
+      - timestamp
+
+WakuMessageKeyValue:
+  type: object
+  properties:
+    message_hash:
+      type: string
+    message:
+      $ref: '#/components/schemas/WakuMessage'
+  required:
+    - message_hash
+    - message
+
+StoreQueryResponse:
+  type: object
+  properties:
+    request_id:
+      type: string
+    status_code:
+      type: integer
+      format: uint32
+    status_desc:
+      type: string
+    messages:
+      type: array
+      items:
+        $ref: '#/components/schemas/WakuMessageKeyValue'
+    pagination_cursor:
+      type: string
+  required:
+    - request_id
+    - status_code
+    - status_desc
+    - messages

 PushRequest:
  type: object
--- a/api-spec/storeapi.yaml
+++ b/api-spec/storeapi.yaml
@ -1,8 +1,8 @@
-# /store/v1/messages:
+# /store/v3/messages:
 get:
  summary: Gets message history
  description: >
-    Retrieves WakuV2 message history. The returned history
+    Retrieves Waku message history. The returned history
    can be potentially filtered by optional request parameters.
  operationId: getMessageHistory
  tags:
@ -12,11 +12,23 @@ get:
      in: query
      schema:
        type: string
+      required: true
      description: >
        P2P fully qualified peer multiaddress
        in the format `(ip4|ip6)/tcp/p2p/$peerId` and URL-encoded.
      example: '%2Fip4%2F127.0.0.1%2Ftcp%2F60001%2Fp2p%2F16Uiu2HAmVFXtAfSj4EiR7mL2KvL4EE2wztuQgUSBoj2Jx2KeXFLN'

+    - name: includeData
+      in: query
+      schema:
+        type: string
+      description: >
+        Boolean indicating if the query should return messages (data) or hashes only.
+        A value of 'false' returns hashes only.
+        A value of 'true' returns hashes AND messages.
+        Default value is 'false'
+      example: 'true'
+
    - name: pubsubTopic
      in: query
      schema:
@ -60,38 +72,23 @@ get:
        integer value.
      example: '1680590945000000000'

-    - name: senderTime
+    - name: hashes
      in: query
      schema:
        type: string
      description: >
-        Cursor field intended for pagination purposes.
-        Represents the Unix time in nanoseconds at which a message was generated.
-        It could be empty for retrieving the first page,
-        and will be returned from the GET response so that
-        it can be part of the next page request.
-      example: '1680590947000000000'
+        Comma-separated list of message hashes.
+        URL-base64-encoded string computed as a hash of messages.
+        Used to find messages by hash.
+      example: 'Gc4ACThW5t2QQO82huq3WnDv%2FapPPJpD%2FwJfxDxAnR0%3D'

-    - name: storeTime
+    - name: cursor
      in: query
      schema:
        type: string
      description: >
        Cursor field intended for pagination purposes.
-        Represents the Unix time in nanoseconds at which a message was stored.
-        It could be empty for retrieving the first page,
-        and will be returned from the GET response so that
-        it can be part of the next page request.
-      example: '1680590945000000000'
-
-    - name: digest
-      in: query
-      schema:
-        type: string
-      description: >
-        Cursor field intended for pagination purposes.
-        URL-base64-encoded string computed as a hash of the
-        a message content topic plus a message payload.
+        URL-base64-encoded string computed as a hash of a message.
        It could be empty for retrieving the first page,
        and will be returned from the GET response so that
        it can be part of the next page request.
@ -110,16 +107,17 @@ get:
      schema:
        type: string
      description: >
-        "true" for paging forward, "false" for paging backward
+        "true" for paging forward, "false" for paging backward.
+        If not specified or if specified with an invalid value, the default is "true".
      example: "true"

  responses:
    '200':
-      description: WakuV2 message history.
+      description: Waku message history.
      content:
        application/json:
          schema:
-            $ref: './schemas/apitypes.yaml#/StoreResponse'
+            $ref: '#/components/schemas/StoreQueryResponse'
    '400':
      description: Bad request error.
      content:
@ -134,4 +132,4 @@ get:
      description: Internal server error.
      content:
        text/plain:
-          type: string
+          type: string