Merge c762ccaa918b27bea3e03c4a510dcf4689f337a6 into 8adc4c8d4520e0b2e11bc353708b51bb799b88cf

README.md

@@ -1,2 +1,2 @@
 # waku-rest-api
-Open API specification of Waku v2 client interface 
+Open API specification of Logos Delivery client interface 

api-spec/adminapi_log_level.yaml

@@ -1,6 +1,6 @@
 post:
   summary: Dynamic set log level on the node
-  description: Change the log level of a Waku v2 node.
+  description: Change the log level of a Logos Delivery node.
   operationId: setLogLevel
   tags:
     - admin

api-spec/adminapi_peer.yaml

@@ -13,7 +13,7 @@ get:
       description: ID of the peer to retrieve information for    
   responses:
     '200':
-      description: Information about a Waku v2 node.
+      description: Information about a Logos Delivery node.
       content:
         application/json:
           schema:

api-spec/adminapi_peers_stats.yaml

@@ -6,7 +6,7 @@ get:
     - admin
   responses:
     '200':
-      description: Information about a Waku v2 node.
+      description: Information about a Logos Delivery node.
       content:
         application/json:
           schema:

api-spec/debugapi_info.yaml

@@ -1,12 +1,12 @@
 get:
   summary: Get node info
-  description: Retrieve information about a Waku v2 node.
+  description: Retrieve information about a Logos Delivery node.
   operationId: getNodeInfo
   tags:
     - debug
   responses:
     '200':
-      description: Information about a Waku v2 node.
+      description: Information about a Logos Delivery node.
       content:
         application/json:
           schema:

api-spec/debugapi_version.yaml

@@ -1,12 +1,12 @@
 get:
   summary: Get node version
-  description: Retrieve the Waku v2 node version.
+  description: Retrieve the Logos Delivery node version.
   operationId: getNodeVersion
   tags:
     - debug
   responses:
     '200':
-      description: The version of a Waku v2 node.
+      description: The version of a Logos Delivery node.
       content:
         text/plain:
           schema:

api-spec/healthapi.yaml

@@ -1,12 +1,12 @@
 get:
   summary: Get node health status
-  description: Retrieve status of a Waku v2 node.
+  description: Retrieve status of a Logos Delivery node.
   operationId: healthcheck
   tags:
     - health
   responses:
     '200':
-      description: Health report of a Waku v2 node and its protocols.
+      description: Health report of a Logos Delivery node and its protocols.
       content:
         application/json:
           schema:

api-spec/messagingapi_events_received.yaml

@@ -0,0 +1,16 @@
+# /messaging/v1/events/received:
+get: # get_messaging_v1_events_received
+  summary: Poll buffered received messages
+  description: Returns buffered received messages (up to the cache capacity, oldest first), then clears them (evict-after-poll). Optimized for polling; each record carries the message hash and the full received WakuMessage.
+  operationId: getMessagingReceivedMessages
+  tags:
+    - messaging
+  responses:
+    '200':
+      description: The buffered received messages, oldest first.
+      content:
+        application/json:
+          schema:
+            $ref: './schemas/apitypes.yaml#/ReceivedMessagesResponse'
+    '5XX':
+      description: Unexpected error.

api-spec/messagingapi_events_send.yaml

@@ -0,0 +1,16 @@
+# /messaging/v1/events/send:
+get: # get_messaging_v1_events_send
+  summary: Poll all buffered send events
+  description: Returns all buffered send events grouped by request id, then clears them (evict-after-poll). Send events are buffered because REST is a poll-based surface over the interactive MessagingClient events.
+  operationId: getMessagingSendEvents
+  tags:
+    - messaging
+  responses:
+    '200':
+      description: The buffered send events, grouped by request id.
+      content:
+        application/json:
+          schema:
+            $ref: './schemas/apitypes.yaml#/SendStatusList'
+    '5XX':
+      description: Unexpected error.

api-spec/messagingapi_events_send_by_id.yaml

@@ -0,0 +1,27 @@
+# /messaging/v1/events/send/{requestId}:
+get: # get_messaging_v1_events_send_by_id
+  summary: Poll the send events for one request id
+  description: Returns the buffered send events for a single request id, then removes them (evict-after-poll). The request id is the value returned by POST /messaging/v1/messages.
+  operationId: getMessagingSendEventsById
+  tags:
+    - messaging
+  parameters:
+    - in: path
+      name: requestId   # Note the name is the same as in the path
+      required: true
+      schema:
+        type: string
+      description: The request id returned by the send endpoint.
+  responses:
+    '200':
+      description: The buffered send events for the request id.
+      content:
+        application/json:
+          schema:
+            $ref: './schemas/apitypes.yaml#/SendStatus'
+    '404':
+      description: No send events buffered for the given request id.
+    '4XX':
+      description: Bad request.
+    '5XX':
+      description: Unexpected error.

api-spec/messagingapi_messages.yaml

@@ -0,0 +1,23 @@
+# /messaging/v1/messages:
+post: # post_messaging_v1_messages
+  summary: Send a message through the messaging client
+  description: Sends a message (a MessageEnvelope) through the messaging client and returns the request id used to correlate the subsequent send events.
+  operationId: postMessagingMessage
+  tags:
+    - messaging
+  requestBody:
+    content:
+      application/json:
+        schema:
+          $ref: './schemas/apitypes.yaml#/MessagingJsonEnvelope'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: './schemas/apitypes.yaml#/MessagingSendResponse'
+    '4XX':
+      description: Bad request.
+    '5XX':
+      description: Unexpected error.

