ws-openapi.yaml

openapi: 3.0.3
info:
  title: Aeron Cache WebSocket API
  description: WebSocket API for subscribing to Aeron Cache updates.
  termsOfService: https://www.github.com/bhf
  contact:
    name: Sanjeev
    url: https://www.sanjeev.pages.dev
    email: na@na.com
  version: 1.2.0
servers:
  - url: ws://localhost:7071
    description: Local WebSocket server
  - url: http://localhost:7071
    description: Local HTTP server (near cache management endpoints, when NEAR_CACHE_ENABLED=true)
paths:
  /api/ws/v1/cache/{cacheId}:
    get:
      summary: Subscribe to a single cache
      description: |
        Establish a WebSocket connection to subscribe to updates for a single cache.
      parameters:
        - name: cacheId
          in: path
          required: true
          description: The ID of the cache to subscribe to.
          schema:
            type: string
        - $ref: '#/components/parameters/KeysQueryParam'
        - $ref: '#/components/parameters/ModeQueryParam'
      responses:
        101:
          description: Switching Protocols - WebSocket connection established.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CacheUpdateEvent'
        400:
          description: Bad Request - Invalid cache ID.
        503:
          description: Service Unavailable - Cluster not connected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestErrorResponse'

  /api/ws/v1/caches/{cacheIds}:
    get:
      summary: Subscribe to multiple caches
      description: |
        Establish a WebSocket connection to subscribe to updates for multiple caches.
      parameters:
        - name: cacheIds
          in: path
          required: true
          description: Comma-separated list of cache IDs to subscribe to.
          schema:
            type: string
        - $ref: '#/components/parameters/KeysQueryParam'
        - $ref: '#/components/parameters/ModeQueryParam'
      responses:
        101:
          description: Switching Protocols - WebSocket connection established.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CacheUpdateEvent'
        400:
          description: Bad Request - Invalid cache IDs.
        503:
          description: Service Unavailable - Cluster not connected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestErrorResponse'

  /api/ws/v1/cache/hydrate/{cacheId}:
    get:
      summary: Subscribe to a single cache with hydration
      description: |
        Establish a WebSocket connection to subscribe to updates for a single cache, with initial state hydration.
      parameters:
        - name: cacheId
          in: path
          required: true
          description: The ID of the cache to subscribe to.
          schema:
            type: string
        - $ref: '#/components/parameters/KeysQueryParam'
        - $ref: '#/components/parameters/ModeQueryParam'
      responses:
        101:
          description: Switching Protocols - WebSocket connection established.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CacheUpdateEvent'
        400:
          description: Bad Request - Invalid cache ID.
        503:
          description: Service Unavailable - Cluster not connected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestErrorResponse'

  /api/ws/v1/caches/hydrate/{cacheIds}:
    get:
      summary: Subscribe to multiple caches with hydration
      description: |
        Establish a WebSocket connection to subscribe to updates for multiple caches, with initial state hydration.
      parameters:
        - name: cacheIds
          in: path
          required: true
          description: Comma-separated list of cache IDs to subscribe to.
          schema:
            type: string
        - $ref: '#/components/parameters/KeysQueryParam'
        - $ref: '#/components/parameters/ModeQueryParam'
      responses:
        101:
          description: Switching Protocols - WebSocket connection established.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CacheUpdateEvent'
        400:
          description: Bad Request - Invalid cache IDs.
        503:
          description: Service Unavailable - Cluster not connected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestErrorResponse'

  /api/v1/near/caches:
    get:
      summary: List warm near caches
      description: |
        HTTP endpoint. List the caches currently kept warm in the local near cache, with their local item
        counts. Available only when the WebSocket interface is started with `NEAR_CACHE_ENABLED=true`.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CacheDetails'
  /api/v1/near/cache/{cacheId}:
    post:
      summary: Prime a near cache up front
      description: |
        HTTP endpoint. Prime the specified cache: start the internal cluster subscription (requesting a
        snapshot) so the local copy is warmed up front, before any hydrating streaming subscription
        arrives (which then rides the warm copy instead of triggering a cold per-subscriber snapshot). The
        snapshot populates the local copy asynchronously, so a SUCCESS response means priming was started,
        not that it is fully populated yet. Idempotent - priming a cache that is already warm succeeds with
        `wasAlreadyWarm=true` and does not re-subscribe. Available only when the WebSocket interface is
        started with `NEAR_CACHE_ENABLED=true`.
      parameters:
        - name: cacheId
          in: path
          required: true
          description: The ID of the cache to prime.
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrimeNearCacheResponse'
    delete:
      summary: Stop near caching a cache
      description: |
        HTTP endpoint. Stop near caching the specified cache: drop the internal cluster subscription that
        keeps the local copy warm and remove the local copy. Active streaming subscriptions are not
        affected. Idempotent - stopping a cache that is not currently warm succeeds with `wasCached=false`.
        Available only when the WebSocket interface is started with `NEAR_CACHE_ENABLED=true`.
      parameters:
        - name: cacheId
          in: path
          required: true
          description: The ID of the cache to stop near caching.
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StopNearCacheResponse'
  /api/v1/near/counters-caches:
    get:
      summary: List warm near counter caches
      description: |
        HTTP endpoint. List the counter caches currently kept warm in the local near cache, with their
        local item counts. Available only when the WebSocket interface is started with
        `NEAR_CACHE_ENABLED=true`.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CacheDetails'
  /api/v1/near/counters/{cacheId}:
    post:
      summary: Prime a near counter cache up front
      description: |
        HTTP endpoint. Prime the specified counter cache: start the internal cluster subscription
        (requesting a snapshot) so the local copy is warmed up front, before any hydrating streaming
        subscription arrives. The snapshot populates the local copy asynchronously, so a SUCCESS response
        means priming was started, not that it is fully populated yet. Idempotent - priming a counter cache
        that is already warm succeeds with `wasAlreadyWarm=true` and does not re-subscribe. Available only
        when the WebSocket interface is started with `NEAR_CACHE_ENABLED=true`.
      parameters:
        - name: cacheId
          in: path
          required: true
          description: The ID of the counter cache to prime.
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrimeNearCacheResponse'
    delete:
      summary: Stop near caching a counter cache
      description: |
        HTTP endpoint. Stop near caching the specified counter cache: drop the internal cluster
        subscription that keeps the local copy warm and remove the local copy. Active streaming
        subscriptions are not affected. Idempotent - stopping a counter cache that is not currently warm
        succeeds with `wasCached=false`. Available only when the WebSocket interface is started with
        `NEAR_CACHE_ENABLED=true`.
      parameters:
        - name: cacheId
          in: path
          required: true
          description: The ID of the counter cache to stop near caching.
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StopNearCacheResponse'

