---
openapi: 3.1.0
info:
  title: App Mesh REST API
  description: API documentation for App Mesh.
  version: 2.2.1

paths:
  /appmesh/login:
    post:
      summary: Authenticate user and obtain access token.
      tags: [Identity]
      security:
        - BasicAuth: []
      parameters:
        - name: X-Totp-Code
          in: header
          required: false
          schema:
            type: string
          description: Optional TOTP code for two-factor authentication.
        - name: X-Expire-Seconds
          in: header
          required: false
          schema:
            type: integer
            default: 3600
          description: Optional token expiration time in seconds.
        - name: X-Audience
          in: header
          required: false
          schema:
            type: string
            default: "appmesh-service"
          description: JWT audience.
        - name: X-Set-Cookie
          in: header
          required: false
          schema:
            type: boolean
            default: false
          description: Optional to request cookie authentication.
      responses:
        "200":
          $ref: "#/components/responses/TokenResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "428":
          description: Precondition Required - TOTP required.
          content:
            application/json:
              schema:
                type: object
                properties:
                  WWW-Authenticate:
                    type: string
                    example: 'TOTP realm="TOTP Authentication", qop="auth"'
                  totp_challenge:
                    type: string
                    example: "CHALLENGE-ABC"
                  status:
                    type: string
                    example: "TOTP_CHALLENGE_REQUIRED"
                  algorithm:
                    type: string
                    example: "HS256"
                  digits:
                    type: integer
                    example: 6
                  period:
                    type: integer
                    example: 60
                  expires:
                    type: integer
                    example: 1704067380

  /appmesh/auth:
    post:
      summary: Verify user token and permission.
      tags: [Authorization]
      security:
        - BearerAuth: []
      parameters:
        - name: X-Permission
          in: header
          schema:
            type: string
          description: Permission name to verify.
        - name: X-Audience
          in: header
          schema:
            type: string
            default: "appmesh-service"
          description: JWT audience.
      responses:
        "200":
          description: Verified successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  permission:
                    type: string
                    example: "app-view"
                  success:
                    type: boolean
                    example: true
                  user:
                    type: string
                    example: "admin"
                  audience:
                    type: string
                    example: "appmesh-service"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /appmesh/self/logoff:
    post:
      summary: Log out the current user.
      tags: [Identity]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: User logged out successfully.
        "401":
          $ref: "#/components/responses/Unauthorized"

  /appmesh/token/renew:
    post:
      summary: Renew access token.
      tags: [Identity]
      security:
        - BearerAuth: []
      parameters:
        - name: X-Expire-Seconds
          in: header
          required: false
          schema:
            type: integer
            default: 3600
          description: Optional token expiration time in seconds.
      responses:
        "200":
          $ref: "#/components/responses/TokenResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /appmesh/totp/secret:
    post:
      summary: Generate TOTP secret.
      tags: [TwoFactor]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: TOTP secret generated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  mfa_uri:
                    type: string
                    format: base64
                    example: "base64-encoded-mfa-uri(otpauth://totp/admin?secret=secret&issuer=AppMesh)"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /appmesh/totp/setup:
    post:
      summary: Setup TOTP for user and get new token.
      tags: [TwoFactor]
      security:
        - BearerAuth: []
      parameters:
        - name: X-Totp-Code
          in: header
          required: true
          schema:
            type: string
          description: 6-digit TOTP code.
      responses:
        "200":
          $ref: "#/components/responses/TokenResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /appmesh/totp/validate:
    post:
      summary: Validate TOTP code and get token.
      tags: [TwoFactor]
      parameters:
        - name: X-Set-Cookie
          in: header
          schema:
            type: boolean
          default: true
          description: Request to set cookie for authentication.
      requestBody:
        description: TOTP validation request.
        content:
          application/json:
            schema:
              type: object
              required: [user_name, totp_challenge, totp_code]
              properties:
                user_name:
                  type: string
                  example: "admin"
                  description: User name.
                totp_challenge:
                  type: string
                  example: "CHALLENGE-ABC"
                  description: TOTP challenge from login response.
                totp_code:
                  type: string
                  example: "123456"
                  description: 6-digit TOTP code.
                expire_seconds:
                  type: integer
                  example: 3600
                  description: Optional token expiration time in seconds.
      responses:
        "200":
          $ref: "#/components/responses/TokenResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /appmesh/totp/{user_name}/disable:
    post:
      summary: Disable TOTP for user.
      tags: [TwoFactor]
      security:
        - BearerAuth: []
      parameters:
        - name: user_name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: TOTP disabled successfully.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /appmesh/app/{app_name}/output:
    get:
      summary: Retrieve application output.
      tags: [ApplicationMonitor]
      security:
        - BearerAuth: []
      parameters:
        - name: app_name
          in: path
          required: true
          schema:
            type: string
        - name: stdout_position
          in: query
          schema:
            type: integer
          description: Starting read position, 0 means from the beginning.
        - name: stdout_index
          in: query
          schema:
            type: integer
          description: History process stdout index, 0 for current running process.
        - name: stdout_maxsize
          in: query
          schema:
            type: integer
          description: Maximum buffer size to read.
        - name: process_uuid
          in: query
          schema:
            type: string
          description: Specify the process ID for asynchronous app run.
        - name: timeout
          in: query
          schema:
            type: integer
          description: Wait time (seconds) for the running process to get the output.
      responses:
        "200":
          description: Application output retrieved successfully.
          content:
            text/plain:
              schema:
                type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/applications:
    get:
      summary: List all applications.
      tags: [ApplicationManagement]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: List of applications retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/app/{app_name}/health:
    get:
      summary: Check application health status.
      tags: [ApplicationMonitor]
      parameters:
        - name: app_name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Application health status retrieved successfully.
          content:
            application/json:
              schema:
                type: object
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/app/{app_name}/disable:
    post:
      summary: Disable Application
      tags: [ApplicationManagement]
      security:
        - BearerAuth: []
      parameters:
        - name: app_name
          in: path
          required: true
          schema:
            type: string
          description: Application name.
      responses:
        "200":
          description: Application disabled successfully.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/app/{app_name}:
    get:
      summary: View Application
      tags: [ApplicationManagement]
      security:
        - BearerAuth: []
      parameters:
        - name: app_name
          in: path
          required: true
          schema:
            type: string
          description: Application name.
      responses:
        "200":
          description: Application details retrieved successfully.
          content:
            application/json:
              schema:
                type: object
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

    put:
      summary: Add Application
      tags: [ApplicationManagement]
      security:
        - BearerAuth: []
      parameters:
        - name: app_name
          in: path
          required: true
          schema:
            type: string
          description: Application name.
      requestBody:
        description: Application definition
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "test-ping"
                description:
                  type: string
                  example: "appmesh ping test"
                command:
                  type: string
                  example: "ping github.com -w 300"
                shell:
                  type: boolean
                  example: true
                behavior:
                  type: object
                  properties:
                    control:
                      type: object
                      additionalProperties:
                        type: string
                      example:
                        "0": "standby"
                    exit:
                      type: string
                      example: "standby"
              required:
                - name
                - command
      responses:
        "201":
          description: Application added successfully.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "500":
          $ref: "#/components/responses/InternalServerError"

    delete:
      summary: Delete Application
      tags: [ApplicationManagement]
      security:
        - BearerAuth: []
      parameters:
        - name: app_name
          in: path
          required: true
          schema:
            type: string
          description: Application name.
      responses:
        "200":
          description: Application deleted successfully.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/app/{app_name}/enable:
    post:
      summary: Enable Application
      tags: [ApplicationManagement]
      security:
        - BearerAuth: []
      parameters:
        - name: app_name
          in: path
          required: true
          schema:
            type: string
          description: Application name.
      responses:
        "200":
          description: Application enabled successfully.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/app/run:
    post:
      summary: Run Application Asynchronously
      tags: [ApplicationRun]
      security:
        - BearerAuth: []
      parameters:
        - name: timeout
          in: query
          required: false
          schema:
            type: integer
          description: Maximum run time for the remote process, in seconds.
        - name: lifecycle
          in: query
          required: false
          schema:
            type: integer
          description: Maximum lifecycle time for the remote process, in seconds.
      requestBody:
        description: Application JSON definition.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                command:
                  type: string
                shell:
                  type: boolean
                session_login:
                  type: boolean
      responses:
        "200":
          description: Application running asynchronously.
          content:
            application/json:
              schema:
                type: object
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/app/syncrun:
    post:
      summary: Run Application Synchronously
      tags: [ApplicationRun]
      security:
        - BearerAuth: []
      parameters:
        - name: timeout
          in: query
          required: false
          schema:
            type: integer
          description: Maximum run time for the remote process, in seconds.
        - name: lifecycle
          in: query
          required: false
          schema:
            type: integer
          description: Maximum lifecycle time for the remote process, in seconds.
      requestBody:
        description: Application JSON definition.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                command:
                  type: string
                shell:
                  type: boolean
                session_login:
                  type: boolean
      responses:
        "200":
          description: Application running synchronously.
          content:
            application/json:
              schema:
                type: object
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/app/{app_name}/task:
    post:
      summary: Execute task on remote application and wait for result
      description: |
        Sends a task payload to a running App Mesh application and waits synchronously 
        for the result. The target application must be running and capable of processing 
        the task data. This is useful for request-response patterns where you need 
        immediate feedback from the application.
      tags: [TaskRun]
      security:
        - BearerAuth: []
      parameters:
        - name: app_name
          in: path
          required: true
          schema:
            type: string
            default: "pytask"
          description: Name of the target application registered in App Mesh.
        - name: timeout
          in: query
          required: false
          schema:
            type: integer
            default: 60
          description: Maximum time in seconds to wait for a response from the application.
      requestBody:
        description: Payload to deliver to the application.
        required: true
        content:
          text/plain:
            schema:
              type: string
              default: "import sys;print(sys.version_info)"
      responses:
        "200":
          description: Task executed successfully. Returns the result from the remote application.
          content:
            text/plain:
              schema:
                type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "408":
          description: Task timeout.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "417":
          description: Task interrupt.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          $ref: "#/components/responses/InternalServerError"

    delete:
      summary: Remove a submitted task
      description: |
        Client delete a submitted message which is under processing for an application.
      tags: [TaskRun]
      security:
        - BearerAuth: []
      parameters:
        - name: app_name
          in: path
          required: true
          schema:
            type: string
            default: "pytask"
          description: Name of the target application registered in App Mesh.
      responses:
        "200":
          description: Task exist and removed successfully.
        "208":
          description: Task not exist.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"

    get:
      summary: Fetch task data for the current application process
      description: |
        Used by the App Mesh application process to retrieve the payload sent by a client.
        Requires valid process UUID to identify the correct task.
      tags: [TaskRun]
      parameters:
        - name: app_name
          in: path
          required: true
          schema:
            type: string
            default: "pytask"
          description: Name of the current application registered in App Mesh.
        - name: process_key
          in: query
          required: true
          schema:
            type: string
          description: Credential of the running application process.
      responses:
        "200":
          description: Task data retrieved successfully.
          content:
            text/plain:
              schema:
                type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

    put:
      summary: Return the result of a task to the original client
      description: |
        Used by the App Mesh application process to return the result of the processed task back to the client.
        Requires the process UUID to correlate with the original task.
      tags: [TaskRun]
      parameters:
        - name: app_name
          in: path
          required: true
          schema:
            type: string
            default: "pytask"
          description: Name of the current application registered in App Mesh.
        - name: process_key
          in: query
          required: true
          schema:
            type: string
          description: Credential of the running application process.
      requestBody:
        description: Result payload to be returned to the client.
        required: true
        content:
          text/plain:
            schema:
              type: string
      responses:
        "200":
          description: Task result successfully returned.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/file/download:
    get:
      summary: Download File
      tags: [FileOperation]
      security:
        - BearerAuth: []
      parameters:
        - name: X-File-Path
          in: header
          required: true
          schema:
            type: string
          description: The remote file path.
      responses:
        "200":
          description: File downloaded.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/file/upload:
    post:
      summary: Upload File
      tags: [FileOperation]
      security:
        - BearerAuth: []
      parameters:
        - name: X-File-Path
          in: header
          required: true
          schema:
            type: string
          description: The remote file path.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: File uploaded successfully.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/labels:
    get:
      summary: View All Labels
      tags: [Configuration]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: List of labels.
          content:
            application/json:
              schema:
                type: object
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/label/{label_name}:
    put:
      summary: Add Label
      tags: [Configuration]
      security:
        - BearerAuth: []
      parameters:
        - name: label_name
          in: path
          required: true
          schema:
            type: string
          description: Label name.
        - name: value
          in: query
          required: true
          schema:
            type: string
          description: Label value.
      responses:
        "201":
          description: Label added.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"

    delete:
      summary: Delete Label
      tags: [Configuration]
      security:
        - BearerAuth: []
      parameters:
        - name: label_name
          in: path
          required: true
          schema:
            type: string
          description: Label name.
      responses:
        "200":
          description: Label deleted.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/config:
    get:
      summary: View Config
      tags: [Configuration]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Configuration details.
          content:
            application/json:
              schema:
                type: object
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"

    post:
      summary: Set Config
      tags: [Configuration]
      security:
        - BearerAuth: []
      requestBody:
        description: Configuration JSON segment.
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Configuration set.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/user/{user_name}/passwd:
    post:
      summary: Change User Password
      tags: [UserManagement]
      security:
        - BearerAuth: []
      parameters:
        - name: user_name
          in: path
          required: true
          schema:
            type: string
          description: User name.
      requestBody:
        description: New password definition. The password must be base64 encoded.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - old_password
                - new_password
              properties:
                old_password:
                  type: string
                  format: byte
                  description: Base64 encoded old password
                new_password:
                  type: string
                  format: byte
                  description: Base64 encoded new password
      responses:
        "200":
          description: Password changed.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/user/{user_name}/lock:
    post:
      summary: Lock User
      tags: [UserManagement]
      security:
        - BearerAuth: []
      parameters:
        - name: user_name
          in: path
          required: true
          schema:
            type: string
          description: User name.
      responses:
        "200":
          description: User locked.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/user/{user_name}/unlock:
    post:
      summary: Unlock User
      tags: [UserManagement]
      security:
        - BearerAuth: []
      parameters:
        - name: user_name
          in: path
          required: true
          schema:
            type: string
          description: User name.
      responses:
        "200":
          description: User unlocked.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/user/{user_name}:
    put:
      summary: Add User
      tags: [UserManagement]
      security:
        - BearerAuth: []
      parameters:
        - name: user_name
          in: path
          required: true
          schema:
            type: string
          description: User name.
      requestBody:
        description: User definition.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                exec_user:
                  type: string
                group:
                  type: string
                key:
                  type: string
                locked:
                  type: boolean
                mfa_enabled:
                  type: boolean
                mfa_key:
                  type: string
                roles:
                  type: array
                  items:
                    type: string
      responses:
        "201":
          description: User added.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "500":
          $ref: "#/components/responses/InternalServerError"

    delete:
      summary: Delete User
      tags: [UserManagement]
      security:
        - BearerAuth: []
      parameters:
        - name: user_name
          in: path
          required: true
          schema:
            type: string
          description: User name.
      responses:
        "200":
          description: User deleted.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/user/self:
    get:
      summary: View Self User
      tags: [UserManagement]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: User details.
          content:
            application/json:
              schema:
                type: object
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/users:
    get:
      summary: View All Users
      tags: [UserManagement]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: List of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/roles:
    get:
      summary: View All Roles
      tags: [Authorization]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: List of roles.
          content:
            application/json:
              schema:
                type: object
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/role/{role_name}:
    post:
      summary: Update Role
      tags: [Authorization]
      security:
        - BearerAuth: []
      parameters:
        - name: role_name
          in: path
          required: true
          schema:
            type: string
          description: Role name.
      requestBody:
        description: |
          Role permission definition.
          example: ["app-control", "app-delete"]
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        "200":
          description: Role updated.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "500":
          $ref: "#/components/responses/InternalServerError"

    delete:
      summary: Delete Role
      tags: [Authorization]
      security:
        - BearerAuth: []
      parameters:
        - name: role_name
          in: path
          required: true
          schema:
            type: string
          description: Role name.
      responses:
        "200":
          description: Role deleted.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/user/permissions:
    get:
      summary: View User Permissions
      tags: [Authorization]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: List of user permissions.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/permissions:
    get:
      summary: View All Permissions
      tags: [Authorization]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: List of permissions.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/user/groups:
    get:
      summary: View User Groups
      tags: [UserManagement]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: List of user groups.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/metrics:
    get:
      summary: View Prometheus Metrics
      tags: [Monitoring]
      responses:
        "200":
          description: Prometheus text-based exposition format.
          content:
            text/plain:
              schema:
                type: string
        "500":
          $ref: "#/components/responses/InternalServerError"

  /appmesh/resources:
    get:
      summary: View Server Resources Usage Information
      tags: [Monitoring]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Resource details in JSON format.
          content:
            application/json:
              schema:
                type: object
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT token obtained from /appmesh/login endpoint. 
        Include in Authorization header as: Bearer <token>
    BasicAuth:
      type: http
      scheme: basic
      description: |
        Username and password for initial authentication.
        Only used for login endpoint.

  schemas:
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message text
      required:
        - message
      example:
        message: "Error message"

  responses:
    BadRequest:
      description: Invalid request parameters or malformed request body
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            message: "Invalid parameter: id must be an integer"

    Unauthorized:
      description: Authentication required or invalid credentials
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            message: "Unauthorized access, please provide valid credentials"

    Forbidden:
      description: Insufficient permissions for the requested operation
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            message: "Forbidden: insufficient permissions"

    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            message: "Path not found GET:/unknown/path"

    PreconditionFailed:
      description: Request could not be processed due to logical/semantic issues
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            message: "Precondition failed: runtime validation error"

    InternalServerError:
      description: Unexpected internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            known:
              summary: Known exception
              value:
                message: "Internal server error"
            unknown:
              summary: Unknown exception
              value:
                message: "Unknown exception"

    TokenResponse:
      description: Successful token generation.
      content:
        application/json:
          schema:
            type: object
            properties:
              profile:
                type: object
                properties:
                  name:
                    type: string
                    example: "admin"
                  auth_time:
                    type: integer
                    example: 1704067200
              access_token:
                type: string
                example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
              token_type:
                type: string
                example: "Bearer"
              expire_time:
                type: integer
                example: 1704070800
              expire_seconds:
                type: integer
                example: 3600