openapi: 3.0.2
info:
  version: '1.0.0' 
  
  title: Mycelium management
  contact:
    url: 'https://github.com/threefoldtech/mycelium'
  license:
    name: Apache 2.0
    url: 'https://github.com/threefoldtech/mycelium/LICENSE'
  
  description: |
    This is the specification of the **mycelium** management API. It is used to perform admin tasks on the system, and
    to perform administrative duties.

externalDocs:
  description: For full documentation, check out the mycelium github repo.
  url: 'https://github.com/threefoldtech/mycelium'

tags:
  - name: Message
    description: Operations on the embedded message subsystem

servers:
  - url: 'http://localhost:8989'

paths:
  '/api/v1/messages':
    get:
      tags:
        - Message
      summary: Get a message from the inbound message queue
      description: |
        Get a message from the inbound message queue. By default, the message is removed from the queue and won't be shown again.
        If the peek query parameter is set to true, the message will be peeked, and the next call to this endpoint will show the same message.
        This method returns immediately by default: a message is returned if one is ready, and if there isn't nothing is returned. If the timeout
        query parameter is set, this call won't return for the given amount of seconds, unless a message is received
      operationId: popMessage
      parameters:
        - in: query
          name: peek
          required: false
          schema:
            type: boolean
          description: Whether to peek the message or not. If this is true, the message won't be removed from the inbound queue when it is read
          example: true
        - in: query
          name: timeout
          required: false
          schema: 
            type: integer
            format: int64
            minimum: 0
          description: |
            Amount of seconds to wait for a message to arrive if one is not available. Setting this to 0 is valid and will return
            a message if present, or return immediately if there isn't
          example: 60

      responses:
        '200':
          description: Message retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundMessage'
        '204':
          description: No message ready
    post:
      tags:
        - Message
      summary: Submit a new message to the system.
      description: |
        Push a new message to the systems outbound message queue. The system will continuously attempt to send the message until
        it is either fully transmitted, or the send deadline is expired.
      operationId: pushMessage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PushMessageBody'
      responses:
        '200':
          description: Message pushed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushMessageResponse'

  '/api/v1/messages/status/:id':
    get:
      tags:
        - Message
      summary: Get the status of an outbound message
      description: |
        Get information about the current state of an outbound message. This can be used to check the transmission
        state, size and destination of the message.
      operationId: getMessageInfo
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageStatusResponse'
        '404':
          description: Message not found


components:
  schemas:
    InboundMessage:
      description: A message received by the system
      type: object
      properties:
        id:
          description: Id of the message, hex encoded
          type: string
          minLength: 16
          maxLength: 16
          example: 0123456789abcdef
        src_ip:
          description: Sender overlay IP address
          type: string
          format: ipv6
          example: 249:abcd:0123:defa::1
        src_pk:
          description: Sender public key, hex encoded
          type: string
          minLength: 64
          maxLength: 64
          example: fedbca9876543210fedbca9876543210fedbca9876543210fedbca9876543210
        dst_ip:
          description: Receiver overlay IP address
          type: string
          format: ipv6
          example: 34f:b680:ba6e:7ced:355f:346f:d97b:eecb
        dst_pk:
          description: Receiver public key, hex encoded. This is the public key of the system
          type: string
          minLength: 64
          maxLength: 64
          example: 02468ace13579bdf02468ace13579bdf02468ace13579bdf02468ace13579bdf
        payload:
          description: The message payload, encoded in standard alphabet base64
          type: string
          format: byte
          example: xuV+

    PushMessageBody:
      description: A message to send to a given receiver
      type: object
      properties:
        dst:
          $ref: '#/components/schemas/MessageDestination'
        payload:
          description: The message to send, base64 encoded
          type: string
          format: byte
          example: xuV+

    MessageDestination:
      oneOf:
        - description: An IP in the subnet of the receiver node
          type: object 
          properties:
            ip:
              description: The target IP of the message
              format: ipv6
              example: 249:abcd:0123:defa::1
        - description: The hex encoded public key of the receiver node
          type: object
          properties:
            pk:
              description: The hex encoded public key of the target node
              type: string
              minLength: 64
              maxLength: 64
              example: bb39b4a3a4efd70f3e05e37887677e02efbda14681d0acd3882bc0f754792c32

    PushMessageResponse:
      description: The ID generated for a message after pushing it to the system
      type: object
      properties:
        id:
          description: Id of the message, hex encoded
          type: string
          minLength: 16
          maxLength: 16
          example: 0123456789abcdef

    MessageStatusResponse:
      description: Information about an outobund message
      type: object
      properties:
        dst:
          description: Ip address of the receiving node
          type: string
          format: ipv6
          example: 249:abcd:0123:defa::1
        state: 
          $ref: '#/components/schemas/TransmissionState'
        created:
          description: Unix timestamp of when this message was created
          type: integer
          format: int64
          example: 1649512789
        deadline:
          description: Unix timestamp of when this message will expire. If the message is not received before this, the system will give up
          type: integer
          format: int64
          example: 1649513089
        msg_len:
          description: Length of the message in bytes
          type: integer
          minimum: 0
          example: 27

    TransmissionState:
      description: The state of an outbound message in it's lifetime
      oneOf:
        - type: string
          enum: ['pending', 'received', 'read', 'aborted']
          example: 'received'
        - type: object
          properties:
            sending:
              type: object
              properties:
                pending:
                  type: integer
                  minimum: 0
                  example: 5
                sent:
                  type: integer
                  minimum: 0
                  example: 17
                acked:
                  type: integer
                  minimum: 0
                  example: 3
      example: 'received'