components:
  parameters:
    KeysQueryParam:
      name: keys
      in: query
      required: false
      description: |
        Optional comma-separated list of key filters that restrict the subscription to specific keys. Each token is
        either `cacheId:key` (targets that key within that cache) or a bare `key` (applies to every cache in the
        route). When omitted, the subscription covers the whole cache.
      schema:
        type: string
    ModeQueryParam:
      name: mode
      in: query
      required: false
      description: |
        Subscription mode. `full` (default) streams complete item values as `ADD_ITEM` events; `patch` streams only
        the changed fields of patched items as `PATCH_ITEM` events. Patch mode is cache-only.
      schema:
        type: string
        enum:
          - full
          - patch
        default: full
  schemas:
    CacheUpdateEvent:
      type: object
      description: A cache update event published over the WebSocket connection.
      properties:
        cacheId:
          type: string
          description: The ID of the cache.
        eventType:
          type: string
          description: The type of event.
          enum:
            - ADD_ITEM
            - PATCH_ITEM
            - DELETE_CACHE
            - REMOVE_ITEM
            - CLEAR_CACHE
        itemKey:
          type: string
          nullable: true
          description: The key of the item.
        itemValue:
          type: string
          nullable: true
          description: The value of the item.
        requestId:
          type: string
          description: The request ID associated with the event.
      required:
        - cacheId
        - eventType
        - requestId
    RequestErrorResponse:
      type: object
      properties:
        errorMsg:
          type: string
        helpMsg:
          type: string
        operationStatus:
          $ref: '#/components/schemas/CacheOperationStatus'
    CacheDetails:
      type: object
      description: A near-cached cache and its local item count.
      properties:
        cacheId:
          type: string
        itemCount:
          type: integer
          format: int64
    StopNearCacheResponse:
      type: object
      description: The result of stopping near caching for a cache.
      properties:
        cacheId:
          type: string
        wasCached:
          type: boolean
          description: Whether a local near cache copy existed and was removed.
        operationStatus:
          $ref: '#/components/schemas/CacheOperationStatus'
    PrimeNearCacheResponse:
      type: object
      description: The result of priming a near cache for a cache.
      properties:
        cacheId:
          type: string
        wasAlreadyWarm:
          type: boolean
          description: Whether the cache was already warm, in which case priming was a no-op.
        operationStatus:
          $ref: '#/components/schemas/CacheOperationStatus'
    CacheOperationStatus:
      type: string
      enum:
        - NONE
        - SUCCESS
        - ERROR
        - UNKNOWN_CACHE
        - UNKNOWN_KEY
        - CACHE_EXISTS
        - DUPLICATE_SUBSCRIPTION
        - UNKNOWN_SUBSCRIPTION
        - NULL_VAL