ankusa-sdk 0.3.0

data/lib/ankusa/claim_check.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Ankusa
+  # Every failure the claim-check client can raise.
+  #
+  # `retryable?` is the whole point of this hierarchy: a caller (a queue
+  # consumer, typically) needs exactly one bit -- dead-letter or retry -- and
+  # nothing here requires it to know the gateway's status codes to get that
+  # right.
+  #
+  # Non-retryable: the ref or expected sha256 is malformed, the gateway said
+  # 404/other 4xx, or the bytes that came back don't match the sha256.
+  # Retryable: the gateway said 5xx/503, or the request never completed
+  # (network error, timeout).
+  class ClaimCheckError < Error
+    def retryable? = false
+  end
+
+  # The ref string isn't a `urn:ankusa:claim:v1:<tenant>:<claim_id>`
+  # claim-check ref, or the expected sha256 isn't 64-char lowercase hex.
+  class InvalidClaimRefError < ClaimCheckError
+  end
+
+  # The gateway returned 404: no such object, expired by retention or never
+  # written.
+  class ClaimNotFoundError < ClaimCheckError
+  end
+
+  # The gateway rejected the request (400 or any other non-404 4xx).
+  class ClaimRejectedError < ClaimCheckError
+    attr_reader :status, :body
+
+    def initialize(message, status:, body:)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+
+  # The sha256 of the bytes the gateway returned doesn't match the expected
+  # sha256 the queue message carries. The gateway itself never checks this --
+  # see "Redeem a claim" in docs/claim-check.md -- so this is the reader's own
+  # end-to-end check, always run before `redeem` returns.
+  class ClaimIntegrityError < ClaimCheckError
+  end
+
+  # The gateway is unreachable, or answered 5xx/503. Safe to retry.
+  class ClaimCheckUnavailableError < ClaimCheckError
+    def retryable? = true
+  end
+
+  # A parsed claim-check ref, ready to become a GET /v1/claims/... request.
+  ParsedClaimRef = Data.define(:tenant_id, :claim_id, :path)
+
+  # Mirrors `#/components/schemas/Ref` in priv/openapi/claim_check.v1.yaml --
+  # keep the two in sync. A ref is one string:
+  #   urn:ankusa:claim:v1:<tenant>:<claim_id>
+  #
+  # \A...\z, never ^...$: Ruby's ^ and $ are line anchors, so a ref ending in a
+  # newline would otherwise parse.
+  CLAIM_REF_PATTERN = /\Aurn:ankusa:claim:v1:([A-Za-z0-9_-]{1,64}):([0-7][0-9A-HJKMNP-TV-Z]{25})\z/
+
+  SHA256_PATTERN = /\A[0-9a-f]{64}\z/
+
+  # Parses a claim-check ref (the `claim` field of a queue message) into the
+  # tenant id, claim id, and GET /v1/claims/{tenant_id}/{claim_id} path. Raises
+  # `InvalidClaimRefError` -- never worth retrying -- if `ref` isn't a
+  # well-formed ref.
+  def self.parse_claim_ref(ref)
+    match = ref.is_a?(String) ? CLAIM_REF_PATTERN.match(ref) : nil
+    raise InvalidClaimRefError, "invalid claim-check ref: #{ref}" if match.nil?
+
+    tenant_id = match[1]
+    claim_id = match[2]
+    ParsedClaimRef.new(tenant_id: tenant_id, claim_id: claim_id, path: "/v1/claims/#{tenant_id}/#{claim_id}")
+  end
+
+  # Redeem claim-check refs against a deployment's claim-check gateway.
+  #
+  # The gateway itself does no authentication or authorization (see
+  # docs/claim-check.md) -- `headers` is for whatever a deployer's own boundary
+  # (service mesh, an API gateway) expects in front of it.
+  class ClaimCheckClient
+    def initialize(base_url, headers: nil, timeout: 10.0, transport: nil)
+      @connection = Connection.new(base_url, headers: headers, timeout: timeout, transport: transport)
+    end
+
+    # Redeem a claim-check ref: fetch its bytes and verify them against
+    # `sha256` (the queue message's `sha256` field, 64-char lowercase hex)
+    # before returning. The gateway does not check integrity itself -- see
+    # "Redeem a claim" in docs/claim-check.md -- so this end-to-end check always
+    # runs here.
+    #
+    # Raises a `ClaimCheckError`; check `retryable?` to sort a failure into
+    # dead-letter (false) or retry (true).
+    def redeem(ref, sha256)
+      parsed = Ankusa.parse_claim_ref(ref)
+      unless sha256.is_a?(String) && SHA256_PATTERN.match?(sha256)
+        raise InvalidClaimRefError, "invalid claim sha256: #{sha256.inspect}"
+      end
+
+      body = fetch_bytes(parsed)
+      if Digest::SHA256.hexdigest(body) != sha256
+        raise ClaimIntegrityError, "claim sha256 mismatch for #{parsed.tenant_id}/#{parsed.claim_id}"
+      end
+
+      body
+    end
+
+    # Liveness probe: GET /health.
+    def health
+      response = @connection.request("GET", "/health")
+      status = response.status
+      if status != 200
+        raise ClaimCheckUnavailableError, "claim-check gateway health check failed (#{status})"
+      end
+
+      Connection.parse_json(response.body)
+    rescue Transport::Error => e
+      raise ClaimCheckUnavailableError, "claim-check gateway unreachable: #{e.message}"
+    rescue JSON::ParserError
+      raise ClaimCheckUnavailableError, "claim-check gateway health check returned a non-JSON body (#{status})"
+    end
+
+    private
+
+    def fetch_bytes(parsed)
+      response = @connection.request("GET", parsed.path)
+      status = response.status
+      if status == 404
+        raise ClaimNotFoundError, "claim not found: #{parsed.tenant_id}/#{parsed.claim_id}"
+      end
+
+      if status >= 400 && status < 500
+        body = Connection.error_body(response)
+        raise ClaimRejectedError.new(
+          "claim-check rejected redeem (#{status}): #{body.inspect}",
+          status: status,
+          body: body
+        )
+      end
+
+      if status != 200
+        raise ClaimCheckUnavailableError,
+          "claim-check gateway error (#{status}): #{Connection.error_body(response).inspect}"
+      end
+
+      response.body
+    rescue Transport::Error => e
+      raise ClaimCheckUnavailableError, "claim-check gateway unreachable: #{e.message}"
+    end
+  end
+end

