api.yaml

swagger: "2.0"
info:
  description: "Squash debugger api."
  version: "2.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/v2"
tags:
- name: "debugattachment"
  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:
  /debugattachment:
    post:
      tags:
      - "debugattachment"
      summary: "Request squash to attach to a running container."
      description: >
                      A debug attachment instructs squash to attach to a container. Debug attachment is made of
                        - 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. if not provided huerisrtics will be used to identify it.
                        - debugger: Type of debugger to use. "dlv" and "gdb" are supported now.
                        - match_request: Whether to match this attachment to a debug request. This is used in automated use-cases to guarantee that the attachment matches a pending debug request.
      operationId: "addDebugAttachment"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "DebugAttachment object"
        required: true
        schema:
          $ref: "#/definitions/DebugAttachment"
      responses:
        201:
          description: "Debug attachment created"
          schema:
            $ref: "#/definitions/DebugAttachment"
        400:
          description: "Bad request"
        404:
          description: "Not found"
        422:
          description: "Invalid input"
        503:
          description: "Service Unavailable"
    get:
      tags:
      - "debugattachment"
      summary: "Return all debug attachment"
      description: "Return all debug attachment"
      operationId: "getDebugAttachments"
      parameters:
      - name: "wait"
        in: "query"
        description: "wait until there's something to return instead of returning an empty list"
        required: false
        type: "boolean"
      - name: "node"
        in: "query"
        description: "filter by node that the debugattachment is assigned to"
        required: false
        type: "string"
      - name: "state"
        in: "query"
        description: "filter by the state of debugattachment is assigned to"
        required: false
        type: "string"
      - name: "states"
        in: "query"
        description: "filter by any of the states of the debugattachment (for example, attached and error)"
        required: false
        type: "array"
        items:
          type: "string"
      - name: "names"
        in: "query"
        description: "Only get a subset of debugattachments"
        required: false
        type: "array"
        items:
          type: "string"
      - name: "if-none-match"
        in: "header"
        description: "If the quering for all the attachments on a node, this case be used to wait for an update"
        required: false
        type: string
      - name: "X-Timeout"
        in: "header"
        type: number
      responses:
        200:
          description: OK
          headers:
            ETag:
              description: When querying for all the sessions on the node this can be used for to wait for a version update.
              type: string
          schema:
            type: "array"
            items:
              $ref: "#/definitions/DebugAttachment"
        408:
          description: "Request timed out"
        422:
          description: "Validation exception"
  /debugattachment/{debugAttachmentId}:
    patch:
      tags:
      - "debugattachment"
      summary: "Modify an existing attachment."
      description: >
                      Modify an existing attachment.
      operationId: "patchDebugAttachment"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "debugAttachmentId"
        in: "path"
        description: "ID of config to return"
        required: true
        type: "string"
      - in: "body"
        name: "body"
        description: "DebugAttachment object"
        required: true
        schema:
          $ref: "#/definitions/DebugAttachment"
      responses:
        200:
          description: "Debug attachment modified"
          schema:
            $ref: "#/definitions/DebugAttachment"
        400:
          description: "Bad request"
        404:
          description: "Not found"
        409:
          description: "Conflict"
        422:
          description: "Invalid input"
        503:
          description: "Service Unavailable"
    delete:
      tags:
      - "debugattachment"
      summary: "Delete a debug attachment"
      description: "Delete a debug attachment. be careful not to delete on during attaching phase."
      operationId: "deleteDebugAttachment"
      parameters:
      - name: "debugAttachmentId"
        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:
      - "debugattachment"
      summary: "Return a debug attachment"
      description: "Return a debug attachment"
      operationId: "getDebugAttachment"
      parameters:
      - name: "debugAttachmentId"
        in: "path"
        description: "ID of config to return"
        required: true
        type: "string"
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/DebugAttachment"
        400:
          description: "Invalid ID supplied"
        404:
          description: "Debug config not found"
        422:
          description: "Validation exception"
  /debugrequest:
    get:
      tags:
      - "debugrequest"
      summary: "Return all debug request"
      description: "Return all debug requests"
      operationId: "getDebugRequests"
      responses:
        200:
          description: OK
          schema:
            type: "array"
            items:
              $ref: "#/definitions/DebugRequest"
        422:
          description: "Validation exception"
    post:
      tags:
      - "debugrequest"
      summary: "Return a debug attachment"
      description: "Return a debug attachment"
      operationId: "createDebugRequest"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "DebugRequest object"
        required: true
        schema:
          $ref: "#/definitions/DebugRequest"
      responses:
        201:
          description: Created
          schema:
            $ref: "#/definitions/DebugRequest"
  /debugrequest/{debugRequestId}:
    get:
      tags:
      - "debugrequest"
      summary: "Get a debug request"
      description: "Get a debug request"
      operationId: "getDebugRequest"
      parameters:
      - name: "debugRequestId"
        in: "path"
        description: "ID of config to return"
        required: true
        type: "string"
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/DebugRequest"
        404:
          description: "Not found"
    delete:
      tags:
      - "debugrequest"
      summary: "Delete a debug request"
      description: "Delete a debug request."
      operationId: "deleteDebugRequest"
      parameters:
      - name: "debugRequestId"
        in: "path"
        description: "ID of debug request"
        required: true
        type: "string"
      responses:
        200:
          description: OK
        400:
          description: "Invalid ID supplied"
        404:
          description: "Debug request not found"
        422:
          description: "Validation exception"

definitions:
  ObjectMeta:
    type: object
    properties:
      name:
        type: string
      version:
        type: string

  Attachment:
    type: object
    # platform specific attachment information

  DebugAttachmentSpec:
    type: object
    required:
    - "attachment"
    properties:
      attachment:
        $ref: "#/definitions/Attachment"
      debugger:
        type: string
      image:
        type: string
      process_name:
        type: string
      node:
        type: string
      match_request:
        type: boolean
        description: If true, this attachment must match a pending debug request.

  DebugAttachmentStatus:
    type: object
    properties:
      state:
        type: string
        enum: [none, attaching, attached, error]
      debug_server_address:
        type: string

  DebugAttachment:
    type: object
    required:
    - "spec"
    properties:
      metadata:
        $ref: "#/definitions/ObjectMeta"
      spec:
        $ref: "#/definitions/DebugAttachmentSpec"
      status:
        $ref: "#/definitions/DebugAttachmentStatus"

  DebugRequestSpec:
    type: object
    required:
    - "image"
    - "debugger"
    properties:
      image:
        type: string
      debugger:
        type: string
      process_name:
        type: string


  DebugRequestStatus:
    type: object
    properties:
      debug_attachment_ref:
        type: string

  DebugRequest:
    type: object
    required:
    - "spec"
    properties:
      metadata:
        $ref: "#/definitions/ObjectMeta"
      spec:
        $ref: "#/definitions/DebugRequestSpec"
      status:
        $ref: "#/definitions/DebugRequestStatus"
externalDocs:
  description: "Find out more about Squash"
  url: "https://github.com/solo-io/squash"