ankusa-sdk 0.3.0

data/lib/ankusa/sources.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+module Ankusa
+  # Every failure the source-management client can raise.
+  #
+  # Every subclass carries the HTTP `status` and decoded `body` of the response
+  # that produced it (both nil when no response was involved, e.g. a transport
+  # failure). Unlike the other families this one has no `retryable?`, matching
+  # the reference SDK.
+  class SourcesError < Error
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+
+  # 404: no such source for this tenant.
+  class SourceNotFoundError < SourcesError
+  end
+
+  # 409 source_exists: a source with that name already exists.
+  class SourceConflictError < SourcesError
+  end
+
+  # 409 source_store_read_only: the deployment's source store is a static seed,
+  # so writes are impossible.
+  class SourceStoreReadOnlyError < SourcesError
+  end
+
+  # 400: bad tenant, bad source name, or a spec the server rejected.
+  #
+  # `message` is the server's own `message` (for a bad spec) or the `error` code
+  # (for a bad tenant/name, which has no message).
+  class SourceInvalidError < SourcesError
+  end
+
+  # The admin API is unreachable, timed out, or answered 5xx. Safe to retry.
+  class SourcesUnavailableError < SourcesError
+  end
+
+  # GET /health reported a version other than `expected_version`.
+  class VersionMismatchError < SourcesError
+  end
+
+  # The writable fields of a source, as submitted to POST/PUT.
+  #
+  # `verify` is optional (absent means `{"type" => "none"}` on the server);
+  # `sinks` is required and must be non-empty -- the server validates all of
+  # this exactly as the YAML config does.
+  SourceSpec = Data.define(:sinks, :verify, :on_verify_failure) do
+    def initialize(sinks:, verify: nil, on_verify_failure: nil) = super
+
+    # The JSON body for a create/update, omitting unset (nil) fields.
+    def to_request_body
+      body = {"sinks" => sinks}
+      body["verify"] = verify unless verify.nil?
+      body["on_verify_failure"] = on_verify_failure unless on_verify_failure.nil?
+      body
+    end
+  end
+
+  # A stored source as the admin API reports it: redacted spec plus the derived
+  # identity fields.
+  Source = Data.define(:tenant, :name, :source_id, :ingest_path, :verify, :on_verify_failure, :sinks) do
+    def self.from_h(data)
+      new(
+        tenant: data.fetch("tenant"),
+        name: data.fetch("name"),
+        source_id: data.fetch("source_id"),
+        ingest_path: data.fetch("ingest_path"),
+        verify: data["verify"] || {"type" => "none"},
+        on_verify_failure: data["on_verify_failure"],
+        sinks: data["sinks"] || []
+      )
+    end
+  end
+
+  # Manage a deployment's tenant-scoped sources via `Ankusa.Admin.Router` (the
+  # same `admin.port` as the operator API).
+  #
+  # The router does no authentication (by design, like the rest of this port),
+  # and every source it returns has its secrets redacted. So a `Source` read
+  # back here is never useful for editing: resending its `verify` map is not the
+  # same as resending the stored secret. Callers that hold the secret supply it
+  # through `SourceSpec`.
+  #
+  # Only `[A-Za-z0-9_-]{1,64}` tenants and names are accepted, and both are
+  # checked before any path is built, so a caller-supplied name cannot escape
+  # its tenant through URL normalization.
+  #
+  # `expected_version` is an optional safety latch: when set, the first API call
+  # fetches GET /health once, compares its `"version"` field against the
+  # expected value, caches the fetched version, and raises
+  # `VersionMismatchError` on any mismatch. Every subsequent call re-checks the
+  # cached value without another request.
+  class SourcesClient
+    # The same rule `Ankusa::CLAIM_REF_PATTERN` uses for its tenant. Anything
+    # outside it is rejected before a path is built: URL parsers normalize dot
+    # segments, so an unvalidated "../" would escape the tenant scope before the
+    # server sees it.
+    SAFE_ID = /\A[A-Za-z0-9_-]{1,64}\z/
+
+    def initialize(base_url, expected_version: nil, timeout: 10.0, transport: nil)
+      @connection = Connection.new(base_url, timeout: timeout, transport: transport)
+      @expected_version = expected_version
+      @server_version = nil
+    end
+
+    # The deployment's Ankusa version: GET /health ["version"].
+    #
+    # Fetched once and cached; when `expected_version` was set this also
+    # enforces it, so a mismatched deployment raises `VersionMismatchError` here
+    # too.
+    def server_version
+      @server_version = fetch_version if @server_version.nil?
+      check_version
+      @server_version
+    end
+
+    # List a tenant's sources: GET /v1/tenants/<tenant>/sources.
+    def list_sources(tenant)
+      validate_tenant(tenant)
+      ensure_version
+      response = request("GET", "/v1/tenants/#{tenant}/sources")
+      raise_for_status(response)
+      parse_json(response).fetch("entries").map { |entry| Source.from_h(entry) }
+    end
+
+    # Fetch one source: GET /v1/tenants/<tenant>/sources/<name>.
+    def get_source(tenant, name)
+      validate_tenant(tenant)
+      validate_name(name)
+      ensure_version
+      response = request("GET", "/v1/tenants/#{tenant}/sources/#{name}")
+      raise_for_status(response)
+      Source.from_h(parse_json(response))
+    end
+
+    # Create a source: POST /v1/tenants/<tenant>/sources.
+    #
+    # The source name travels in the body (plus `name`); the tenant comes from
+    # the URL and wins over any `"tenant"` key inside `spec`.
+    def create_source(tenant, name, spec)
+      validate_tenant(tenant)
+      validate_name(name)
+      ensure_version
+      body = spec.to_request_body.merge("name" => name)
+      response = request("POST", "/v1/tenants/#{tenant}/sources", json: body)
+      raise_for_status(response)
+      Source.from_h(parse_json(response))
+    end
+
+    # Replace a source: PUT /v1/tenants/<tenant>/sources/<name>.
+    #
+    # The name comes from the URL; a `"name"` key inside `spec` is never sent
+    # (`SourceSpec` has no such field).
+    def update_source(tenant, name, spec)
+      validate_tenant(tenant)
+      validate_name(name)
+      ensure_version
+      response = request("PUT", "/v1/tenants/#{tenant}/sources/#{name}", json: spec.to_request_body)
+      raise_for_status(response)
+      Source.from_h(parse_json(response))
+    end
+
+    # Delete a source: DELETE /v1/tenants/<tenant>/sources/<name>.
+    #
+    # Succeeds with no return value (the server answers 204 with an empty body);
+    # a missing source raises `SourceNotFoundError`.
+    def delete_source(tenant, name)
+      validate_tenant(tenant)
+      validate_name(name)
+      ensure_version
+      response = request("DELETE", "/v1/tenants/#{tenant}/sources/#{name}")
+      raise_for_status(response)
+      nil
+    end
+
+    private
+
+    # The optional version latch: only when `expected_version` is set does the
+    # first API call fetch /health once, cache the version, and enforce it.
+    def ensure_version
+      return if @expected_version.nil?
+
+      @server_version = fetch_version if @server_version.nil?
+      check_version
+    end
+
+    def check_version
+      return if @expected_version.nil? || @server_version == @expected_version
+
+      raise VersionMismatchError,
+        "expected Ankusa version #{@expected_version.inspect}, server reports #{@server_version.inspect}"
+    end
+
+    def fetch_version
+      response = request("GET", "/health")
+      status = response.status
+      if status != 200
+        body = Connection.error_body(response)
+        raise SourcesUnavailableError.new(
+          "ankusa admin API health check failed (#{status}): #{body.inspect}",
+          status: status,
+          body: body
+        )
+      end
+
+      begin
+        data = Connection.parse_json(response.body)
+      rescue JSON::ParserError
+        raise SourcesUnavailableError, "ankusa admin API health check returned a non-JSON body (#{status})"
+      end
+
+      version = data.is_a?(Hash) ? data["version"] : nil
+      unless version.is_a?(String)
+        raise SourcesUnavailableError,
+          "ankusa admin API health check returned no version (#{status}): #{data.inspect}"
+      end
+
+      version
+    end
+
+    def request(http_method, path, json: nil)
+      @connection.request(http_method, path, json: json)
+    rescue Transport::Error => e
+      raise SourcesUnavailableError, "ankusa admin API unreachable: #{e.message}"
+    end
+
+    def parse_json(response)
+      Connection.parse_json(response.body)
+    rescue JSON::ParserError
+      # Deliberate deviation from the reference SDK, which lets its decoder's
+      # ValueError escape here: every other failure this client can produce is a
+      # SourcesError, so a 2xx that isn't JSON is one too.
+      raise SourcesUnavailableError.new(
+        "ankusa admin API returned a non-JSON body (#{response.status})",
+        status: response.status
+      )
+    end
+
+    def raise_for_status(response)
+      status = response.status
+      return if status >= 200 && status < 300
+
+      body = Connection.error_body(response)
+      if status == 404
+        raise SourceNotFoundError.new("source not found (#{status}): #{body.inspect}", status: status, body: body)
+      end
+
+      if status == 400
+        raise SourceInvalidError.new(invalid_message(body, status), status: status, body: body)
+      end
+
+      if status == 409
+        if body.is_a?(Hash) && body["error"] == "source_store_read_only"
+          raise SourceStoreReadOnlyError.new(
+            "source store is read-only (#{status}): #{body.inspect}",
+            status: status,
+            body: body
+          )
+        end
+
+        raise SourceConflictError.new("source already exists (#{status}): #{body.inspect}", status: status, body: body)
+      end
+
+      raise SourcesUnavailableError.new("ankusa admin API error (#{status}): #{body.inspect}", status: status, body: body)
+    end
+
+    def invalid_message(body, status)
+      if body.is_a?(Hash)
+        message = body["message"] || body["error"]
+        return message if message.is_a?(String)
+      end
+
+      "invalid source (#{status}): #{body.inspect}"
+    end
+
+    # Reject a tenant that is not `[A-Za-z0-9_-]{1,64}` before any path is
+    # built.
+    def validate_tenant(tenant)
+      return if tenant.is_a?(String) && SAFE_ID.match?(tenant)
+
+      raise SourceInvalidError, "invalid tenant: #{tenant.inspect}"
+    end
+
+    # Reject a source name that is not `[A-Za-z0-9_-]{1,64}` before any path is
+    # built.
+    def validate_name(name)
+      return if name.is_a?(String) && SAFE_ID.match?(name)
+
+      raise SourceInvalidError, "invalid source name: #{name.inspect}"
+    end
+  end
+end

