openapi.yaml

openapi: "3.1.0"
info:
  title: check.quip.network
  description: |
    Network diagnostic service for the QUIP P2P network. Provides IP lookup,
    TCP port checking, and QUIC/QUIP protocol connectivity verification.

    Every endpoint except /health is rate limited per client IP by a token
    bucket. The bucket holds 10 requests and refills at 2 per second, so a
    client may burst 10 requests and then sustain 2 per second indefinitely.
    A request that arrives at an empty bucket earns a ban of at most 5
    minutes and receives a 429 response.
  version: "1.0.0"
  license:
    name: AGPL-3.0-or-later
    url: https://www.gnu.org/licenses/agpl-3.0.html

servers:
  - url: https://check.quip.network
    description: Production
  - url: http://localhost:8080
    description: Local development

paths:
  /health:
    get:
      summary: Health check
      description: Returns service health status. Not rate limited.
      operationId: getHealth
      responses:
        "200":
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                required: [status]
                properties:
                  status:
                    type: string
                    enum: [ok]
                    example: ok

  /ip:
    get:
      summary: Client IP lookup
      description: |
        Returns the client's public IP address as seen by the service.
        Extracts from X-Forwarded-For (first entry), X-Real-IP, or RemoteAddr.
      operationId: getIP
      responses:
        "200":
          description: Client IP address
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IPResponse"
        "429":
          $ref: "#/components/responses/RateLimited"

  /checkport:
    get:
      summary: TCP port check (self-check)
      description: |
        Checks whether a TCP port is reachable on the caller's own IP.
        The target host is always derived from the caller's connection —
        no host parameter is accepted, preventing use as a port scanner.
        Performs a TCP connect with 5s timeout and attempts to read
        the first 4 bytes (banner grab) with a 1s read timeout.

        Results are cached per caller IP and port. A reachable result is
        held for 1 hour, an unreachable result for 1 minute. The short
        failure window lets an operator who opens a port see the change
        on the next request. A cached response reports `cached: true` and
        an `X-Cache: HIT` header.
      operationId: checkPort
      parameters:
        - name: port
          in: query
          required: true
          description: TCP port number (1-65535)
          schema:
            type: integer
            minimum: 1
            maximum: 65535
            example: 20049
      responses:
        "200":
          description: Port check result
          headers:
            X-Cache:
              $ref: "#/components/headers/XCache"
            X-Cache-Cached-At:
              $ref: "#/components/headers/XCacheCachedAt"
            X-Cache-Expires:
              $ref: "#/components/headers/XCacheExpires"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckPortResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimited"

  /checkconn:
    get:
      summary: QUIP connectivity check (self-check)
      description: |
        Verifies QUIC/QUIP protocol connectivity back to the caller's own IP.
        The target host is always derived from the caller's connection —
        no host parameter is accepted, preventing use as a QUIC scanner.
        Performs a QUIC handshake with ALPN "quip-v1", TLS 1.3,
        then sends a STATUS_REQUEST datagram and waits for a
        STATUS_RESPONSE. Self-signed certificates are accepted.

        Results are cached per caller IP and port, on the same terms as
        /checkport: 1 hour for a successful handshake, 1 minute for a
        failure. A cached response reports `cached: true` and an
        `X-Cache: HIT` header.
      operationId: checkConn
      parameters:
        - name: port
          in: query
          required: false
          description: QUIC port number (defaults to 20049)
          schema:
            type: integer
            minimum: 1
            maximum: 65535
            default: 20049
      responses:
        "200":
          description: QUIP connectivity result
          headers:
            X-Cache:
              $ref: "#/components/headers/XCache"
            X-Cache-Cached-At:
              $ref: "#/components/headers/XCacheCachedAt"
            X-Cache-Expires:
              $ref: "#/components/headers/XCacheExpires"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckConnResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimited"

  /checkhostname:
    get:
      summary: Hostname-to-IP match check
      description: |
        Checks whether the caller's public IP matches the DNS resolution
        of the provided hostname. Useful for QUIP nodes to verify their
        DNS is correctly configured before advertising their hostname.
      operationId: checkHostname
      parameters:
        - name: hostname
          in: query
          required: true
          description: Hostname to resolve and compare against the caller's IP
          schema:
            type: string
            example: node1.quip.network
      responses:
        "200":
          description: Hostname match result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckHostnameResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimited"

  /probe:
    get:
      summary: Host-targeted node probes (reward boosts)
      description: |
        Runs the same connectivity checks used for testnet node operator
        reward percentage boosts against an explicit host (not the caller IP).
        Source of truth for probe semantics (p2p, api_port, tls, rpc,
        telemetry, dashboard). Subject to the global per-IP rate limit.
        Loopback and link-local targets are rejected.

        Each target host is probed at most once per 24 hours. Later requests
        for that host return the stored result with `cached` set to true and
        an `X-Cache: HIT` header. The cache key is the host alone, so a
        request that gives different ports or checks still returns the stored
        result; `params_used` reports the options the stored probe ran with.
      operationId: probeHost
      parameters:
        - name: host
          in: query
          required: true
          description: Public hostname or IP to probe
          schema:
            type: string
            example: miner.example.com
        - name: api_port
          in: query
          schema:
            type: integer
            default: 20049
            minimum: 1
            maximum: 65535
        - name: p2p_port
          in: query
          schema:
            type: integer
            default: 30333
            minimum: 1
            maximum: 65535
        - name: tls_port
          in: query
          description: TLS port (0 skips the TLS check)
          schema:
            type: integer
            default: 443
        - name: checks
          in: query
          description: >
            Comma-separated check names, or "all". Names are matched after
            trimming and lowercasing. An unrecognized name is rejected with
            400 rather than returning an empty result set.
          schema:
            type: string
            default: all
            example: p2p,api_port,tls,rpc,telemetry,dashboard
        - name: http
          in: query
          description: If true/1, use http instead of https for API paths
          schema:
            type: string
            enum: ["0", "1", "true", "false"]
        - name: timeout
          in: query
          description: Per-check timeout in seconds (max 30)
          schema:
            type: number
            default: 5
      responses:
        "200":
          description: Probe results, freshly run or served from the 24h cache
          headers:
            X-Cache:
              $ref: "#/components/headers/XCache"
            X-Cache-Cached-At:
              $ref: "#/components/headers/XCacheCachedAt"
            X-Cache-Expires:
              $ref: "#/components/headers/XCacheExpires"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProbeResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimited"

