active_chronicle 0.1.0

data/lib/chronicle/resilience.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'mutex_m'
+
+module Chronicle
+  module Resilience
+    class CircuitBreaker
+      attr_reader :state, :failure_count, :opened_at
+
+      def initialize(threshold: nil, cooldown: nil)
+        @mutex = Mutex.new
+        @state = :closed
+        @failure_count = 0
+        @opened_at = nil
+        @threshold = threshold
+        @cooldown = cooldown
+      end
+
+      def threshold
+        @threshold || (Chronicle.configuration ? Chronicle.configuration.circuit_breaker_threshold : 5)
+      end
+
+      def cooldown
+        @cooldown || (Chronicle.configuration ? Chronicle.configuration.circuit_breaker_cooldown : 10.0)
+      end
+
+      def check_state!
+        @mutex.synchronize do
+          case @state
+          when :open
+            if Time.now - @opened_at >= cooldown
+              @state = :half_open
+            else
+              raise Chronicle::CircuitBreakerError,
+                    "Circuit breaker is OPEN. Datomic Transactor requests failing fast (opened at #{@opened_at})."
+            end
+          when :half_open, :closed
+            # Allow execution
+          end
+        end
+      end
+
+      def record_success
+        @mutex.synchronize do
+          @failure_count = 0
+          @state = :closed
+          @opened_at = nil
+        end
+      end
+
+      def record_failure
+        @mutex.synchronize do
+          @failure_count += 1
+          if @failure_count >= threshold || @state == :half_open
+            @state = :open
+            @opened_at = Time.now
+          end
+        end
+      end
+
+      def reset!
+        @mutex.synchronize do
+          @state = :closed
+          @failure_count = 0
+          @opened_at = nil
+        end
+      end
+
+      def force_open!
+        @mutex.synchronize do
+          @state = :open
+          @opened_at = Time.now
+        end
+      end
+    end
+
+    class << self
+      def global_circuit_breaker
+        @global_circuit_breaker ||= CircuitBreaker.new
+      end
+
+      def reset_circuit_breaker!
+        global_circuit_breaker.reset!
+      end
+
+      def retryable_exceptions
+        @retryable_exceptions ||= [
+          Chronicle::ConnectionError,
+          Chronicle::TransactionError,
+          Faraday::TimeoutError,
+          Faraday::ConnectionFailed,
+          Errno::ECONNREFUSED,
+          Errno::ETIMEDOUT
+        ]
+      end
+
+      def with_retry(max_retries: nil, base_delay: nil, max_delay: nil, circuit_breaker: nil)
+        nested_retry = Thread.current[:chronicle_retry_depth].to_i.positive?
+        cb = circuit_breaker || (nested_retry ? CircuitBreaker.new : global_circuit_breaker)
+        config = Chronicle.configuration
+
+        retries = max_retries || (config ? config.max_retries : 5)
+        delay   = base_delay   || (config ? config.retry_base_delay : 0.1)
+        max_d   = max_delay    || (config ? config.retry_max_delay : 2.0)
+
+        begin
+          Thread.current[:chronicle_retry_depth] = Thread.current[:chronicle_retry_depth].to_i + 1
+          cb.check_state!
+
+          attempt = 0
+          begin
+            attempt += 1
+            result = yield
+            cb.record_success
+            result
+          rescue StandardError => e
+            if retryable?(e)
+              cb.record_failure
+              if attempt <= retries
+                sleep_time = [delay * (2**(attempt - 1)), max_d].min
+                jitter = rand(0.0..0.1) * sleep_time
+                sleep_backoff(sleep_time + jitter)
+                retry
+              end
+            end
+            raise e
+          end
+        ensure
+          Thread.current[:chronicle_retry_depth] -= 1
+        end
+      end
+
+      def sleep_backoff(duration)
+        if defined?(Fiber) && Fiber.respond_to?(:scheduler) && Fiber.scheduler
+          Fiber.scheduler.kernel_sleep(duration)
+        else
+          sleep(duration)
+        end
+      end
+
+      private
+
+      def retryable?(exception)
+        retryable_exceptions.any? { |klass| exception.is_a?(klass) } ||
+          exception.message.to_s.match?(/transactor-unavailable|queue-full|backpressure|timeout/i)
+      end
+    end
+  end
+end

