openapi: 3.0.0
info:
  title: envd
  version: 0.1.3
  description: API for managing files' content and controlling envd

tags:
  - name: files

paths:
  /health:
    get:
      summary: Check the health of the service
      responses:
        '204':
          description: The service is healthy

  /metrics:
    get:
      summary: Get the stats of the service
      security:
        - AccessTokenAuth: []
        - {}
      responses:
        '200':
          description: The resource usage metrics of the service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metrics'

  /init:
    post:
      summary: Set initial vars, ensure the time and metadata is synced with the host
      security:
        - AccessTokenAuth: []
        - {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                hyperloopIP:
                  type: string
                  description: IP address of the hyperloop server to connect to
                envVars:
                  $ref: '#/components/schemas/EnvVars'
                accessToken:
                  type: string
                  description: Access token for secure access to envd service
                timestamp:
                  type: string
                  format: date-time
                  description: The current timestamp in RFC3339 format
                defaultUser:
                  type: string
                  description: The default user to use for operations
                defaultWorkdir:
                  type: string
                  description: The default working directory to use for operations
      responses:
        '204':
          description: Env vars set, the time and metadata is synced with the host

  /envs:
    get:
      summary: Get the environment variables
      security:
        - AccessTokenAuth: []
        - {}
      responses:
        '200':
          description: Environment variables
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvVars'

  /files:
    get:
      summary: Download a file
      tags: [files]
      security:
        - AccessTokenAuth: []
        - {}
      parameters:
        - $ref: '#/components/parameters/FilePath'
        - $ref: '#/components/parameters/User'
        - $ref: '#/components/parameters/Signature'
        - $ref: '#/components/parameters/SignatureExpiration'
      responses:
        '200':
          $ref: '#/components/responses/DownloadSuccess'
        '401':
          $ref: '#/components/responses/InvalidUser'
        '400':
          $ref: '#/components/responses/InvalidPath'
        '404':
          $ref: '#/components/responses/FileNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Upload a file and ensure the parent directories exist. If the file exists, it will be overwritten.
      description: |
        Any request header of the form `X-Metadata-<key>: <value>` is persisted
        as a user-defined extended attribute on the uploaded file. The
        `X-Metadata-` prefix is stripped and the remaining header name is
        lowercased to form the metadata key; the resulting map is returned on
        `EntryInfo` lookups (e.g. `Stat`, `ListDir`).

        Each upload replaces the file's metadata with the keys provided in
        that request: keys previously stored but absent from the new request
        are removed, and an upload that sends no `X-Metadata-*` header clears
        all existing metadata.

        Both keys and values must be printable US-ASCII (bytes `0x20`-`0x7E`)
        and are rejected with HTTP 400 otherwise. Each key is capped at 246
        bytes (the Linux VFS xattr-name limit minus the namespace prefix), and
        the combined size of all metadata on a file (keys plus values, with the
        namespace prefix counted per key) is capped at 4096 bytes to stay within
        the filesystem's per-inode xattr budget. Multiple files in a single
        multipart upload receive the same metadata. If the same
        `X-Metadata-<key>` header is sent more than once, only the first
        value is used.
      tags: [files]
      security:
        - AccessTokenAuth: []
        - {}
      parameters:
        - $ref: '#/components/parameters/FilePath'
        - $ref: '#/components/parameters/User'
        - $ref: '#/components/parameters/Signature'
        - $ref: '#/components/parameters/SignatureExpiration'
      requestBody:
        $ref: '#/components/requestBodies/File'
      responses:
        '200':
          $ref: '#/components/responses/UploadSuccess'
        '400':
          $ref: '#/components/responses/InvalidPath'
        '401':
          $ref: '#/components/responses/InvalidUser'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '507':
          $ref: '#/components/responses/NotEnoughDiskSpace'

components:
  securitySchemes:
    AccessTokenAuth:
      type: apiKey
      scheme: header
      name: X-Access-Token

  parameters:
    FilePath:
      name: path
      in: query
      required: false
      description: Path to the file, URL encoded. Can be relative to user's home directory.
      schema:
        type: string
    User:
      name: username
      in: query
      required: false
      description: User used for setting the owner, or resolving relative paths.
      schema:
        type: string
    Signature:
      name: signature
      in: query
      required: false
      description: Signature used for file access permission verification.
      schema:
        type: string
    SignatureExpiration:
      name: signature_expiration
      in: query
      required: false
      description: Signature expiration used for defining the expiration time of the signature.
      schema:
        type: integer

  requestBodies:
    File:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              file:
                type: string
                format: binary

  responses:
    UploadSuccess:
      description: The file was uploaded successfully.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/EntryInfo'

    DownloadSuccess:
      description: Entire file downloaded successfully.
      content:
        application/octet-stream:
          schema:
            type: string
            format: binary
            description: The file content
    InvalidPath:
      description: Invalid path
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    FileNotFound:
      description: File not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidUser:
      description: Invalid user
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotEnoughDiskSpace:
      description: Not enough disk space
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    Error:
      required:
        - message
        - code
      properties:
        message:
          type: string
          description: Error message
        code:
          type: integer
          description: Error code
    EntryInfo:
      required:
        - path
        - name
        - type
      properties:
        path:
          type: string
          description: Path to the file
        name:
          type: string
          description: Name of the file
        type:
          type: string
          description: Type of the file
          enum:
            - file
        metadata:
          type: object
          description: User-defined metadata stored as extended attributes on the file.
          additionalProperties:
            type: string
    EnvVars:
      type: object
      description: Environment variables to set
      additionalProperties:
        type: string
    Metrics:
      type: object
      description: Resource usage metrics
      properties:
        ts:
          type: integer
          format: int64
          description: Unix timestamp in UTC for current sandbox time
        cpu_count:
          type: integer
          description: Number of CPU cores
        cpu_used_pct:
          type: number
          format: float
          description: CPU usage percentage
        mem_total:
          type: integer
          description: Total virtual memory in bytes
        mem_used:
          type: integer
          description: Used virtual memory in bytes
        disk_used:
          type: integer
          description: Used disk space in bytes
        disk_total:
          type: integer
          description: Total disk space in bytes