swagger: "2.0"
info:
  description: "Squash debugget api sample."
  version: "1.0.0"
  title: "Squash Server"
  contact:
    email: "apiteam@solo.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
basePath: "/api/v1"
tags:
- name: "debugconfig"
  description: "Everything about your debugconfig"
  externalDocs:
    description: "Find out more"
    url: "http://swagger.io"
- name: "debugsessions"
  description: "Everything about your debug sessions"
schemes:
- "http"
paths:
  /debugconfig:
    post:
      tags:
      - "debugconfig"
      summary: "Add a new debug configuration for squash server."
      description: > 
                      Add a debug config to squash. A debug config instrucs squash what containers should be debugged, and now.
                      DebugConfig object consists of:
                        - Attachment: The object we are attaching to. either a specific container, or a service. 
                        in the case of the service, the squash will attach to the first container that hits a debug event.
                        - Breakpoints: A list of breakpoints. When "immediately" set to false, squash will wait for a debug event
                        (i.e a program crash) before giving the user access to the remote debugger. If breakpoints is set, squash will place them and will notify when the first breakpoint hits.
                        - image: The container image we are debugging. this is used for extra validation, as placing breakpoints on the wrong binary can lead to unexpected results.
                        - debugger: Type of debugger to use. "dlv" and "gdb" are supported now.
                        - immediately: Weather to attach immediatly or wait for debug event. can only be set to true if attachment type is container.

      operationId: "addDebugConfig"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "DebugConfig object that needs to be added"
        required: true
        schema:
          $ref: "#/definitions/DebugConfig"
      responses:
        201:
          description: "Debug config created"
          schema:
            $ref: "#/definitions/DebugConfig"
        400:
          description: "Bad request"
        404:
          description: "Attachment not found"
        422:
          description: "Invalid input"
        503:
          description: "Service Unavailable"
    get:
      tags:
      - "debugconfig"
      summary: "Retrun all debug configs" 
      description: "Retrun all debug configs"
      operationId: "getDebugConfigs"
      responses:
        200:
          description: OK
          schema:
            type: "array"
            items:
              $ref: "#/definitions/DebugConfig"
        400:
          description: "Invalid ID supplied"
        404:
          description: "Debug config not found"
        422:
          description: "Validation exception"
  /debugconfig/{debugConfigId}:
    patch:
      tags:
      - "debugconfig"
      summary: "Update an existing debug config"
      description: ""
      operationId: "updateDebugConfig"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "debugConfigId"
        in: "path"
        description: "ID of config to return"
        required: true
        type: "string"
      - in: "body"
        name: "body"
        description: "debug config edited"
        required: true
        schema:
          $ref: "#/definitions/DebugConfig"
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/DebugConfig"
        400:
          description: "Invalid ID supplied"
        404:
          description: "Debug config not found"
        422:
          description: "Validation exception"
    delete:
      tags:
      - "debugconfig"
      summary: "Delete a debug config" 
      description: "Delete a debug config"
      operationId: "deleteDebugConfig"
      parameters:
      - name: "debugConfigId"
        in: "path"
        description: "ID of config to return"
        required: true
        type: "string"
      responses:
        200:
          description: OK
        400:
          description: "Invalid ID supplied"
        404:
          description: "Debug config not found"
        422:
          description: "Validation exception"
    get:
      tags:
      - "debugconfig"
      summary: "Retrun a debug config" 
      description: "Retrun a debug config"
      operationId: "getDebugConfig"
      parameters:
      - name: "debugConfigId"
        in: "path"
        description: "ID of config to return"
        required: true
        type: "string"
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/DebugConfig"
        400:
          description: "Invalid ID supplied"
        404:
          description: "Debug config not found"
        422:
          description: "Validation exception"
  /debugconfig/platform/containers/{node}/latest:
    delete:
      tags:
      - "debugconfig"
      summary: "Pop the latest debugconfig for a node in the cluster - this is used by the squash client." 
      description: ""
      operationId: "popContainerToDebug"
      parameters:
      - name: "node"
        in: "path"
        description: "ID the node we are watching"
        required: true
        type: "string"
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/DebugConfig"
        400:
          description: "Invalid ID supplied"
        404:
          description: "Node note not found"
        408:
          description: "Timeout reached"

  /debugconfig/{debugConfigId}/session:
    put:
      tags:
      - "debugsessions"
      summary: "Add a new debug session - this is used by the squash client."
      description: >
                    When a debugger is attached, it should create a new debug session object under the debug config 
                    that caused the debug session. Only one debug session is allowed per debug config. Once a 
                    session is added, The service will stop being watched, and new debug configs for the same service can be created again.
      operationId: "putDebugSession"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "debugConfigId"
        in: "path"
        description: "debug config id."
        required: true
        type: "string"
      - name: "body"
        in: "body"
        description: "the debug session."
        required: true
        schema:
          $ref: "#/definitions/DebugSession"
      responses:
        201:
          description: "Debug session created"
          schema:
            $ref: "#/definitions/DebugSession"
        400:
          description: "Invalid ID supplied"
        404:
          description: "debug config not found"
        422:
          description: "Invalid input"
        412:
          description: "Debug state currently exists"  
    delete:
      tags:
      - "debugsessions"
      summary: "Wait and for a debug session is available. when it is available it is returned and deleted"
      description: >
                    Long-poll and wait for a debug session to arrive. 
                    The squash client will add a debug session to the debug config once a container associated with this 
                    debug config generated a debug event.
      operationId: "popDebugSession"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "debugConfigId"
        in: "path"
        description: "debug config id."
        required: true
        type: "string"
      - name: "X-Timeout"
        in: "header"
        type: number
      responses:
        200:
          description: "Debug session returned"
          schema:
            $ref: "#/definitions/DebugSession"
        400:
          description: "Invalid ID supplied"
        404:
          description: "debug config not found"
        408:
          description: "Timeout reached"
definitions:
  Attachment:
    type: "object"
    required:
    - "type"
    - "name"
    properties:
      type:
        type: "string"
        enum: ["service", "container"]
      name:
        type: "string"
  Breakpoint:
    type: "object"
    required:
    - "location"
    properties:
      location:
        type: "string"
      
  DebugConfig:
    type: "object"
    required:
    - "attachment"
    - "image"
    properties:
      id:
        type: "string"
      attachment:
        $ref: "#/definitions/Attachment"
      breakpoints:
        type: "array"
        items:
          $ref: "#/definitions/Breakpoint"
      image:
        type: "string"
      debugger:
        type: "string"
      immediately:
        type: "boolean"
      active:
        type: "boolean"

  DebugSession:
    type: "object"
    required:
    - "debugConfigId"
    properties:
      url:
        type: "string"
      debugConfigId:
        type: "string"
externalDocs:
  description: "Find out more about Squash"
  url: "https://github.com/solo-io/squash"