data/lib/chronicle/schema/table_definition.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Chronicle
+  class Schema
+    class TableDefinition
+      attr_reader :entity_name, :attributes
+
+      TYPE_MAPPINGS = {
+        string: 'string',
+        integer: 'long',
+        bigint: 'long',
+        float: 'double',
+        boolean: 'boolean',
+        datetime: 'instant',
+        ref: 'ref',
+        uuid: 'uuid',
+        bytes: 'bytes',
+        uri: 'uri'
+      }.freeze
+
+      def initialize(entity_name)
+        @entity_name = entity_name.to_s.singularize
+        @attributes = []
+      end
+
+      def string(name, **)
+        add_attribute(name, :string, **)
+      end
+
+      def integer(name, **)
+        add_attribute(name, :integer, **)
+      end
+
+      def bigint(name, **)
+        add_attribute(name, :bigint, **)
+      end
+
+      def float(name, **)
+        add_attribute(name, :float, **)
+      end
+
+      def boolean(name, **)
+        add_attribute(name, :boolean, **)
+      end
+
+      def datetime(name, **)
+        add_attribute(name, :datetime, **)
+      end
+
+      def ref(name, **)
+        add_attribute(name, :ref, **)
+      end
+
+      def uuid(name, **)
+        add_attribute(name, :uuid, **)
+      end
+
+      def timestamps
+        datetime(:created_at)
+        datetime(:updated_at)
+      end
+
+      def to_datoms
+        @attributes.map do |attr|
+          datomic_type = TYPE_MAPPINGS[attr[:type]] || 'string'
+          cardinality = attr[:options][:cardinality] == :many || attr[:options][:array] ? ':db.cardinality/many' : ':db.cardinality/one'
+
+          datom = {
+            ':db/ident' => ":#{@entity_name}/#{attr[:name]}",
+            ':db/valueType' => ":db.type/#{datomic_type}",
+            ':db/cardinality' => cardinality
+          }
+
+          if attr[:options][:unique] == :identity
+            datom[':db/unique'] = ':db.unique/identity'
+          elsif attr[:options][:unique] == :value
+            datom[':db/unique'] = ':db.unique/value'
+          end
+
+          datom[':db/index'] = true if attr[:options][:index]
+          datom[':db/doc'] = attr[:options][:doc] if attr[:options][:doc]
+          datom
+        end
+      end
+
+      private
+
+      def add_attribute(name, type, **options)
+        @attributes << { name:, type:, options: }
+      end
+    end
+  end
+end