data/lib/ankusa/transport.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+require "zlib"
+
+module Ankusa
+  # The injectable HTTP hook every client sends through.
+  #
+  # A transport is any object that responds to `call(Request) -> Response`,
+  # including a lambda. `Transport::NetHTTP` is the default, used when a client
+  # is built without one; tests inject a lambda and never touch the network.
+  module Transport
+    # One HTTP request. `http_method` is an upcased String -- not `method`,
+    # which would shadow `Object#method` -- and `url` is a full `URI::HTTP`.
+    Request = Data.define(:http_method, :url, :headers, :body)
+
+    # One HTTP response. `headers` has lowercase String keys; `body` is a binary
+    # String, `""` when the response carried no body.
+    Response = Data.define(:status, :headers, :body)
+
+    # Raised for any transport failure: connection refused, DNS failure, a
+    # timeout, a TLS error, a truncated response. An injected transport raises
+    # it too, to signal unreachable without a network.
+    class Error < Ankusa::Error
+    end
+
+    # The default transport: one `Net::HTTP` request per call, no redirects, no
+    # retries, and one timeout for connecting, reading, and writing.
+    class NetHTTP
+      def initialize(timeout:)
+        @timeout = timeout
+      end
+
+      def call(request)
+        url = request.url
+        # hostname, not host: for an IPv6 literal host is "[::1]" with the
+        # brackets still on, and Net::HTTP.addr_port adds them back from the
+        # bare address, so "[::1]" would go to DNS as written.
+        http = Net::HTTP.new(url.hostname, url.port)
+        http.use_ssl = url.scheme == "https"
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+        http.write_timeout = @timeout
+        # Net::HTTP retries idempotent requests (GET, PUT, DELETE, ...) once by
+        # default, which would send -- and so in the conformance vectors,
+        # record -- a second request.
+        http.max_retries = 0
+
+        http_request = Net::HTTPGenericRequest.new(
+          request.http_method,
+          !request.body.nil?,
+          request.http_method != "HEAD",
+          url.request_uri,
+          request.headers
+        )
+        http_request.body = request.body unless request.body.nil?
+
+        response = http.request(http_request)
+        Response.new(
+          status: response.code.to_i,
+          headers: response.each_header.to_h,
+          body: (response.body || "").b
+        )
+      rescue SystemCallError, IOError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError,
+        Net::ProtocolError, Net::HTTPBadResponse, Zlib::Error => e
+        raise Error, "#{e.class}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/ankusa/webhook.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Ankusa
+  # The identity of one HTTP-sink delivery: the headers Ankusa's HTTP sink
+  # attaches to every delivery.
+  #
+  # `content_type` and `tenant` are nil when the delivery had no such header
+  # (a tenant only travels when the source has one).
+  HookHeaders = Data.define(:id, :source, :tenant, :content_type)
+
+  # Raised by `Ankusa.parse_headers` when `x-ankusa-id` is absent or empty.
+  #
+  # Every other Ankusa header is optional; this one is the identity a receiver
+  # dedupes on, so a delivery without it is a framework bug, not a malformed but
+  # tolerable request.
+  class MissingHookIdError < Error
+  end
+
+  # Parses the `x-ankusa-*` headers of one delivery, whatever the mapping's own
+  # case behavior: lookup here is always case-insensitive.
+  #
+  # See "HTTP handoff" in docs/integrations.md for the delivery contract this
+  # mirrors. A receiver must dedupe on `x-ankusa-id`: delivery is at-least-once,
+  # so the same hook can arrive twice after a retry.
+  def self.parse_headers(headers)
+    lowered = headers.to_h { |key, value| [key.to_s.downcase, value] }
+
+    hook_id = lowered["x-ankusa-id"]
+    raise MissingHookIdError, "missing x-ankusa-id header" if hook_id.nil? || hook_id.empty?
+
+    HookHeaders.new(
+      id: hook_id,
+      source: lowered.fetch("x-ankusa-source", ""),
+      tenant: lowered["x-ankusa-tenant"],
+      content_type: lowered["content-type"]
+    )
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: ankusa-sdk
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- James Carr
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Client SDK for Ankusa deployments. Bundles the claim-check gateway client,
+  the route-management and operator (admin) clients, the source-management client,
+  and a webhook-receiving header helper; more clients (ingest) land here as they're
+  built.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ankusa/admin.rb
+- lib/ankusa/claim_check.rb
+- lib/ankusa/connection.rb
+- lib/ankusa/error.rb
+- lib/ankusa/routes.rb
+- lib/ankusa/sdk.rb
+- lib/ankusa/sdk/version.rb
+- lib/ankusa/sources.rb
+- lib/ankusa/transport.rb
+- lib/ankusa/webhook.rb
+homepage: https://github.com/jamescarr/ankusa/tree/main/packages/sdk-ruby
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/jamescarr/ankusa/tree/main/packages/sdk-ruby
+  source_code_uri: https://github.com/jamescarr/ankusa
+  bug_tracker_uri: https://github.com/jamescarr/ankusa/issues
+  changelog_uri: https://github.com/jamescarr/ankusa/blob/main/packages/sdk-ruby/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Client SDK for Ankusa deployments.
+test_files: []