api-spec/messagingapi_subscriptions.yaml

@@ -0,0 +1,50 @@
+# /messaging/v1/subscriptions:
+post: # post_messaging_v1_subscriptions
+  summary: Subscribe the messaging client to an array of content topics
+  description: Subscribe the messaging client to an array of Content topics.
+  operationId: postMessagingSubscriptions
+  tags:
+    - messaging
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: array
+          items:
+            $ref: './schemas/apitypes.yaml#/ContentTopic'
+  responses:
+    '200':
+      description: OK
+      content:
+        text/plain:
+          schema:
+            type: string
+    '4XX':
+      description: Bad request.
+    '5XX':
+      description: Unexpected error.
+
+delete: # delete_messaging_v1_subscriptions
+  summary: Unsubscribe the messaging client from an array of content topics
+  description: Unsubscribe the messaging client from an array of Content topics.
+  operationId: deleteMessagingSubscriptions
+  tags:
+    - messaging
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: array
+          items:
+            $ref: './schemas/apitypes.yaml#/ContentTopic'
+  responses:
+    '200':
+      description: OK
+      content:
+        text/plain:
+          schema:
+            type: string
+    '4XX':
+      description: Bad request.
+    '5XX':
+      description: Unexpected error.

api-spec/openapi.yaml

@@ -1,6 +1,6 @@
 openapi: 3.1.0
 info:
-  title: Waku V2 node REST API
+  title: Logos Delivery node REST API
   version: 1.0.0
   description:
   contact:
@@ -13,9 +13,9 @@ tags:
   - name: admin
     description: Control of the connected peers.
   - name: debug
-    description: Information about a Waku v2 node.
+    description: Information about a Logos Delivery node.
   - name: health
-    description: Health check of a Waku v2 node.
+    description: Health check of a Logos Delivery node.
   - name: lightpush
     description: Interface to request a message relay. See [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/) RFC
   - name: relay
@@ -28,6 +28,8 @@ tags:
     description: Control of the content filtering. See [12/WAKU2-FILTER](https://rfc.vac.dev/spec/12/) RFC
   - name: filter_legacy
     description: Obsolate Filter interface kept for compatibility reason. Will be removed in future.
+  - name: messaging
+    description: High-level messaging client interface (subscribe / send by content topic) and poll-based observation of send and received events.
 paths:
   /health:
     $ref: "./healthapi.yaml"
@@ -89,6 +91,16 @@ paths:
     $ref: "./filterapi_v2_subscriptions_all.yaml"
   /filter/v2/messages/{contentTopic}:
     $ref: "./filterapi_v2_messages.yaml"
+  /messaging/v1/subscriptions:
+    $ref: "./messagingapi_subscriptions.yaml"
+  /messaging/v1/messages:
+    $ref: "./messagingapi_messages.yaml"
+  /messaging/v1/events/send:
+    $ref: "./messagingapi_events_send.yaml"
+  /messaging/v1/events/send/{requestId}:
+    $ref: "./messagingapi_events_send_by_id.yaml"
+  /messaging/v1/events/received:
+    $ref: "./messagingapi_events_received.yaml"
 components:
   schemas:
     $ref: "./schemas/apitypes.yaml"

api-spec/schemas/apitypes.yaml

@@ -320,3 +320,90 @@ HealthReport:
         type: object
         additionalProperties:
           $ref: "#/HealthStatus"
+
+## Messaging API types
+
+MessagingJsonEnvelope:
+  type: object
+  description: JSON wire form of the messaging MessageEnvelope (the send input).
+  properties:
+    payload:
+      type: string
+      format: byte
+    contentTopic:
+      $ref: "#/ContentTopic"
+    ephemeral:
+      type: boolean
+    meta:
+      type: string
+      format: byte
+  required:
+    - payload
+    - contentTopic
+
+MessagingSendResponse:
+  type: object
+  properties:
+    requestId:
+      type: string
+      description: Correlates the send with its MessageSent / MessageError events.
+  required:
+    - requestId
+
+SendEventRecord:
+  type: object
+  properties:
+    kind:
+      type: string
+      enum:
+        - "sent"
+        - "propagated"
+        - "error"
+    messageHash:
+      type: string
+    error:
+      type: string
+      description: Populated only when kind is "error".
+    timestamp:
+      type: integer
+      format: int64
+      description: Nanoseconds, stamped when the event was cached.
+  required:
+    - kind
+    - messageHash
+    - timestamp
+
+SendStatus:
+  type: object
+  description: All send events observed so far for a single request id.
+  properties:
+    requestId:
+      type: string
+    events:
+      type: array
+      items:
+        $ref: "#/SendEventRecord"
+  required:
+    - requestId
+    - events
+
+SendStatusList:
+  type: array
+  items:
+    $ref: "#/SendStatus"
+
+ReceivedMessageRecord:
+  type: object
+  properties:
+    messageHash:
+      type: string
+    message:
+      $ref: "#/RelayWakuMessage"
+  required:
+    - messageHash
+    - message
+
+ReceivedMessagesResponse:
+  type: array
+  items:
+    $ref: "#/ReceivedMessageRecord"