data/lib/chronicle/schema.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative 'schema/table_definition'
+
+module Chronicle
+  class Schema
+    class << self
+      def create_attribute(entity_name, attribute_name, value_type, options = {})
+        ident = ":#{entity_name.to_s.underscore}/#{attribute_name}"
+        cardinality = options[:cardinality] == :many ? ':db.cardinality/many' : ':db.cardinality/one'
+        type_str = ":db.type/#{value_type}"
+
+        schema_datom = {
+          ':db/ident' => ident,
+          ':db/valueType' => type_str,
+          ':db/cardinality' => cardinality
+        }
+
+        schema_datom[':db/unique'] = ':db.unique/identity' if options[:unique] == :identity
+        schema_datom[':db/doc'] = options[:doc] if options[:doc]
+
+        schema_datom
+      end
+
+      def define(entity_name)
+        table_def = TableDefinition.new(entity_name)
+        yield(table_def) if block_given?
+        table_def.to_datoms
+      end
+
+      def drop_attribute_datom(entity_name, attribute_name, timestamp = Time.now.strftime('%Y%m%d%H%M%S'))
+        old_ident = ":#{entity_name.to_s.underscore}/#{attribute_name}"
+        new_ident = ":deprecated.#{entity_name.to_s.underscore}.#{timestamp}/#{attribute_name}"
+
+        {
+          ':db/id' => old_ident,
+          ':db/ident' => new_ident,
+          ':db/doc' => "DEPRECATED and dropped via Chronicle migration at #{timestamp}"
+        }
+      end
+
+      def deprecate_attribute_datom(entity_name, attribute_name, reason: 'Deprecated in migration')
+        ident = ":#{entity_name.to_s.underscore}/#{attribute_name}"
+        {
+          ':db/id' => ident,
+          ':db/doc' => "DEPRECATED: #{reason}"
+        }
+      end
+
+      def rename_attribute_datom(entity_name, old_name, new_name)
+        old_ident = ":#{entity_name.to_s.underscore}/#{old_name}"
+        new_ident = ":#{entity_name.to_s.underscore}/#{new_name}"
+
+        {
+          ':db/id' => old_ident,
+          ':db/ident' => new_ident
+        }
+      end
+    end
+  end
+
+  module MigrationExtension
+    def create_datomic_schema(entity_name, &)
+      datoms = Chronicle::Schema.define(entity_name, &)
+      transport = Chronicle::Transport.client
+      transport.transact(datoms)
+    end
+
+    def drop_datomic_attribute(entity_name, attribute_name)
+      datom = Chronicle::Schema.drop_attribute_datom(entity_name, attribute_name)
+      transport = Chronicle::Transport.client
+      transport.transact([datom])
+    end
+
+    def deprecate_datomic_attribute(entity_name, attribute_name, reason: 'Deprecated')
+      datom = Chronicle::Schema.deprecate_attribute_datom(entity_name, attribute_name, reason:)
+      transport = Chronicle::Transport.client
+      transport.transact([datom])
+    end
+
+    def rename_datomic_attribute(entity_name, old_name, new_name)
+      datom = Chronicle::Schema.rename_attribute_datom(entity_name, old_name, new_name)
+      transport = Chronicle::Transport.client
+      transport.transact([datom])
+    end
+  end
+end
+
+ActiveRecord::Migration.include(Chronicle::MigrationExtension) if defined?(ActiveRecord::Migration)

data/lib/chronicle/transaction_coordinator.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Chronicle
+  class TransactionCoordinator
+    attr_reader :basis_t, :tx_id, :transport, :transacted_datoms, :created_entity_ids, :datomic_result
+
+    class << self
+      def transact(transport: nil, &)
+        new(transport:).transact(&)
+      end
+    end
+
+    def initialize(transport: nil)
+      @transport = transport || Chronicle::Transport.client
+      @transacted_datoms = []
+      @created_entity_ids = []
+      @basis_t = nil
+      @tx_id = nil
+      @datomic_result = nil
+    end
+
+    def transact
+      yield(self)
+      self
+    rescue StandardError => e
+      rollback!(e)
+    end
+
+    def datomic(datoms_or_model)
+      datoms = convert_to_datoms(datoms_or_model)
+      @transacted_datoms.concat(datoms)
+
+      @datomic_result = @transport.transact(datoms) || {}
+
+      @basis_t = @datomic_result[:basis_t] || @datomic_result['basis_t'] || Time.now.to_i
+      @tx_id = @datomic_result[:tx_id] || @datomic_result['tx_id'] || @basis_t
+
+      @created_entity_ids.concat(@datomic_result[:tempids].values) if @datomic_result[:tempids]
+
+      datoms.each do |d|
+        @created_entity_ids << d[1] if d.is_a?(Array) && d[1].is_a?(Numeric)
+      end
+      @created_entity_ids.uniq!
+
+      @datomic_result
+    end
+
+    def postgres
+      raise Chronicle::TransactionError, 'No Datomic transaction has been executed yet' unless @basis_t
+
+      if defined?(ActiveRecord::Base)
+        ActiveRecord::Base.transaction do
+          yield(self)
+        end
+      else
+        yield(self)
+      end
+    end
+
+    alias sqlite postgres
+    alias relational postgres
+
+    def read_your_own_write(model_class, finder_attributes = {})
+      raise Chronicle::TransactionError, 'No basis-t available for read-your-own-write' unless @basis_t
+
+      model_class.as_of(@basis_t).where(finder_attributes)
+    end
+
+    private
+
+    def convert_to_datoms(datoms_or_model)
+      if datoms_or_model.respond_to?(:to_datoms)
+        datoms_or_model.to_datoms
+      elsif datoms_or_model.is_a?(Array)
+        datoms_or_model
+      else
+        raise ArgumentError, 'Expected datoms array or an object responding to #to_datoms'
+      end
+    end
+
+    def rollback!(cause)
+      execute_compensating_retraction if @datomic_result && (@created_entity_ids.any? || @transacted_datoms.any?)
+
+      raise Chronicle::TransactionError, "Cross-database transaction rolled back due to: #{cause.message}"
+    end
+
+    def execute_compensating_retraction
+      retraction_datoms = @created_entity_ids.map do |eid|
+        [':db/retractEntity', eid]
+      end
+
+      if retraction_datoms.empty?
+        @transacted_datoms.each do |datom|
+          retraction_datoms << [':db/retract', datom[1], datom[2], datom[3]] if datom.is_a?(Array) && datom[0] == ':db/add'
+        end
+      end
+
+      @transport.transact(retraction_datoms) if retraction_datoms.any?
+    rescue StandardError => e
+      warn("[Chronicle] Compensating rollback failed: #{e.message}")
+    end
+  end
+end