data/lib/ankusa/connection.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Ankusa
+  # Shared by every client, so the URL, query, body, and JSON rules live in one
+  # place.
+  #
+  # @api private
+  class Connection
+    attr_reader :base_url, :headers
+
+    def initialize(base_url, headers: nil, timeout: 10.0, transport: nil)
+      @base_url = base_url.to_s.chomp("/")
+      @headers = (headers || {}).to_h { |key, value| [key.to_s, value.to_s] }
+      @transport = transport || Transport::NetHTTP.new(timeout: timeout)
+    end
+
+    # One request. Raises `Transport::Error` for anything that went wrong on the
+    # wire; mapping that to a client error is the caller's job.
+    #
+    # `query` entries whose value is nil are dropped, so an absent parameter is
+    # never sent as `=`. A non-nil `json` becomes the body, with the client
+    # headers extended by `content-type: application/json` -- a request-specific
+    # header of the same name wins.
+    def request(http_method, path, query: nil, json: nil)
+      url = URI.parse("#{@base_url}#{path}#{query_string(query)}")
+      headers = @headers.dup
+      body = nil
+      unless json.nil?
+        body = JSON.generate(json)
+        headers["content-type"] = "application/json"
+      end
+
+      @transport.call(Transport::Request.new(http_method: http_method, url: url, headers: headers, body: body))
+    end
+
+    # Parses a response body as JSON. Raises `JSON::ParserError`, which each
+    # caller maps to its own error.
+    def self.parse_json(body)
+      JSON.parse(body.dup.force_encoding(Encoding::UTF_8))
+    end
+
+    # The decoded error body: JSON when the body is JSON regardless of its
+    # content-type, otherwise the raw text with invalid bytes scrubbed. An empty
+    # body gives `""`.
+    def self.error_body(response)
+      parse_json(response.body)
+    rescue JSON::ParserError
+      response.body.dup.force_encoding(Encoding::UTF_8).scrub
+    end
+
+    private
+
+    def query_string(query)
+      pairs = (query || {}).reject { |_, value| value.nil? }.to_a
+      return "" if pairs.empty?
+
+      "?#{URI.encode_www_form(pairs)}"
+    end
+  end
+end

