openapi: 3.0.0
info:
  title: Discovery Service
  version: 1.0.0
  description: Lightning node backend discovery and management service
servers:
  - url: http://localhost:3001
security:
  - bearerAuth: []
paths:
  /discovery:
    post:
      summary: Register new backend
      description: Registers a new Lightning node backend with its connection details and load balancing configuration.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscoveryBackend'
      responses:
        '201':
          description: Backend created
          headers:
            Location:
              schema:
                type: string
        '409':
          description: Backend already exists

    get:
      summary: Get all backends
      description: Retrieves a list of all registered Lightning node backends.
      parameters:
        - name: If-None-Match
          in: header
          required: false
          description: ETag value from a previous response. If it matches the current ETag, returns 304 Not Modified.
          schema:
            type: string
      responses:
        '200':
          description: List of backends
          headers:
            Cache-Control:
              schema:
                type: string
            Expires:
              schema:
                type: string
            Pragma:
              schema:
                type: string
            ETag:
              schema:
                type: string
              description: Current version of the backend list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DiscoveryBackend'
        '304':
          description: Not Modified - backend list hasn't changed since the ETag provided in If-None-Match
          headers:
            Cache-Control:
              schema:
                type: string
            Expires:
              schema:
                type: string
            Pragma:
              schema:
                type: string
            ETag:
              schema:
                type: string
              description: Current version of the backend list (same as the If-None-Match value)
  /discovery/{public-key}:
    get:
      summary: Get specific backend
      description: Retrieves detailed information about a specific Lightning node backend identified by its public key.
      parameters:
        - name: public-key
          in: path
          required: true
          schema:
            type: string
          description: Secp256k1 public key in hex format
      responses:
        '200':
          description: Backend details
          headers:
            Cache-Control:
              schema:
                type: string
            Expires:
              schema:
                type: string
            Pragma:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveryBackend'
        '404':
          description: Backend not found
    put:
      summary: Create or update backend
      description: Creates a new backend or updates an existing one with the provided configuration at the specified public key.
      parameters:
        - name: public-key
          in: path
          required: true
          schema:
            type: string
          description: Secp256k1 public key in hex format
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscoveryBackendSparse'
      responses:
        '201':
          description: Backend created
        '204':
          description: Backend updated
    patch:
      summary: Partially update backend
      description: Updates specific fields of an existing Lightning node backend without requiring the full backend configuration.
      parameters:
        - name: public-key
          in: path
          required: true
          schema:
            type: string
          description: Secp256k1 public key in hex format
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscoveryBackendPatchSparse'
      responses:
        '204':
          description: Backend updated
        '404':
          description: Backend not found
    delete:
      summary: Remove backend
      description: Removes a Lightning node backend from the discovery service, preventing it from receiving new traffic.
      parameters:
        - name: public-key
          in: path
          required: true
          schema:
            type: string
          description: Secp256k1 public key in hex format
      responses:
        '204':
          description: Backend removed
        '404':
          description: Backend not found
  /health:
    get:
      summary: Health check
      description: Returns HTTP 200 OK to indicate the discovery service is running and accessible.
      security: []
      responses:
        '200':
          description: Service healthy
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    DiscoveryBackend:
      type: object
      description: Complete backend configuration with public key identifier
      required:
        - publicKey
        - partitions
        - weight
        - enabled
        - implementation
      properties:
        publicKey:
          type: string
          description: Secp256k1 public key in hex format (66 hex characters, 33 bytes)
          pattern: '^[0-9a-fA-F]{66}$'
          example: "03e7156ae33b0a208d0744199163177e909e80176e55d97a2f221ede0f934dd9ad"
        name:
          type: string
          nullable: true
          description: Optional human-readable name for the backend
        partitions:
          type: array
          items:
            type: string
          description: Load balancing partitions
        weight:
          type: integer
          minimum: 0
          description: Load balancing weight
        enabled:
          type: boolean
          description: Whether the backend is enabled
        implementation:
          $ref: '#/components/schemas/DiscoveryBackendImplementation'

    DiscoveryBackendSparse:
      type: object
      description: Backend configuration without address (used in PUT requests where address is in path)
      required:
        - partitions
        - weight
        - enabled
        - implementation
      properties:
        name:
          type: string
          nullable: true
          description: Optional human-readable name for the backend
        partitions:
          type: array
          items:
            type: string
          description: Load balancing partitions
        weight:
          type: integer
          minimum: 0
          description: Load balancing weight
        enabled:
          type: boolean
          description: Whether the backend is enabled
        implementation:
          $ref: '#/components/schemas/DiscoveryBackendImplementation'
          
    DiscoveryBackendPatchSparse:
      type: object
      description: Partial update payload for backend configuration without address (used in PATCH requests where address is in path). All fields are optional.
      properties:
        name:
          type: string
          nullable: true
          description: Optional name for the backend
        partitions:
          type: array
          items:
            type: string
          description: Load balancing partitions
        weight:
          type: integer
          minimum: 0
          description: Load balancing weight
        enabled:
          type: boolean
          description: Whether the backend is enabled

    DiscoveryBackendImplementation:
      oneOf:
        - $ref: '#/components/schemas/ClnGrpcImplementation'
        - $ref: '#/components/schemas/LndGrpcImplementation'
      discriminator:
        propertyName: type
        mapping:
          clnGrpc: '#/components/schemas/ClnGrpcImplementation'
          lndGrpc: '#/components/schemas/LndGrpcImplementation'

    ClnGrpcImplementation:
      type: object
      description: Core Lightning gRPC backend implementation
      required:
        - type
        - url
        - auth
      properties:
        type:
          type: string
          enum: [clnGrpc]
        url:
          type: string
          format: uri
          description: gRPC endpoint URL
        domain:
          type: string
          nullable: true
          description: Optional SNI domain for TLS verification
        auth:
          $ref: '#/components/schemas/ClnGrpcClientAuth'

    ClnGrpcClientAuth:
      type: object
      description: Authentication configuration for CLN gRPC
      required:
        - type
        - caCertPath
        - clientCertPath
        - clientKeyPath
      properties:
        type:
          type: string
          enum: [path]
        caCertPath:
          type: string
          description: Path to CA certificate file
        clientCertPath:
          type: string
          description: Path to client certificate file
        clientKeyPath:
          type: string
          description: Path to client key file

    LndGrpcImplementation:
      type: object
      description: LND gRPC backend implementation
      required:
        - type
        - url
        - auth
        - ampInvoice
      properties:
        type:
          type: string
          enum: [lndGrpc]
        url:
          type: string
          format: uri
          description: gRPC endpoint URL
        domain:
          type: string
          nullable: true
          description: Optional SNI domain for TLS verification
        auth:
          $ref: '#/components/schemas/LndGrpcClientAuth'
        ampInvoice:
          type: boolean
          description: Whether to use AMP invoices

    LndGrpcClientAuth:
      type: object
      description: Authentication configuration for LND gRPC
      required:
        - type
        - tlsCertPath
        - macaroonPath
      properties:
        type:
          type: string
          enum: [path]
        tlsCertPath:
          type: string
          description: Path to TLS certificate file
        macaroonPath:
          type: string
          description: Path to macaroon file