<commit_before>openapi: 3.0.0
info:
  title: UpdateHub Agent local HTTP API routes
  description: |-
    These are the routes available through HTTP on the device running the
    UpdateHub Agent.
  version: "2.0"
servers:
  - url: "http://localhost:8080"
    variables: {}

paths:
  "/info":
    get:
      summary: "Get general information."
      responses:
        "200":
          description: "Request accepted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentInfo"

  "/probe":
    post:
      summary: "Actively probe the server."
      description: |-
        Probe the server and download the update metadata if  available.
        Returns a json object containing the "update_available" boolean field.
        It also may contain a "try_again_in" field which means the caller should
        try the request again 'n' seconds from now, where 'n' is the value of
        "try_again_in".

        This request accepts a "server_address" parameter on POST. When it's present,
        it will use the address for the triggered probe (and the update procedure too
        in case there is an update available).

        If agent is busy (e.g. downloading a object or installing an object) the
        returned http code is 202.
      requestBody:
        required: false
        description: "The custom server to probe"
        content:
          application/json:
              schema:
                $ref: "#/components/schemas/ProbeCustomServer"
      responses:
        "200":
          description: "Request accepted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProbeInfo"
        "202":
          description: "Agent is busy"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentStatus"

  "/local_install":
    post:
      summary: "Install local package"
      description: |-
        Request the agent for installation of a local package.
      requestBody:
        required: true
        description: "Path for the file to be installed"
        content:
          text/plain:
            schema:
              type: string
              example: "/tmp/update.uhupkg"
      responses:
        "200":
          description: "Request accepted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentStatus"
        "422":
          description: "Local instalation cond't start"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentStatus"

  "/remote_install":
    post:
      summary: "Download and install package from remote url"
      description: |-
        Request the agent for installation of a remote package.
      requestBody:
        required: true
        description: "Remote url that offers the update pacakge"
        content:
          text/plain:
            schema:
              type: string
              example: "https://some_remote_url.domain/update.uhupkg"
      responses:
        "200":
          description: "Request accepted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentStatus"
        "422":
          description: "Remote instalation cond't start"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentStatus"

  "/update/download/abort":
    post:
      summary: "Abort download"
      description: |-
        Abort an update objects download (triggered by any command). On success, returns
        HTTP 200 and a empty json object as body. On failure, returns HTTP 400 and the
        error message inside a json object as body.
      responses:
        "200":
          description: "Download Aborted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AbortDownloadAccepted"
        "400":
          description: "No download to be aborted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AbortDownloadRejected"

  "/log":
    post:
      summary: "Fetch agent log"
      description: |-
        Returns the agent log.
      responses:
        "200":
          description: "Download Aborted"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/LogEntry"

