openapi.yaml

openapi: 3.0.3

info:
  title: Ably Asset Tracking Fault Simulation Proxy
  description: |-
    A REST API for creating and managing proxies which are able to simulate connectivity faults that might occur during use of the Ably Asset Tracking SDKs.
  version: 0.1.0

servers:
  - description: Local server
    url: http://localhost:8080

paths:
  /faults:
    get:
      summary: List all faults
      description: Lists all of the faults that the proxy is capable of simulating.
      operationId: listFaults
      responses:
        '200':
          description: Successful operation. Returns a list of all fault names.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              example:
                - NullTransportFault
                - NullApplicationLayerFault
                - TcpConnectionRefused
                - TcpConnectionUnresponsive
                - AttachUnresponsive
                - DetachUnresponsive
                - DisconnectWithFailedResume
                - EnterFailedWithNonfatalNack
                - UpdateFailedWithNonfatalNack
                - DisconnectAndSuspend
                - ReenterOnResumeFailed
                - EnterUnresponsive

  /faults/{name}/simulation:
    post:
      summary: Create a fault simulation and start its proxy
      description: |-
        A fault simulation implements a specific type of connectivity fault that might occur during the use of the Asset Tracking SDK. In order to simulate a fault, it creates and manipulates a proxy that transparently sits between the client and the Ably Realtime service. The fault simulation returned by this endpoint provides details of how a client can connect to its proxy.

        Faults also specify what state Trackables should enter during a fault and after it has been resolved, so that assertions can be made while testing common use-cases.

        A fault simulation does not have any effect on the connection’s behaviour until it is _enabled_. To enable a fault simulation, use the `POST /fault-simulations/{id}/enable` endpoint.

        At the moment, all created proxies listen on the same port, so it is not possible to have multiple proxies active simultaneously – in order to create a new fault simulation you must first clean up the previous one using the `POST /fault-simulations/{id}/clean-up` endpoint. This is a limitation of the current implementation, which will be resolved in the future.
      operationId: createFaultSimulation
      parameters:
        - name: name
          in: path
          description: Name of fault to create a simulation for. This must be one of the fault names returned by the `GET /faults` endpoint.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation. Returns a representation of the created fault simulation and details of how to connect to its proxy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaultSimulationDto'

  /fault-simulations/{id}/enable:
    post:
      summary: Enable a fault simulation
      description: Breaks the proxy using the fault-specific failure conditions.
      operationId: enableFaultSimulation
      parameters:
        - name: id
          in: path
          description: ID of fault simulation to enable
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation.

  /fault-simulations/{id}/resolve:
    post:
      summary: Resolve a fault simulation
      description: Restores the proxy to normal functionality.
      operationId: resolveFaultSimulation
      parameters:
        - name: id
          in: path
          description: ID of fault simulation to resolve
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation.

  /fault-simulations/{id}/clean-up:
    post:
      summary: Clean up a fault simulation
      description: Stops the proxy. This should be called at the end of each test case that creates a fault simulation.
      operationId: cleanUpFaultSimulation
      parameters:
        - name: id
          in: path
          description: ID of fault simulation to clean up
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation.

components:
  schemas:
    FaultSimulationDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          example: TcpConnectionRefused
        type:
          $ref: '#/components/schemas/FaultTypeDto'
          description: Describes the expected impact of the fault simulation.
        proxy:
          $ref: '#/components/schemas/ProxyDto'
          description: The details of how to connect to the proxy created for this fault simulation.

    FaultTypeDto:
      description: Describes the nature of a given fault simulation, and specifically the impact that it should have on any Trackables or channel activity during and after resolution.
      example:
        type: nonfatal
        resolvedWithinMillis: 180_000
      properties:
        type:
          type: string
          enum:
            - nonfatal
            - nonfatalWhenResolved
            - fatal
      oneOf:
        - $ref: '#/components/schemas/NonfatalFaultTypeDto'
        - $ref: '#/components/schemas/NonfatalWhenResolvedFaultTypeDto'
        - $ref: '#/components/schemas/FatalFaultTypeDto'
      discriminator:
        propertyName: 'type'
        mapping:
          nonfatal: '#/components/schemas/NonfatalFaultTypeDto'
          nonfatalWhenResolved: '#/components/schemas/NonFatalWhenResolvedFaultTypeDto'
          fatal: '#/components/schemas/FatalFaultTypeDto'

    NonfatalFaultTypeDto:
      description: AAT and/or the Ably client library should handle this fault seamlessly. Trackable state should be online and publisher should be present within resolvedWithinMillis milliseconds. It's possible the fault will cause a brief Offline blip, but tests should expect to see Trackables Online again before resolvedWithinMillis expires regardless.
      type: object
      properties:
        resolvedWithinMillis:
          type: integer

    NonfatalWhenResolvedFaultTypeDto:
      description: This is a non-fatal error, but will persist until the POST /fault-simulations/{id}/resolve endpoint has been called. Trackable states should be offline during the fault within offlineWithinMillis milliseconds maximum. When the fault is resolved, Trackables should return online within onlineWithinMillis milliseconds maximum.
      type: object
      properties:
        offlineWithinMillis:
          type: integer
        onlineWithinMillis:
          type: integer

    FatalFaultTypeDto:
      description: This is a fatal error and should permanently move Trackables to the Failed state. The publisher should not be present in the corresponding channel any more and no further location updates will be published. Tests should check that Trackables reach the Failed state within failedWithinMillis milliseconds.
      type: object
      properties:
        failedWithinMillis:
          type: integer

    ProxyDto:
      description: Describes how a Realtime client instance can connect to a proxy created by a fault simulation.
      type: object
      example:
        listenPort: 13579
      properties:
        listenPort:
          type: integer
          description: The port that the proxy is listening on. In order to experience the fault whose simulation this proxy belongs to, an Ably realtime client should be configured to connect to this port on the same host as the web server hosting this API.