components:
  headers:
    XCache:
      description: HIT if served from cache, MISS if the check ran on this request
      schema:
        type: string
        enum: [HIT, MISS]
    XCacheCachedAt:
      description: When the returned result was produced (RFC 3339)
      schema:
        type: string
        format: date-time
    XCacheExpires:
      description: When the target may be checked again (RFC 3339)
      schema:
        type: string
        format: date-time

  schemas:
    IPResponse:
      type: object
      required: [ip]
      properties:
        ip:
          type: string
          description: Client's public IP address
          example: "203.0.113.42"

    CheckPortResponse:
      type: object
      required: [host, port, reachable, cached, cached_at, expires_at]
      properties:
        cached:
          type: boolean
          description: True when the result comes from an earlier check
        cached_at:
          type: string
          format: date-time
          description: When the returned check ran (RFC 3339)
        expires_at:
          type: string
          format: date-time
          description: When the port may be checked again (RFC 3339)
        host:
          type: string
          example: node1.quip.network
        port:
          type: integer
          example: 20049
        reachable:
          type: boolean
          description: Whether the TCP connection succeeded
        bytes:
          type: string
          description: Hex-encoded first bytes read from the connection (only when reachable)
          example: "0a1b2c3d"
        error:
          type: string
          description: Error message (only when not reachable)
          example: "connection refused"

    CheckConnResponse:
      type: object
      required: [host, port, quip, cached, cached_at, expires_at]
      properties:
        cached:
          type: boolean
          description: True when the result comes from an earlier check
        cached_at:
          type: string
          format: date-time
          description: When the returned check ran (RFC 3339)
        expires_at:
          type: string
          format: date-time
          description: When the port may be checked again (RFC 3339)
        host:
          type: string
          example: node1.quip.network
        port:
          type: integer
          example: 20049
        quip:
          type: boolean
          description: Whether the QUIC handshake with ALPN quip-v1 succeeded
        handshake_ms:
          type: integer
          description: QUIC handshake duration in milliseconds (only when quip=true)
          example: 123
        status_response:
          type: boolean
          description: Whether a STATUS_RESPONSE datagram was received (only when quip=true)
        error:
          type: string
          description: Error message (only when quip=false)
          example: "handshake timeout"

    CheckHostnameResponse:
      type: object
      required: [hostname, client_ip, match]
      properties:
        hostname:
          type: string
          example: node1.quip.network
        client_ip:
          type: string
          description: The caller's public IP as seen by the service
          example: "203.0.113.42"
        resolved_ips:
          type: array
          items:
            type: string
          description: All IPs the hostname resolves to
          example: ["203.0.113.42", "2001:db8::1"]
        match:
          type: boolean
          description: Whether the client's IP is among the resolved IPs
        error:
          type: string
          description: Error message if DNS lookup failed

    ProbeResult:
      type: object
      required: [name, ok]
      properties:
        name:
          type: string
          example: p2p
        ok:
          type: boolean
        detail:
          type: string
        host:
          type: string
        port:
          type: integer
          nullable: true

    ProbeParams:
      type: object
      description: The options the returned probe actually ran with
      required: [api_port, p2p_port, tls_port, https, timeout_seconds, checks]
      properties:
        api_port:
          type: integer
          example: 20049
        p2p_port:
          type: integer
          example: 30333
        tls_port:
          type: integer
          description: 0 means the TLS check was skipped
          example: 443
        https:
          type: boolean
        timeout_seconds:
          type: number
          example: 5
        checks:
          type: array
          items:
            type: string
          example: [p2p, api_port, tls, rpc, telemetry, dashboard]

    ProbeResponse:
      type: object
      required: [cached, cached_at, expires_at, host, params_used, checks]
      properties:
        cached:
          type: boolean
          description: >
            True when the result came from the 24h cache and no probe ran for
            this request.
        cached_at:
          type: string
          format: date-time
          description: When the returned probe ran
        expires_at:
          type: string
          format: date-time
          description: When the host may be probed again
        host:
          type: string
          description: The host given in the request
          example: miner.example.com
        params_used:
          $ref: "#/components/schemas/ProbeParams"
        checks:
          type: object
          description: Map of check name to result
          additionalProperties:
            $ref: "#/components/schemas/ProbeResult"

    RateLimitResponse:
      type: object
      required: [error, retry_after_seconds, ban_level]
      properties:
        error:
          type: string
          enum: ["rate limited"]
        retry_after_seconds:
          type: integer
          description: Seconds until the ban expires. Never more than 300.
          maximum: 300
          example: 60
        ban_level:
          type: integer
          description: |
            Escalation level. Level 1 bans for 30 seconds, level 2 for 2
            minutes, level 3 and above for 5 minutes. The level resets after
            15 minutes without a violation.
          example: 1

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          example: "host parameter required"

  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    RateLimited:
      description: Rate limit exceeded with escalating ban
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/RateLimitResponse"