morphe_adapter_sdk 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b3eeea159d98c6a1db3ad05249f184c498177a79a35f9be08c9b7841f1350411
+  data.tar.gz: dde2121058ab5dfee203bd9ee63ade7aca93a7d72915d122dc8191c963d98c1d
+SHA512:
+  metadata.gz: aab8206c95bf83c3d9995230c70c7ac181dab1bee7348608f966e2a1e3a494261a8cb529ca09caa21551cf654b254f84205356ce5fa890bd86624ccb22eacb6f
+  data.tar.gz: d33bb18d879de995fdcae194b492042d6119c3350835f7375b8dd97c91daf12015126ca9e4202257d5978822f1c9a79ab8579cda0c7d1f7b0aba275735055f0f

data/lib/morphe_adapter_sdk/client.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module MorpheAdapterSdk
+  # Synchronous client for emitting events to the Morphe Control Plane.
+  #
+  # Supports:
+  # - Optional pre-emit JSON Schema validation (+validate_schema: true+)
+  # - HMAC-SHA256 request signing (when +hmac_secret:+ is provided)
+  # - Exponential backoff retry on 5xx / network errors
+  # - Structured JSON:API error surface (ApiError, SchemaValidationError, NetworkError)
+  #
+  # @example
+  #   client = MorpheAdapterSdk::Client.new(token: ENV["MORPHE_TOKEN"])
+  #   result = client.emit(
+  #     event_type:     "dataops.v1.sync_failed",
+  #     system_id:      "11111111-1111-1111-1111-111111111111",
+  #     payload:        { records_failed: 42 },
+  #     idempotency_key: "req-abc-123"
+  #   )
+  #   puts result.id
+  class Client
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_BASE_DELAY  = 0.5 # seconds
+
+    # @!attribute [r] endpoint
+    #   @return [String] resolved Control Plane base URL
+    attr_reader :endpoint
+
+    # @param token           [String]  JWT Bearer token
+    # @param endpoint        [String, nil] override base URL (dev/self-hosted only)
+    # @param hmac_secret     [String, nil] HMAC-SHA256 shared secret
+    # @param max_retries     [Integer] default: 3
+    # @param base_delay      [Float]   default: 0.5 s
+    # @param validate_schema [Boolean] validate payload locally before emitting
+    def initialize(
+      token:,
+      endpoint: nil,
+      hmac_secret: nil,
+      max_retries: DEFAULT_MAX_RETRIES,
+      base_delay: DEFAULT_BASE_DELAY,
+      validate_schema: false
+    )
+      raw = endpoint || ENV["MORPHE_ENDPOINT"] || DEFAULT_ENDPOINT
+      @endpoint        = raw.chomp("/")
+      @token           = token
+      @hmac_secret     = hmac_secret
+      @max_retries     = max_retries
+      @base_delay      = base_delay
+      @validate_schema = validate_schema
+      @schema_cache    = {}
+    end
+
+    # Emit a single event to the Control Plane.
+    #
+    # If +validate_schema+ was set at construction, the payload is validated
+    # against the registered schema before any HTTP request is made.
+    # Raises +SchemaValidationError+ on failure.
+    #
+    # Retries on 5xx responses and network failures with exponential backoff.
+    # Raises +ApiError+ on non-retryable HTTP errors (4xx).
+    # Raises +NetworkError+ when the Control Plane cannot be reached.
+    #
+    # @param event [Hash] event payload (symbol or string keys)
+    # @return [EmitResult]
+    def emit(event)
+      event = stringify_keys(event)
+
+      validate!(event) if @validate_schema
+
+      MorpheAdapterSdk::Retry.call(
+        max_retries: @max_retries,
+        base_delay:  @base_delay,
+        should_retry: ->(err) {
+          err.is_a?(NetworkError) ||
+            (err.is_a?(ApiError) && err.status >= 500)
+        }
+      ) { do_request(event) }
+    end
+
+    private
+
+    EmitResult = Struct.new(:id, :received_at, :schema_valid, :schema_validation_errors, keyword_init: true)
+
+    def do_request(event)
+      body    = JSON.generate(event)
+      version = MorpheAdapterSdk.extract_api_version(event["event_type"])
+      uri     = URI.parse("#{@endpoint}/api/#{version}/events")
+
+      headers = {
+        "Content-Type"  => "application/json",
+        "Authorization" => "Bearer #{@token}"
+      }
+      headers["X-Morphe-Signature"] = MorpheAdapterSdk::Hmac.sign(body, @hmac_secret) if @hmac_secret
+
+      response = http_post(uri, body, headers)
+
+      if response.code.to_i == 202
+        data  = JSON.parse(response.body)
+        attrs = data.dig("data", "attributes")
+        return EmitResult.new(
+          id:                       data.dig("data", "id"),
+          received_at:              attrs["received_at"],
+          schema_valid:             attrs["schema_valid"],
+          schema_validation_errors: attrs["schema_validation_errors"] || []
+        )
+      end
+
+      errors = parse_errors(response)
+      raise ApiError.new(response.code.to_i, errors)
+    end
+
+    def http_post(uri, body, headers)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 10, read_timeout: 30) do |http|
+        req = Net::HTTP::Post.new(uri.request_uri, headers)
+        req.body = body
+        http.request(req)
+      end
+    rescue SocketError, Errno::ECONNREFUSED, Errno::ETIMEDOUT, Net::OpenTimeout, Net::ReadTimeout => e
+      raise NetworkError.new("Failed to reach the Control Plane", e)
+    end
+
+    def parse_errors(response)
+      body = JSON.parse(response.body)
+      body["errors"] || []
+    rescue JSON::ParserError
+      [ { "code" => "parse_error", "title" => "Could not parse error response" } ]
+    end
+
+    def validate!(event)
+      require "json-schema"
+
+      event_type = event["event_type"]
+      schema     = @schema_cache[event_type] ||= fetch_schema(event_type)
+      payload    = event["payload"] || {}
+
+      raw_errors = JSON::Validator.fully_validate(schema, payload)
+      return if raw_errors.empty?
+
+      failures = raw_errors.map { |msg| { field: "/", message: msg } }
+      raise SchemaValidationError.new(failures)
+    end
+
+    def fetch_schema(event_type)
+      version  = MorpheAdapterSdk.extract_api_version(event_type)
+      uri      = URI.parse("#{@endpoint}/api/#{version}/schemas/#{URI.encode_www_form_component(event_type)}")
+      headers  = { "Authorization" => "Bearer #{@token}" }
+
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 10, read_timeout: 30) do |http|
+        http.request(Net::HTTP::Get.new(uri.request_uri, headers))
+      end
+    rescue SocketError, Errno::ECONNREFUSED, Errno::ETIMEDOUT, Net::OpenTimeout, Net::ReadTimeout => e
+      raise NetworkError.new("Failed to fetch schema for #{event_type}", e)
+    else
+      unless (200..299).cover?(response.code.to_i)
+        errors = parse_errors(response)
+        raise ApiError.new(response.code.to_i, errors.empty? ? [ { "code" => "schema_not_found", "title" => "No schema registered for \"#{event_type}\"" } ] : errors)
+      end
+
+      data = JSON.parse(response.body)
+      data.dig("data", "attributes", "schema")
+    end
+
+    def stringify_keys(hash)
+      hash.transform_keys(&:to_s)
+    end
+  end
+end