components:
  schemas:
    AgentInfo:
      description: "Information about the agent"
      required:
        - version
        - config
        - firmware
      properties:
        version:
          type: string
          example: "0.1.0-87-ga836b13"
        config:
          $ref: "#/components/schemas/AgentInfoConfig"
        firmware:
          $ref: "#/components/schemas/AgentInfoFirmware"

    ProbeInfo:
      description: "Response about requested probe"
      type: object
      required:
        - update_available
        - try_again_in
      properties:
        update_available:
          type: boolean
        try_again_in:
          type: integer
          example: 3600

    ProbeCustomServer:
      description: "Server address which the update procedure will use for this request"
      type: object
      properties:
        custom_server:
          type: string
          example: "http://different-address:8080"

    AgentStatus:
      description: "Agent state information"
      type: object
      required:
        - busy
        - current_state
      properties:
        busy:
          type: boolean
          example: false
        current_state:
          $ref: "#/components/schemas/AgentState"

    AbortDownloadAccepted:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          example: "request accepted, download aborted"

    AbortDownloadRejected:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: "there is no download to be aborted"

    LogEntry:
      type: object
      required:
        - level
        - message
        - time
        - data
      properties:
        level:
          $ref: "#/components/schemas/LogLevel"
        message:
          type: string
          example: "info 1"
        time:
          type: string
          example: "2017-06-29 14:59:41.831111065 -0300 -03"
        data:
          type: object
          additionalProperties:
            type: string
          example:
            field1: "value1"
            field2: "value2"

    LogLevel:
      type: string
      enum: ["error", "info", "warning", "debug", "trace"]

    SupportedInstallMode:
      description: "Available install modes"
      type: string
      enum: ["copy", "raw"]

    AgentState:
      description: "Agent state"
      type: string
      enum: ["idle", "install", "park", "poll", "probe", "reboot"]

    AgentInfoConfig:
      type: object
      required:
        - polling
        - storage
        - update
        - network
        - firwamre
      properties:
        polling:
          $ref: "#/components/schemas/AgentInfoConfigPolling"
        storage:
          $ref: "#/components/schemas/AgentInfoConfigStorage"
        update:
          $ref: "#/components/schemas/AgentInfoConfigUpdate"
        network:
          $ref: "#/components/schemas/AgentInfoConfigNetwork"
        firwamre:
          $ref: "#/components/schemas/AgentInfoConfigFirwamre"

    AgentInfoConfigFirwamre:
      type: object
      required:
        - metadata_path
      properties:
        metadata_path:
          type: string
          example: "/usr/share/updatehub"

    AgentInfoConfigNetwork:
      type: object
      required:
        - server_address
      properties:
        server_address:
          type: string
          example: "api.updatehub.io"

    AgentInfoConfigUpdate:
      type: object
      required:
        - download_dir
        - auto_download_when_available
        - auto_install_after_download
        - auto_reboot_after_install
        - supported_install_modes
      properties:
        download_dir:
          type: string
          example: "/tmp/download"
        auto_download_when_available:
          type: boolean
        auto_install_after_download:
          type: boolean
        auto_reboot_after_install:
          type: boolean
        supported_install_modes:
          type: array
          items:
            $ref: "#/components/schemas/SupportedInstallMode"

    AgentInfoConfigStorage:
      type: object
      required:
        - read_only
      properties:
        read_only:
          type: boolean

    AgentInfoConfigPolling:
      type: object
      required:
        - enabled
        - interval
        - last_poll
        - first_poll
        - extra_interval
        - retries
      properties:
        enabled:
          type: boolean
        interval:
          type: integer
          example: 3600
        last_poll:
          type: string
          example: "2017-01-01T00:00:00Z"
        first_poll:
          type: string
          example: "2017-02-02T00:00:00Z"
        extra_interval:
          type: integer
          example: 300
        retries:
          type: integer

    AgentInfoFirmware:
      type: object
      required:
        - product_uid
        - device_identity
        - device_attributes
        - hardware
        - version
      properties:
        product_uid:
          type: string
          example: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        device_identity:
          type: object
          additionalProperties:
            type: string
          example:
            "id1": "value1"
            "id2": "value2"
        device_attributes:
          type: object
          additionalProperties:
            type: string
          example:
            "attr1": "value1"
            "attr2": "value2"
        hardware:
          type: string
          example: "board-name-revA"
        version:
          type: string
          example: "1.2"
<commit_msg>doc: Fix spec for log request<commit_after>openapi: 3.0.0
info:
  title: UpdateHub Agent local HTTP API routes
  description: |-
    These are the routes available through HTTP on the device running the
    UpdateHub Agent.
  version: "2.0"
servers:
  - url: "http://localhost:8080"
    variables: {}

paths:
  "/info":
    get:
      summary: "Get general information."
      responses:
        "200":
          description: "Request accepted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentInfo"

  "/probe":
    post:
      summary: "Actively probe the server."
      description: |-
        Probe the server and download the update metadata if  available.
        Returns a json object containing the "update_available" boolean field.
        It also may contain a "try_again_in" field which means the caller should
        try the request again 'n' seconds from now, where 'n' is the value of
        "try_again_in".

        This request accepts a "server_address" parameter on POST. When it's present,
        it will use the address for the triggered probe (and the update procedure too
        in case there is an update available).

        If agent is busy (e.g. downloading a object or installing an object) the
        returned http code is 202.
      requestBody:
        required: false
        description: "The custom server to probe"
        content:
          application/json:
              schema:
                $ref: "#/components/schemas/ProbeCustomServer"
      responses:
        "200":
          description: "Request accepted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProbeInfo"
        "202":
          description: "Agent is busy"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentStatus"

  "/local_install":
    post:
      summary: "Install local package"
      description: |-
        Request the agent for installation of a local package.
      requestBody:
        required: true
        description: "Path for the file to be installed"
        content:
          text/plain:
            schema:
              type: string
              example: "/tmp/update.uhupkg"
      responses:
        "200":
          description: "Request accepted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentStatus"
        "422":
          description: "Local instalation cond't start"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentStatus"

  "/remote_install":
    post:
      summary: "Download and install package from remote url"
      description: |-
        Request the agent for installation of a remote package.
      requestBody:
        required: true
        description: "Remote url that offers the update pacakge"
        content:
          text/plain:
            schema:
              type: string
              example: "https://some_remote_url.domain/update.uhupkg"
      responses:
        "200":
          description: "Request accepted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentStatus"
        "422":
          description: "Remote instalation cond't start"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentStatus"

  "/update/download/abort":
    post:
      summary: "Abort download"
      description: |-
        Abort an update objects download (triggered by any command). On success, returns
        HTTP 200 and a empty json object as body. On failure, returns HTTP 400 and the
        error message inside a json object as body.
      responses:
        "200":
          description: "Download Aborted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AbortDownloadAccepted"
        "400":
          description: "No download to be aborted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AbortDownloadRejected"

  "/log":
    get:
      summary: "Fetch agent log"
      description: |-
        Returns the agent log.
      responses:
        "200":
          description: "Log of last execution"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/LogEntry"

