openapi: "3.0.2"
info:
  title: Compute node control API
  version: "1.0"

servers:
  - url: "http://localhost:3080"

paths:
  /status:
    get:
      tags:
      - Info
      summary: Get compute node internal status.
      description: ""
      operationId: getComputeStatus
      responses:
        200:
          description: ComputeState
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputeState"

  /metrics.json:
    get:
      tags:
      - Info
      summary: Get compute node startup metrics in JSON format.
      description: ""
      operationId: getComputeMetricsJSON
      responses:
        200:
          description: ComputeMetrics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputeMetrics"

  /insights:
    get:
      tags:
      - Info
      summary: Get current compute insights in JSON format.
      description: |
        Note, that this doesn't include any historical data.
      operationId: getComputeInsights
      responses:
        200:
          description: Compute insights
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputeInsights"

  /installed_extensions:
    get:
      tags:
      - Info
      summary: Get installed extensions.
      description: ""
      operationId: getInstalledExtensions
      responses:
        200:
          description: List of installed extensions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InstalledExtensions"
  /info:
    get:
      tags:
      - Info
      summary: Get info about the compute pod / VM.
      description: ""
      operationId: getInfo
      responses:
        200:
          description: Info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Info"

  /dbs_and_roles:
    get:
      tags:
        - Info
      summary: Get databases and roles in the catalog.
      description: ""
      operationId: getDbsAndRoles
      responses:
        200:
          description: Compute schema objects
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DbsAndRoles"

  /database_schema:
    get:
      tags:
        - Info
      summary: Get schema dump
      parameters:
        - name: database
          in: query
          description: Database name to dump.
          required: true
          schema:
            type: string
          example: "postgres"
      description: Get schema dump in SQL format.
      operationId: getDatabaseSchema
      responses:
        200:
          description: Schema dump
          content:
            text/plain:
              schema:
                type: string
                description: Schema dump in SQL format.
        404:
          description: Non existing database.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericError"

  /grants:
    post:
      tags:
        - Grants
      summary: Apply grants to the database.
      description: ""
      operationId: setRoleGrants
      requestBody:
        description: Grants request.
        required: true
        content:
          application/json:
            schema:
                $ref: "#/components/schemas/SetRoleGrantsRequest"
      responses:
        200:
          description: Grants applied.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SetRoleGrantsResponse"
        412:
          description: |
            Compute is not in the right state for processing the request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericError"
        500:
          description: Error occurred during grants application.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericError"

  /check_writability:
    post:
      tags:
      - Check
      summary: Check that we can write new data on this compute.
      description: ""
      operationId: checkComputeWritability
      responses:
        200:
          description: Check result
          content:
            text/plain:
              schema:
                type: string
                description: Error text or 'true' if check passed.
                example: "true"

  /extensions:
    post:
      tags:
        - Extensions
      summary: Install extension if possible.
      description: ""
      operationId: installExtension
      requestBody:
        description: Extension name and database to install it to.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExtensionInstallRequest"
      responses:
        200:
          description: Result from extension installation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExtensionInstallResult"
        412:
          description: |
            Compute is in the wrong state for processing the request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericError"
        500:
          description: Error during extension installation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericError"

  /configure:
    post:
      tags:
      - Configure
      summary: Perform compute node configuration.
      description: |
        This is a blocking API endpoint, i.e. it blocks waiting until
        compute is finished configuration and is in `Running` state.
        Optional non-blocking mode could be added later.
      operationId: configureCompute
      requestBody:
        description: Configuration request.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - spec
              properties:
                spec:
                  # XXX: I don't want to explain current spec in the OpenAPI format,
                  # as it could be changed really soon. Consider doing it later.
                  type: object
      responses:
        200:
          description: Compute configuration finished.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputeState"
        400:
          description: Provided spec is invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericError"
        412:
          description: |
            It's not possible to do live-configuration of the compute.
            It's either in the wrong state, or compute doesn't use pull
            mode of configuration.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericError"
        500:
          description: |
            Compute configuration request was processed, but error
            occurred. Compute will likely shutdown soon.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericError"
  /extension_server:
    post:
      tags:
      - Extension
      summary: Download extension from S3 to local folder.
      description: ""
      operationId: downloadExtension
      responses:
        200:
          description: Extension downloaded
          content:
            text/plain:
              schema:
                type: string
                description: Error text or 'OK' if download succeeded.
                example: "OK"
        400:
          description: Request is invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericError"
        500:
          description: Extension download request failed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericError"

  /terminate:
    post:
      tags:
      - Terminate
      summary: Terminate Postgres and wait for it to exit
      description: ""
      operationId: terminate
      responses:
        200:
          description: Result
        412:
          description: "wrong state"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericError"
        500:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericError"

