<commit_before>swagger: "2.0"
info:
  title: Firecracker v0.4 API
  description: Firecraker v0.4 - RESTful public-facing API.
               The API is accessible through HTTP calls on specific URLs carrying JSON modeled data.
               The transport medium is a Unix Domain Socket.
  version: 0.4.0
  termsOfService: ""
  contact:
    email: "<EMAIL>"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"

host: "localhost"
basePath: "/"

schemes:
  - http
consumes:
  - application/json
produces:
  - application/json

paths:
  /:
    get:
      summary: Return general information about an instance.
      operationId: describeInstance
      responses:
        200:
          description: The instance information
          schema:
            $ref: "#/definitions/InstanceInfo"
        default:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/Error"
  /actions/{action_id}:
    get:
      summary: Return detailed information about an action.
      operationId: describeInstanceAction
      parameters:
      - name: action_id
        in: path
        description: The action identifier
        required: true
        type: string
      responses:
        200:
          description: The instance action information
          schema:
            $ref: "#/definitions/InstanceActionInfo"
        404:
          description: Action not found
          schema:
            $ref: "#/definitions/Error"
        409:
          description: Action is still pending
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/Error"
    put:
      summary: Creates an instance action.
      operationId: createInstanceAction
      parameters:
      - name: action_id
        in: path
        description: The action identifier
        required: true
        type: string
      - name: info
        in: body
        required: true
        schema:
          $ref: "#/definitions/InstanceActionInfo"
      responses:
        201:
          description: Action created
        default:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/Error"

  /boot-source:
    put:
      summary: Creates new boot source. If boot source already exists,
               updates its state based on new input. Will fail if update is not possible.
               The only supported boot source is LocalImage.
      operationId: putGuestBootSource
      parameters:
      - name: body
        in: body
        description: Guest boot source properties
        required: true
        schema:
          $ref: "#/definitions/BootSource"
      responses:
        201:
          description: Boot source created
        204:
          description: Boot source updated
        400:
          description: Boot source cannot be created due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /drives/{drive_id}:
    put:
      summary: Creates new drive with ID specified by drive_id path parameter.
               If a drive with the specified ID already exists, updates its state based on new input.
               Will fail if update is not possible.
      operationId: putGuestDriveByID
      parameters:
      - name: drive_id
        in: path
        description: The id of the guest drive
        required: true
        type: string
      - name: body
        in: body
        description: Guest drive properties
        required: true
        schema:
          $ref: "#/definitions/Drive"
      responses:
        201:
          description: Drive created
        204:
          description: Drive updated
        400:
          description: Drive cannot be created due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error.
          schema:
            $ref: "#/definitions/Error"

  /logger:
      put:
        summary: Initializes the logging system by specifying a log path on the host.
        operationId: putLogger
        parameters:
        - name: body
          in: body
          description: Logging system description
          required: true
          schema:
            $ref: "#/definitions/Logger"
        responses:
          201:
            description: Logger created.
          400:
            description: Logger cannot be initialized due to bad input.
            schema:
              $ref: "#/definitions/Error"
          default:
            description: Internal server error.
            schema:
              $ref: "#/definitions/Error"

  /machine-config:
    get:
      summary: Get the machine configuration of the VM.
      description: Get the machine configuration of the VM. When called before the PUT operation, it will return
                   the default values for the vCPU count (=1), memory size (=128 MiB), Hyperthreading is disabled and
                   there is no CPU Template.
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/MachineConfiguration"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

    put:
      summary: Updates the Virtual Machine Configuration with the specified input.
               The Machine Configuration has default values for the vCPU count (=1) and the memory size (=256 MiB).
               When Hyperthreading is enabled, the vCPU count has to be either 1 or an even number.
               is disabled, there are no restrictions regarding the vCPU count.
               If one of the parameters does not have a correct value, the update fails and no fields are updated.
      operationId: putMachineConfiguration
      parameters:
      - name: body
        in: body
        description: Machine Configuration Parameters
        schema:
          $ref: "#/definitions/MachineConfiguration"
      responses:
        201:
          description: Machine Configuration created
        204:
          description: Machine Configuration updated
        400:
          description: Machine Configuration cannot be updated due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /network-interfaces/{iface_id}:
    put:
      summary: Creates new network interface with ID specified by iface_id path parameter.
               If network interface with specified ID already exists,
               updates its state based on new input. Will fail if update is not possible.
      operationId: putGuestNetworkInterfaceByID
      parameters:
      - name: iface_id
        in: path
        description: The id of the guest network interface
        required: true
        type: string
      - name: body
        in: body
        description: Guest network interface properties
        required: true
        schema:
          $ref: "#/definitions/NetworkInterface"
      responses:
        201:
          description: Network interface created
        204:
          description: Network interface updated
        400:
          description: Network interface cannot be created due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