data/lib/chronicle/transport/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Chronicle
+  module Transport
+    class Base
+      attr_reader :config
+
+      def initialize(config = {})
+        @config = config
+      end
+
+      def connect!
+        raise NotImplementedError, "#{self.class}#connect! must be implemented"
+      end
+
+      def transact(tx_data)
+        raise NotImplementedError, "#{self.class}#transact must be implemented"
+      end
+
+      def q(query, *args)
+        raise NotImplementedError, "#{self.class}#q must be implemented"
+      end
+
+      def db(as_of: nil, since: nil)
+        raise NotImplementedError, "#{self.class}#db must be implemented"
+      end
+
+      def basis_t
+        raise NotImplementedError, "#{self.class}#basis_t must be implemented"
+      end
+    end
+  end
+end

data/lib/chronicle/transport/cruby_client.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require 'time'
+require 'uri'
+
+Object.const_set('Bignum', Integer) unless Object.const_defined?('Bignum')
+require 'edn'
+
+module Chronicle
+  module Transport
+    class CRubyClient < Base
+      attr_reader :connection, :current_basis_t
+
+      def initialize(config = {})
+        super
+        @endpoint = config[:client_endpoint] || config['client_endpoint'] || ENV.fetch('DATOMIC_CLIENT_ENDPOINT', 'http://localhost:8989')
+        @uri = config[:uri] || config['uri'] || ENV.fetch('DATOMIC_URI', nil)
+        @rest = config[:rest] || config['rest']
+        @storage_alias, @database_name = parse_datomic_uri(@uri) if @rest
+        connection_options = { url: @endpoint }
+        connection_options[:ssl] = { verify: false } if @endpoint.start_with?('https://') && config.fetch(:verify_ssl, false) == false
+        @connection = Faraday.new(**connection_options) do |f|
+          f.request :json
+          f.response :json
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      def connect!
+        if @rest
+          result = rest_connect!
+          @connected = true
+          return result
+        end
+
+        Chronicle::Resilience.with_retry do
+          response = @connection.post('/api/connect', { uri: @uri })
+          raise Chronicle::ConnectionError, "Failed to connect to Datomic Client HTTP API at #{@endpoint}" unless response.success?
+
+          @connected = true
+          true
+        end
+      end
+
+      def connected?
+        !!@connected
+      end
+
+      def disconnect!
+        @connected = false
+      end
+
+      def transact(tx_data)
+        return rest_transact(tx_data) if @rest
+
+        Chronicle::Resilience.with_retry do
+          payload = { uri: @uri, tx_data: }
+          response = @connection.post('/api/transact', payload)
+          raise Chronicle::TransactionError, "Datomic Transact Error: #{response.body}" unless response.success?
+
+          body = response.body
+          @current_basis_t = body['basis_t'] || body['db_after_t']
+          { db_before: body['db_before'], db_after: body['db_after'], tx_data: body['tx_data'],
+            basis_t: @current_basis_t }
+        end
+      end
+
+      def q(query, *args)
+        return rest_query(query, *args) if @rest
+
+        Chronicle::Resilience.with_retry do
+          payload = { uri: @uri, query:, args: }
+          response = @connection.post('/api/query', payload)
+          raise Chronicle::Error, "Datomic Query Error: #{response.body}" unless response.success?
+
+          response.body['results'] || []
+        end
+      end
+
+      def db(as_of: nil, since: nil)
+        if @rest
+          database = { 'db/alias' => "#{@storage_alias}/#{@database_name}" }
+          database['as-of'] = as_of if as_of
+          database['since'] = since if since
+          return database
+        end
+
+        { uri: @uri, as_of:, since:, basis_t: @current_basis_t }
+      end
+
+      def basis_t
+        @current_basis_t || 0
+      end
+
+      private
+
+      def parse_datomic_uri(uri)
+        match = uri.to_s.match(%r{\Adatomic:([^:]+)://[^/]+/(.+)\z})
+        raise ArgumentError, "Invalid Datomic URI: #{uri}" unless match
+
+        match.captures
+      end
+
+      def rest_connect!
+        Chronicle::Resilience.with_retry do
+          response = @connection.post("/data/#{@storage_alias}/") do |request|
+            request.headers['Content-Type'] = 'application/edn'
+            request.headers['Accept'] = 'application/edn'
+            request.body = edn('db-name' => @database_name)
+          end
+          raise Chronicle::ConnectionError, "Failed to connect to Datomic REST API at #{@endpoint}" unless response.success?
+
+          true
+        end
+      end
+
+      def rest_transact(tx_data)
+        Chronicle::Resilience.with_retry do
+          response = @connection.post("/data/#{@storage_alias}/#{@database_name}/") do |request|
+            request.headers['Content-Type'] = 'application/edn'
+            request.headers['Accept'] = 'application/edn'
+            request.body = edn('tx-data' => tx_data)
+          end
+          raise Chronicle::TransactionError, "Datomic REST transaction failed: #{response.body}" unless response.success?
+
+          parsed = EDN.read(response.body)
+          @current_basis_t = parsed.dig('db-after', 'basis-t')
+          parsed
+        end
+      end
+
+      def rest_query(query, *args)
+        Chronicle::Resilience.with_retry do
+          response = @connection.post('/api/query') do |request|
+            request.headers['Content-Type'] = 'application/edn'
+            request.headers['Accept'] = 'application/edn'
+            request.body = edn(q: query, args:)
+          end
+          raise Chronicle::Error, "Datomic REST query failed: #{response.body}" unless response.success?
+
+          EDN.read(response.body)
+        end
+      end
+
+      def edn(value)
+        case value
+        when Hash
+          "{#{value.map { |key, item| "#{edn_key(key)} #{edn(item)}" }.join(' ')}}"
+        when Array
+          return "(#{value.map { |item| edn(item) }.join(' ')})" if value.first == :pull
+
+          "[#{value.map { |item| edn(item) }.join(' ')}]"
+        when Symbol
+          return 'pull' if value == :pull
+
+          value.to_s.start_with?(':') ? value.to_s : ":#{value}"
+        when String
+          return '*' if value == '*'
+
+          value.match?(/\A(?:\?|\$|\.\.\.)/) ? value : JSON.generate(value)
+        when NilClass
+          'nil'
+        when Time
+          "#inst #{JSON.generate(value.utc.iso8601(3))}"
+        when TrueClass, FalseClass, Numeric
+          value.to_s
+        else
+          JSON.generate(value.to_s)
+        end
+      end
+
+      def edn_key(key)
+        key_string = key.to_s
+        key_string.start_with?(':') ? key_string : ":#{key_string}"
+      end
+    end
+  end
+end