data/lib/ankusa/error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Ankusa
+  # The root of every error this SDK raises; each client's family base (and so
+  # every error below it) is a subclass. It deliberately does not respond to
+  # `retryable?`: only a family that defines the retryable/not-retryable split
+  # carries that bit, so a caller can't read one off this class by mistake.
+  class Error < StandardError
+  end
+end

data/lib/ankusa/routes.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Ankusa
+  # Every failure the routes client can raise.
+  #
+  # `retryable?` is the whole point of this hierarchy, exactly as in the
+  # claim-check client: a caller (an operator script, a controller loop) needs
+  # one bit -- leave the table alone and retry, or surface the rejection.
+  #
+  # Non-retryable: the listener said 404 (no such route) or another 4xx (a
+  # rejected write, a duplicate, the cap), or the id was unusable before any
+  # request was sent. Retryable: the listener said 5xx/503 store_unavailable, or
+  # the request never completed (network error, timeout).
+  class RoutesError < Error
+    def retryable? = false
+  end
+
+  # The route `id` cannot be used to build a path.
+  #
+  # Raised before any request is sent. An id that isn't a string, is empty, or
+  # is exactly `.` or `..` is refused: URL parsers normalize those away, so
+  # `get_route("..")` would quietly hit /admin/ and return the list page as if
+  # it were a route. Every other id is percent-encoded as one path segment,
+  # never refused.
+  class InvalidRouteIdError < RoutesError
+  end
+
+  # The listener is unreachable, or answered 5xx/503. Safe to retry.
+  class RoutesUnavailableError < RoutesError
+    def retryable? = true
+  end
+
+  # The listener returned 404: no such route.
+  class RouteNotFoundError < RoutesError
+  end
+
+  # The listener rejected the request (400 or any other non-404 4xx).
+  #
+  # `code` is the body's `error` field (`invalid_route`, `duplicate_route`,
+  # `too_many_routes`, ...); `field`, `message`, `conflicting_id` and
+  # `max_routes` are carried through when the body supplies them.
+  class RoutesRejectedError < RoutesError
+    attr_reader :status, :code, :field, :conflicting_id, :max_routes
+
+    def initialize(message, status:, code:, field: nil, conflicting_id: nil, max_routes: nil)
+      super(message)
+      @status = status
+      @code = code
+      @field = field
+      @conflicting_id = conflicting_id
+      @max_routes = max_routes
+    end
+  end
+
+  # Manage routes and global IP rules on the route-management listener
+  # (`routes.admin.port`, default 4003).
+  #
+  # Route ids are percent-encoded as a single path segment, so `/`, `?`, `#` and
+  # `%` in an id can't reshape the URL; an id that isn't a string, is empty, or
+  # is `.`/`..` raises `InvalidRouteIdError` before any request is sent.
+  class RoutesClient
+    def initialize(base_url, headers: nil, timeout: 10.0, transport: nil)
+      @connection = Connection.new(base_url, headers: headers, timeout: timeout, transport: transport)
+    end
+
+    # Liveness probe: GET /health -> {status, routes}.
+    def health
+      json(request("GET", "/health"))
+    end
+
+    # GET /admin/routes -> a page of route definitions.
+    #
+    # `params` may carry `enabled`, `limit` and `cursor`; absent keys are
+    # omitted from the query string rather than sent as `=`.
+    def list_routes(params = nil)
+      json(request("GET", "/admin/routes", query: params))
+    end
+
+    # POST /admin/routes -> the stored route, timestamps included.
+    def create_route(input)
+      json(request("POST", "/admin/routes", json: input))
+    end
+
+    # GET /admin/routes/{id} -> the route.
+    def get_route(id)
+      json(request("GET", "/admin/routes/#{route_path(id)}"))
+    end
+
+    # PUT /admin/routes/{id} -> the replaced (or created) route.
+    def replace_route(id, input)
+      json(request("PUT", "/admin/routes/#{route_path(id)}", json: input))
+    end
+
+    # PATCH /admin/routes/{id} -> the patched route.
+    def update_route(id, patch)
+      json(request("PATCH", "/admin/routes/#{route_path(id)}", json: patch))
+    end
+
+    # DELETE /admin/routes/{id} (204, no body).
+    def delete_route(id)
+      request("DELETE", "/admin/routes/#{route_path(id)}")
+      nil
+    end
+
+    # GET /admin/ip-rules -> the global IP rules.
+    def get_ip_rules
+      json(request("GET", "/admin/ip-rules"))
+    end
+
+    # PUT /admin/ip-rules -> the stored rules, as parsed.
+    def put_ip_rules(rules)
+      json(request("PUT", "/admin/ip-rules", json: rules))
+    end
+
+    # POST /admin/routes/test -> the dry-run decision for `request`.
+    def test_route(request)
+      json(self.request("POST", "/admin/routes/test", json: request))
+    end
+
+    private
+
+    def request(http_method, path, query: nil, json: nil)
+      response = @connection.request(http_method, path, query: query, json: json)
+      raise_for_status(response)
+      response
+    rescue Transport::Error => e
+      raise RoutesUnavailableError, "routes listener unreachable: #{e.message}"
+    end
+
+    def json(response)
+      Connection.parse_json(response.body)
+    rescue JSON::ParserError
+      raise RoutesUnavailableError, "routes listener returned a non-JSON body (#{response.status})"
+    end
+
+    def raise_for_status(response)
+      status = response.status
+      return if status >= 200 && status < 300
+
+      if status == 404
+        raise RouteNotFoundError, "route not found (#{status})"
+      end
+
+      if status >= 400 && status < 500
+        body = Connection.error_body(response)
+        raise RoutesRejectedError.new(
+          rejection_message(status, body),
+          status: status,
+          code: field(body, "error"),
+          field: field(body, "field"),
+          conflicting_id: field(body, "conflicting_id"),
+          max_routes: field(body, "max_routes")
+        )
+      end
+
+      raise RoutesUnavailableError, "routes listener error (#{status}): #{Connection.error_body(response).inspect}"
+    end
+
+    # The server's own `message` when the body carries a string one, else the
+    # rejection rendered whole.
+    def rejection_message(status, body)
+      message = field(body, "message")
+      return message if message.is_a?(String)
+
+      "routes listener rejected the request (#{status}): #{body.inspect}"
+    end
+
+    def field(body, name)
+      body.is_a?(Hash) ? body[name] : nil
+    end
+
+    # Validates `id` and percent-encodes it as ONE path segment.
+    #
+    # `.` and `..` (and an empty id) are refused rather than encoded: a URL
+    # parser normalizes them away before the request is sent, so `..` would
+    # become /admin/ and an empty id or `.` the collection endpoint -- the
+    # caller would get the list page back as if it were a route. Everything else
+    # travels with `/`, `?`, `#`, `%` and space escaped as %2F %3F %23 %25 %20
+    # instead of reshaping the URL.
+    def route_path(id)
+      raise InvalidRouteIdError, "route id must be a string, got #{id.inspect}" unless id.is_a?(String)
+      raise InvalidRouteIdError, "invalid route id #{id.inspect}" if ["", ".", ".."].include?(id)
+
+      id.b.gsub(/[^A-Za-z0-9_.~-]/) { |char| format("%%%02X", char.ord) }
+    end
+  end
+end

data/lib/ankusa/sdk/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ankusa
+  module SDK
+    VERSION = "0.3.0"
+  end
+end

data/lib/ankusa/sdk.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "sdk/version"
+require_relative "error"
+require_relative "transport"
+require_relative "connection"
+require_relative "webhook"
+require_relative "claim_check"
+require_relative "routes"
+require_relative "admin"
+require_relative "sources"