definitions:
  BootSource:
    type: object
    description:
      Boot source descriptor. The only supported boot source type is the Local Image. Network Boot and Drive Boot will
      be added in future releases.
    properties:
      boot_source_id:
        type: string
        description: Unique identifier for the boot source
      source_type:
        type: string
        description: Type of boot source
        enum:
        - LocalImage
      local_image:
        $ref: "#/definitions/LocalImage"
      boot_args:
        type: string
        description: Kernel boot arguments

  CpuTemplate:
    type: string
    description:
      The CPU Template defines a set of flags to be disabled from the microvm so that
      the features exposed to the guest are the same as in the selected instance type.
    enum:
      - C3
      - T2

  DeviceState:
    type: string
    description:
      The valid states for a Device. So far, a device can only be in the Attached mode.
      Future valid values will be Detaching and Detached.
    enum:
      - Attached

  DrivePermissions:
    type: string
    enum:
      - ro
      - rw

  Drive:
    type: object
    required:
      - drive_id
    properties:
      drive_id:
        type: string
      path_on_host:
        type: string
        description: Host level path for the guest drive
      is_root_device:
        type: boolean
      permissions:
        $ref: "#/definitions/DrivePermissions"
      rate_limiter:
        $ref: "#/definitions/RateLimiter"
      state:
        $ref: "#/definitions/DeviceState"

  Error:
    properties:
      faultMessage:
        type: string
        description: A description of the error condition

  InstanceActionInfo:
    type: object
    description: Variant wrapper containing the real action
    required:
      - action_id
    properties:
      action_id:
        type: string
        minLength: 1
        maxLength: 64
      action_type:
        description: Enumeration indicating what type of action is contained in the payload
        type: string
        enum:
          - InstanceStart
          - InstanceHalt
      # Timestamp generated by FC - output only
      timestamp:
        type: string

  InstanceInfo:
    properties:
      state:
        description: The current detailed state of the Firecracker instance.
                     This value is read-only for the control-plane.
        type: string
        enum:
          - Uninitialized
          - Starting
          - Running
          - Halting
          - Halted

  LocalImage:
    type: object
    description: |
      Locations for local kernel image.
    properties:
      kernel_image_path:
        type: string
        description: Host level path to the kernel image used to boot the guest

  Logger:
    type: object
    description:
      Describes the configuration option for the logger intitialization.
    properties:
      path:
        type: string
        description: The path on the host for the log file.
      level:
        type: string
        description: Set the level.
        enum: [Error, Warning, Info, Debug]
      show_level:
        type: boolean
        description: Whether or not to output the level in the logs.
      show_log_origin:
        type: boolean
        description: Whether or not to include the file path and line number of the log's origin.

  MachineConfiguration:
    type: object
    description: Machine Configuration descriptor by which you can specify the number
                 of vCPU of one machine with vcpu_count, the memory size in MiB with
                 mem_size_mib, the CPU template with cpu_template and whether Hyperthreading
                 is enabled/disabled with ht_enabled
    properties:
      vcpu_count:
        type: integer
        description: Number of vCPUs (either 1 or an even number)
      mem_size_mib:
        type: integer
        description: Memory size of VM
      ht_enabled:
        type: boolean
        description: Flag for enabling/disabling Hyperthreading
      cpu_template:
        $ref: "#/definitions/CpuTemplate"

  NetworkInterface:
    type: object
    required:
      - iface_id
    properties:
      iface_id:
        type: string
      guest_mac:
        type: string<commit_msg>Correct some info therein, and beautify the api yaml.<commit_after>swagger: "2.0"
