# Worterbuch server messages schema
#
# Copyright (C) 2024 Michael Bachmann
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.

title: ServerMessage
type: object
properties:
  welcome:
    description: A message sent by the server to provide the client with basic information about itself
    type: object
    properties:
      info:
        $ref: "#/components/schemas/ServerInfo"
      clientId:
        description: A unique client ID that is valid for the duration of the connection
        type: string
    additionalProperties: false
    required:
      - info
      - clientId
  authorized:
    description: A message sent by the server to indicate that client authorization was successful
    type: object
    properties:
      authorized:
        $ref: "#/properties/ack"
  state:
    description: A message sent by the server in response to a Get or Delete message
    properties:
      transactionId:
        description: A unique transaction ID
        type: integer
        format: u64
      value:
        $ref: "#/components/schemas/Value"
      deleted:
        $ref: "#/components/schemas/Value"
    additionalProperties: false
    required:
      - transactionId
    oneOf:
      - required:
          - value
      - required:
          - deleted
  pState:
    description: A message sent by the server in response to a PGet, PDelete or
      Subscribe/PSubscribe message
    properties:
      transactionId:
        description: A unique transaction ID
        type: integer
        format: u64
      requestPattern:
        type: string
      keyValuePairs:
        $ref: "#/components/schemas/KeyValuePairs"
      deleted:
        $ref: "#/components/schemas/KeyValuePairs"
    additionalProperties: false
    required:
      - transactionId
      - requestPattern
    oneOf:
      - required:
          - keyValuePairs
      - required:
          - deleted
  ack:
    description: A message sent by the server to confirm that a client message has been processed
    properties:
      transactionId:
        description: A unique transaction ID
        type: integer
        format: u64
    additionalProperties: false
    required:
      - transactionId
  err:
    description: A message sent by the server to indicate that there was an error processing a client message
    properties:
      transactionId:
        description: A unique transaction ID
        type: integer
        format: u64
      errorCode:
        type: integer
        format: u8
      metadata:
        type: string
    additionalProperties: false
    required:
      - transactionId
      - errorCode
      - metadata
  lsState:
    description: A message sent by the server in response to an Ls message
    properties:
      transactionId:
        description: A unique transaction ID
        type: integer
        format: u64
      children:
        type: array
        items:
          type: string
    additionalProperties: false
    required:
      - transactionId
      - children
additionalProperties: false
oneOf:
  - required:
      - welcome
  - required:
      - ack
  - required:
      - err
  - required:
      - state
  - required:
      - pState
  - required:
      - lsState
components:
  schemas:
    ServerInfo:
      description: Information about the server and how to communicate with it
      type: object
      properties:
        version:
          description: The server's software version
          type: string
        protocolVersion:
          description: The protocol version implemented by the server
          type: string
        authorizationRequired:
          description: Whether or not the client need to be authorized before sending requests to the server
          type: boolean
      additionalProperties: false
      required:
        - version
        - protocolVersion
        - authorizationRequired
    Value:
      description: A value on worterbuch
    KeyValuePair:
      description: A key/value pair where the key is always a string and the value can be anything
      type: object
      properties:
        key:
          description: The key
          type: string
        value:
          $ref: "#/components/schemas/Value"
      additionalProperties: false
      required:
        - key
        - value
    KeyValuePairs:
      type: array
      minItems: 1
      items:
        $ref: "#/components/schemas/KeyValuePair"