components:
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    ComputeMetrics:
      type: object
      description: Compute startup metrics.
      required:
        - wait_for_spec_ms
        - sync_safekeepers_ms
        - basebackup_ms
        - config_ms
        - total_startup_ms
      properties:
        wait_for_spec_ms:
          type: integer
        sync_safekeepers_ms:
          type: integer
        basebackup_ms:
          type: integer
        config_ms:
          type: integer
        total_startup_ms:
          type: integer

    Info:
      type: object
      description: Information about VM/Pod.
      required:
        - num_cpus
      properties:
        num_cpus:
          type: integer

    DbsAndRoles:
      type: object
      description: Databases and Roles
      required:
        - roles
        - databases
      properties:
        roles:
          type: array
          items:
            $ref: "#/components/schemas/Role"
        databases:
          type: array
          items:
            $ref: "#/components/schemas/Database"

    Database:
      type: object
      description: Database
      required:
        - name
        - owner
        - restrict_conn
        - invalid
      properties:
        name:
          type: string
        owner:
          type: string
        options:
          type: array
          items:
            $ref: "#/components/schemas/GenericOption"
        restrict_conn:
          type: boolean
        invalid:
          type: boolean

    Role:
      type: object
      description: Role
      required:
        - name
      properties:
        name:
          type: string
        encrypted_password:
          type: string
        options:
          type: array
          items:
            $ref: "#/components/schemas/GenericOption"

    GenericOption:
      type: object
      description: Schema Generic option
      required:
        - name
        - vartype
      properties:
        name:
          type: string
        value:
          type: string
        vartype:
          type: string

    ComputeState:
      type: object
      required:
        - start_time
        - status
      properties:
        start_time:
          type: string
          description: |
            Time when compute was started. If initially compute was started in the `empty`
            state and then provided with valid spec, `start_time` will be reset to the
            moment, when spec was received.
          example: "2022-10-12T07:20:50.52Z"
        status:
          $ref: "#/components/schemas/ComputeStatus"
        last_active:
          type: string
          description: |
            The last detected compute activity timestamp in UTC and RFC3339 format.
            It could be empty if compute was never used by user since start.
          example: "2022-10-12T07:20:50.52Z"
        error:
          type: string
          description: Text of the error during compute startup or reconfiguration, if any.
          example: ""
        tenant:
          type: string
          description: Identifier of the current tenant served by compute node, if any.
          example: c9269c359e9a199fad1ea0981246a78f
        timeline:
          type: string
          description: Identifier of the current timeline served by compute node, if any.
          example: ece7de74d4b8cbe5433a68ce4d1b97b4

    ComputeInsights:
      type: object
      properties:
        pg_stat_statements:
          description: Contains raw output from pg_stat_statements in JSON format.
          type: array
          items:
            type: object

    ComputeStatus:
      type: string
      enum:
        - empty
        - init
        - failed
        - running
        - configuration_pending
        - configuration
      example: running

    ExtensionInstallRequest:
      type: object
      required:
        - extension
        - database
        - version
      properties:
        extension:
          type: string
          description: Extension name.
          example: "pg_session_jwt"
        version:
          type: string
          description: Version of the extension.
          example: "1.0.0"
        database:
          type: string
          description: Database name.
          example: "neondb"

    ExtensionInstallResult:
      type: object
      properties:
        extension:
          description: Name of the extension.
          type: string
          example: "pg_session_jwt"
        version:
          description: Version of the extension.
          type: string
          example: "1.0.0"

    InstalledExtensions:
      type: object
      properties:
        extensions:
          description: Contains list of installed extensions.
          type: array
          items:
            type: object
            properties:
              extname:
                type: string
              versions:
                type: array
                items:
                  type: string
              n_databases:
                type: integer

    SetRoleGrantsRequest:
      type: object
      required:
        - database
        - schema
        - privileges
        - role
      properties:
        database:
          type: string
          description: Database name.
          example: "neondb"
        schema:
          type: string
          description: Schema name.
          example: "public"
        privileges:
          type: array
          items:
            type: string
          description: List of privileges to set.
          example: ["SELECT", "INSERT"]
        role:
          type: string
          description: Role name.
          example: "neon"

    SetRoleGrantsResponse:
      type: object
      required:
        - database
        - schema
        - privileges
        - role
      properties:
        database:
          type: string
          description: Database name.
          example: "neondb"
        schema:
          type: string
          description: Schema name.
          example: "public"
        privileges:
          type: array
          items:
            type: string
          description: List of privileges set.
          example: ["SELECT", "INSERT"]
        role:
          type: string
          description: Role name.
          example: "neon"

    #
    # Errors
    #

    GenericError:
      type: object
      required:
        - error
      properties:
        error:
          type: string

security:
  - JWT: []