info:
  title: Firecracker v0.4 API
  description: Firecraker v0.4 - RESTful public-facing API.
               The API is accessible through HTTP calls on specific URLs carrying JSON modeled data.
               The transport medium is a Unix Domain Socket.
  version: 0.4.0
  termsOfService: ""
  contact:
    email: "<EMAIL>"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"

host: "localhost"
basePath: "/"

schemes:
  - http
consumes:
  - application/json
produces:
  - application/json

paths:
  /:
    get:
      summary: Returns general information about an instance.
      operationId: describeInstance
      responses:
        200:
          description: The instance information
          schema:
            $ref: "#/definitions/InstanceInfo"
        default:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/Error"
  /actions/{action_id}:
    get:
      summary: Returns detailed information about an action.
      operationId: describeInstanceAction
      parameters:
      - name: action_id
        in: path
        description: The action identifier
        required: true
        type: string
      responses:
        200:
          description: The instance action information
          schema:
            $ref: "#/definitions/InstanceActionInfo"
        404:
          description: Action not found
          schema:
            $ref: "#/definitions/Error"
        409:
          description: Action is still pending
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/Error"
    put:
      summary: Creates an instance action.
      operationId: createInstanceAction
      parameters:
      - name: action_id
        in: path
        description: The action identifier
        required: true
        type: string
      - name: info
        in: body
        required: true
        schema:
          $ref: "#/definitions/InstanceActionInfo"
      responses:
        201:
          description: Action created
        default:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/Error"

  /boot-source:
    put:
      summary: Creates or updates the boot source.
      description:
        Creates new boot source if one does not already exist, otherwise updates it.
        Will fail if update is not possible.
        Note that the only currently supported boot source is LocalImage.
      operationId: putGuestBootSource
      parameters:
      - name: body
        in: body
        description: Guest boot source properties
        required: true
        schema:
          $ref: "#/definitions/BootSource"
      responses:
        201:
          description: Boot source created
        204:
          description: Boot source updated
        400:
          description: Boot source cannot be created due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /drives/{drive_id}:
    put:
      summary: Creates or updates a drive.
      description:
        Creates new drive with ID specified by drive_id path parameter.
        If a drive with the specified ID already exists, updates its state based on new input.
        Will fail if update is not possible.
      operationId: putGuestDriveByID
      parameters:
      - name: drive_id
        in: path
        description: The id of the guest drive
        required: true
        type: string
      - name: body
        in: body
        description: Guest drive properties
        required: true
        schema:
          $ref: "#/definitions/Drive"
      responses:
        201:
          description: Drive created
        204:
          description: Drive updated
        400:
          description: Drive cannot be created due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error.
          schema:
            $ref: "#/definitions/Error"

  /logger:
      put:
        summary: Initializes the logging system by specifying a log path on the host.
        operationId: putLogger
        parameters:
        - name: body
          in: body
          description: Logging system description
          required: true
          schema:
            $ref: "#/definitions/Logger"
        responses:
          201:
            description: Logger created.
          400:
            description: Logger cannot be initialized due to bad input.
            schema:
              $ref: "#/definitions/Error"
          default:
            description: Internal server error.
            schema:
              $ref: "#/definitions/Error"

  /machine-config:
    get:
      summary: Gets the machine configuration of the VM.
      description:
        Gets the machine configuration of the VM. When called before the PUT operation, it
        will return the default values for the vCPU count (=1), memory size (=128 MiB).
        By default Hyperthreading is disabled and there is no CPU Template.
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/MachineConfiguration"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

    put:
      summary: Updates the Machine Configuration of the VM.
      description:
        Updates the Virtual Machine Configuration with the specified input.
        Firecracker starts with default values for vCPU count (=1) and memory size (=128 MiB).
        With Hyperthreading enabled, the vCPU count is restricted to be 1 or an even number,
        otherwise there are no restrictions regarding the vCPU count.
        If any of the parameters has an incorrect value, the whole update fails.
      operationId: putMachineConfiguration
      parameters:
      - name: body
        in: body
        description: Machine Configuration Parameters
        schema:
          $ref: "#/definitions/MachineConfiguration"
      responses:
        201:
          description: Machine Configuration created
        204:
          description: Machine Configuration updated
        400:
          description: Machine Configuration cannot be updated due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /network-interfaces/{iface_id}:
    put:
      summary: Creates a network interface.
      description:
        Creates new network interface with ID specified by iface_id path parameter.
        Updating existing interfaces is currently not allowed.
      operationId: putGuestNetworkInterfaceByID
      parameters:
      - name: iface_id
        in: path
        description: The id of the guest network interface
        required: true
        type: string
      - name: body
        in: body
        description: Guest network interface properties
        required: true
        schema:
          $ref: "#/definitions/NetworkInterface"
      responses:
        201:
          description: Network interface created
        400:
          description: Network interface cannot be created due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