data/lib/morphe_adapter_sdk/errors.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module MorpheAdapterSdk
+  # Base class for all Morphe SDK errors.
+  # Callers can rescue MorpheAdapterSdk::Error to catch any SDK error.
+  class Error < StandardError; end
+
+  # Raised when the Control Plane returns a non-2xx response.
+  #
+  # Exposes the first JSON:API error's +code+, +title+, and +detail+
+  # fields as top-level attributes for easy exception handling, plus the
+  # full +errors+ array for callers that want all details.
+  class ApiError < Error
+    attr_reader :status, :code, :title, :detail, :errors
+
+    # @param status [Integer] HTTP status code
+    # @param errors [Array<Hash>] JSON:API errors array
+    def initialize(status, errors = [])
+      first = errors.first || {}
+      @status = status
+      @code   = first["code"] || "unknown_error"
+      @title  = first["title"] || "Unknown error"
+      @detail = first["detail"]
+      @errors = errors
+      super("#{@status} #{@title}")
+    end
+  end
+
+  # Raised when pre-emit schema validation fails.
+  # No HTTP request is made — the payload was rejected locally.
+  class SchemaValidationError < Error
+    attr_reader :failures
+
+    # @param failures [Array<Hash>] array of {field:, message:} hashes
+    def initialize(failures)
+      @failures = failures
+      parts = failures.map { |f| "#{f[:field]} #{f[:message]}" }
+      super("Schema validation failed: #{parts.join('; ')}")
+    end
+  end
+
+  # Raised when a network-level failure prevents reaching the Control Plane.
+  # Retries are already exhausted before this is raised.
+  class NetworkError < Error
+    attr_reader :original_error
+
+    # @param message [String]
+    # @param original_error [Exception]
+    def initialize(message, original_error)
+      @original_error = original_error
+      super(message)
+    end
+  end
+end