components:
  schemas:
    AgentInfo:
      description: "Information about the agent"
      required:
        - version
        - config
        - firmware
      properties:
        version:
          type: string
          example: "0.1.0-87-ga836b13"
        config:
          $ref: "#/components/schemas/AgentInfoConfig"
        firmware:
          $ref: "#/components/schemas/AgentInfoFirmware"

    ProbeInfo:
      description: "Response about requested probe"
      type: object
      required:
        - update_available
        - try_again_in
      properties:
        update_available:
          type: boolean
        try_again_in:
          type: integer
          example: 3600

    ProbeCustomServer:
      description: "Server address which the update procedure will use for this request"
      type: object
      properties:
        custom_server:
          type: string
          example: "http://different-address:8080"

    AgentStatus:
      description: "Agent state information"
      type: object
      required:
        - busy
        - current_state
      properties:
        busy:
          type: boolean
          example: false
        current_state:
          $ref: "#/components/schemas/AgentState"

    AbortDownloadAccepted:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          example: "request accepted, download aborted"

    AbortDownloadRejected:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: "there is no download to be aborted"

    LogEntry:
      type: object
      required:
        - level
        - message
        - time
        - data
      properties:
        level:
          $ref: "#/components/schemas/LogLevel"
        message:
          type: string
          example: "info 1"
        time:
          type: string
          example: "2017-06-29 14:59:41.831111065 -0300 -03"
        data:
          type: object
          additionalProperties:
            type: string
          example:
            field1: "value1"
            field2: "value2"

    LogLevel:
      type: string
      enum: ["error", "info", "warning", "debug", "trace"]

    SupportedInstallMode:
      description: "Available install modes"
      type: string
      enum: ["copy", "raw"]

    AgentState:
      description: "Agent state"
      type: string
      enum: ["idle", "install", "park", "poll", "probe", "reboot"]

    AgentInfoConfig:
      type: object
      required:
        - polling
        - storage
        - update
        - network
        - firwamre
      properties:
        polling:
          $ref: "#/components/schemas/AgentInfoConfigPolling"
        storage:
          $ref: "#/components/schemas/AgentInfoConfigStorage"
        update:
          $ref: "#/components/schemas/AgentInfoConfigUpdate"
        network:
          $ref: "#/components/schemas/AgentInfoConfigNetwork"
        firwamre:
          $ref: "#/components/schemas/AgentInfoConfigFirwamre"

    AgentInfoConfigFirwamre:
      type: object
      required:
        - metadata_path
      properties:
        metadata_path:
          type: string
          example: "/usr/share/updatehub"

    AgentInfoConfigNetwork:
      type: object
      required:
        - server_address
      properties:
        server_address:
          type: string
          example: "api.updatehub.io"

    AgentInfoConfigUpdate:
      type: object
      required:
        - download_dir
        - auto_download_when_available
        - auto_install_after_download
        - auto_reboot_after_install
        - supported_install_modes
      properties:
        download_dir:
          type: string
          example: "/tmp/download"
        auto_download_when_available:
          type: boolean
        auto_install_after_download:
          type: boolean
        auto_reboot_after_install:
          type: boolean
        supported_install_modes:
          type: array
          items:
            $ref: "#/components/schemas/SupportedInstallMode"

    AgentInfoConfigStorage:
      type: object
      required:
        - read_only
      properties:
        read_only:
          type: boolean

    AgentInfoConfigPolling:
      type: object
      required:
        - enabled
        - interval
        - last_poll
        - first_poll
        - extra_interval
        - retries
      properties:
        enabled:
          type: boolean
        interval:
          type: integer
          example: 3600
        last_poll:
          type: string
          example: "2017-01-01T00:00:00Z"
        first_poll:
          type: string
          example: "2017-02-02T00:00:00Z"
        extra_interval:
          type: integer
          example: 300
        retries:
          type: integer

    AgentInfoFirmware:
      type: object
      required:
        - product_uid
        - device_identity
        - device_attributes
        - hardware
        - version
      properties:
        product_uid:
          type: string
          example: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        device_identity:
          type: object
          additionalProperties:
            type: string
          example:
            "id1": "value1"
            "id2": "value2"
        device_attributes:
          type: object
          additionalProperties:
            type: string
          example:
            "attr1": "value1"
            "attr2": "value2"
        hardware:
          type: string
          example: "board-name-revA"
        version:
          type: string
          example: "1.2"

{'fraction_non_alphanumeric': 0.07772498060512024, 'fraction_numerical': 0.018231186966640806, 'mean_word_length': 1.5891287973889028, 'pattern_counts': {'":': 40, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 43, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2714254', 'n_tokens_mistral': 5586, 'n_tokens_neox': 5255, 'n_words': 1491}