definitions:
  BootSource:
    type: object
    description:
      Boot source descriptor. The only supported boot source type is the Local Image.
      Network Boot and Drive Boot will be added in future releases.
    properties:
      boot_source_id:
        type: string
        description: Unique identifier for the boot source
      source_type:
        type: string
        description: Type of boot source
        enum:
        - LocalImage
      local_image:
        $ref: "#/definitions/LocalImage"
      boot_args:
        type: string
        description: Kernel boot arguments

  CpuTemplate:
    type: string
    description:
      The CPU Template defines a set of flags to be disabled from the microvm so that
      the features exposed to the guest are the same as in the selected instance type.
    enum:
      - C3
      - T2

  DeviceState:
    type: string
    description:
      The valid states for a Device. So far, a device can only be in the Attached mode.
      Future valid values will be Detaching and Detached.
    enum:
      - Attached

  DrivePermissions:
    type: string
    enum:
      - ro
      - rw

  Drive:
    type: object
    required:
      - drive_id
    properties:
      drive_id:
        type: string
      path_on_host:
        type: string
        description: Host level path for the guest drive
      is_root_device:
        type: boolean
      permissions:
        $ref: "#/definitions/DrivePermissions"
      rate_limiter:
        $ref: "#/definitions/RateLimiter"
      state:
        $ref: "#/definitions/DeviceState"

  Error:
    properties:
      faultMessage:
        type: string
        description: A description of the error condition

  InstanceActionInfo:
    type: object
    description:
      Variant wrapper containing the real action.
      The timestamp field is read-only, trying to update/change it with an API call will fail.
    required:
      - action_id
    properties:
      action_id:
        type: string
        minLength: 1
        maxLength: 64
      action_type:
        description: Enumeration indicating what type of action is contained in the payload
        type: string
        enum:
          - InstanceStart
          - InstanceHalt
      timestamp:
        type: string

  InstanceInfo:
    properties:
      state:
        description:
          The current detailed state of the Firecracker instance.
          This value is read-only for the control-plane.
        type: string
        enum:
          - Uninitialized
          - Starting
          - Running
          - Halting
          - Halted

  LocalImage:
    type: object
    description:
      Locations for local kernel image.
    properties:
      kernel_image_path:
        type: string
        description: Host level path to the kernel image used to boot the guest

  Logger:
    type: object
    description:
      Describes the configuration option for the logger intitialization.
    properties:
      path:
        type: string
        description: The path on the host for the log file.
      level:
        type: string
        description: Set the level.
        enum: [Error, Warning, Info, Debug]
      show_level:
        type: boolean
        description: Whether or not to output the level in the logs.
      show_log_origin:
        type: boolean
        description: Whether or not to include the file path and line number of the log's origin.

  MachineConfiguration:
    type: object
    description:
      Describes the number of vCPUs, memory size, Hyperthreading capabilities and
      the CPU template.
    properties:
      vcpu_count:
        type: integer
        description: Number of vCPUs (either 1 or an even number)
      mem_size_mib:
        type: integer
        description: Memory size of VM
      ht_enabled:
        type: boolean
        description: Flag for enabling/disabling Hyperthreading
      cpu_template:
        $ref: "#/definitions/CpuTemplate"

  NetworkInterface:
    type: object
    description:
      Defines a network interface.
    required:
      - iface_id
    properties:
      iface_id:
        type: string
      guest_mac:
        type: string
{'fraction_non_alphanumeric': 0.05798319327731093, 'fraction_numerical': 0.0072689075630252105, 'mean_word_length': 1.8500778349898215, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5545374', 'n_tokens_mistral': 5924, 'n_tokens_neox': 5757, 'n_words': 2291}