data/lib/morphe_adapter_sdk/hmac.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module MorpheAdapterSdk
+  # HMAC-SHA256 signing utility.
+  #
+  # Produces the value expected by the X-Morphe-Signature header.
+  # The result is identical to the TypeScript and Python SDK sign_body
+  # implementations when both receive the same UTF-8 encoded inputs.
+  module Hmac
+    # @param body   [String] raw JSON request body (UTF-8)
+    # @param secret [String] HMAC shared secret from the API credential
+    # @return [String] 64-character lowercase hex digest
+    def self.sign(body, secret)
+      OpenSSL::HMAC.hexdigest("SHA256", secret, body)
+    end
+  end
+end

data/lib/morphe_adapter_sdk/retry.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module MorpheAdapterSdk
+  # Exponential backoff retry utility.
+  #
+  # - Configurable +max_retries+ and +base_delay+.
+  # - Jitter in [0.5, 1.5] to spread retries across clients.
+  # - Injectable +sleep_fn+ for test isolation (avoids stubbing Kernel#sleep).
+  module Retry
+    # @param max_retries [Integer] maximum retry attempts (0 = no retries)
+    # @param base_delay  [Float]   base delay in seconds before first retry
+    # @param should_retry [Proc]  predicate: returns true if the error is transient
+    # @param sleep_fn     [Proc]  injectable sleep; defaults to Kernel.method(:sleep)
+    # @yield zero-argument block to execute and retry
+    # @return the return value of the block on success
+    # @raise the last exception after all retries exhausted
+    def self.call(max_retries:, base_delay:, should_retry:, sleep_fn: nil, &block)
+      sleep_fn ||= method(:sleep)
+      attempt = 0
+
+      loop do
+        return yield
+      rescue => err
+        raise if attempt >= max_retries || !should_retry.call(err)
+
+        jitter = 0.5 + rand
+        delay  = base_delay * (2**attempt) * jitter
+        sleep_fn.call(delay)
+        attempt += 1
+      end
+    end
+  end
+end

data/lib/morphe_adapter_sdk/version.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module MorpheAdapterSdk
+  VERSION = "1.0.0"
+
+  # Default production endpoint for the Morphe Control Plane.
+  # Override via the MORPHE_ENDPOINT environment variable for development
+  # or self-hosted deployments.
+  DEFAULT_ENDPOINT = "https://api.morphe.io"
+
+  # Extract the API version segment from an event_type string.
+  #
+  # The version is the first dot-delimited part matching /^v\d+$/.
+  # Falls back to "v1" when no version segment is present.
+  #
+  # @example
+  #   MorpheAdapterSdk.extract_api_version("dataops.v1.sync_failed") # => "v1"
+  #   MorpheAdapterSdk.extract_api_version("dataops.v2.sync_failed") # => "v2"
+  #   MorpheAdapterSdk.extract_api_version("dataops.sync_failed")    # => "v1"
+  #
+  # @param event_type [String]
+  # @return [String]
+  def self.extract_api_version(event_type)
+    event_type.split(".").find { |part| part.match?(/\Av\d+\z/) } || "v1"
+  end
+end

data/lib/morphe_adapter_sdk.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "morphe_adapter_sdk/version"
+require_relative "morphe_adapter_sdk/errors"
+require_relative "morphe_adapter_sdk/hmac"
+require_relative "morphe_adapter_sdk/retry"
+require_relative "morphe_adapter_sdk/client"
+
+# MorpheAdapterSdk — Ruby adapter for emitting governance events to the
+# Morphe Control Plane.
+#
+# @example
+#   client = MorpheAdapterSdk::Client.new(token: ENV["MORPHE_TOKEN"])
+#   result = client.emit(
+#     event_type: "dataops.v1.sync_failed",
+#     system_id:  "11111111-1111-1111-1111-111111111111",
+#     payload:    { records_failed: 42 }
+#   )
+module MorpheAdapterSdk
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: morphe_adapter_sdk
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Morphe
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+description:
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/morphe_adapter_sdk.rb
+- lib/morphe_adapter_sdk/client.rb
+- lib/morphe_adapter_sdk/errors.rb
+- lib/morphe_adapter_sdk/hmac.rb
+- lib/morphe_adapter_sdk/retry.rb
+- lib/morphe_adapter_sdk/version.rb
+homepage:
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby adapter SDK for emitting events to the Morphe Control Plane
+test_files: []