activecypher 0.0.0 → 0.2.0

data/lib/active_cypher/connection_factory.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  # ConnectionFactory provides a simple API for creating connections to Cypher databases
+  # using the ConnectionUrlResolver to parse database URLs.
+  #
+  # This factory simplifies the process of creating database connections by:
+  # 1. Parsing connection URLs with ConnectionUrlResolver
+  # 2. Creating the appropriate adapter based on the URL
+  # 3. Establishing and configuring the connection with the right security settings
+  #
+  # Example:
+  #   factory = ConnectionFactory.new("neo4j://user:pass@localhost:7687")
+  #   driver = factory.create_driver
+  #
+  #   driver.with_session do |session|
+  #     result = session.run("RETURN 'Connected!' AS message")
+  #     puts result.first[:message]
+  #   end
+  class ConnectionFactory
+    # Initialize with a database URL
+    # @param url [String] A database connection URL
+    # @param options [Hash] Additional options for the connection
+    def initialize(url, options = {})
+      @url = url
+      @options = options
+      @config = resolve_url(url)
+    end
+
+    # Create a Bolt driver based on the parsed URL
+    # @param pool_size [Integer] Size of the connection pool
+    # @return [ActiveCypher::Bolt::Driver, nil] The configured driver or nil if URL is invalid
+    def create_driver(pool_size: 5)
+      return nil unless @config
+
+      # Create the adapter based on the resolved configuration
+      adapter = create_adapter
+      return nil unless adapter
+
+      # Create and configure the Bolt driver
+      uri = build_uri
+      auth_token = build_auth_token
+
+      ActiveCypher::Bolt::Driver.new(
+        uri: uri,
+        adapter: adapter,
+        auth_token: auth_token,
+        pool_size: pool_size
+      )
+    end
+
+    # Get the parsed configuration
+    # @return [Hash, nil] The parsed configuration or nil if URL is invalid
+    attr_reader :config
+
+    # Verify if the URL is valid and supported
+    # @return [Boolean] True if the URL is valid and supported
+    def valid?
+      !@config.nil?
+    end
+
+    private
+
+    # Resolve the URL into a configuration hash
+    def resolve_url(url)
+      resolver = ConnectionUrlResolver.new(url)
+      resolver.to_hash
+    end
+
+    # Create the appropriate adapter based on the parsed URL
+    def create_adapter
+      case @config[:adapter]
+      when 'neo4j'
+        create_neo4j_adapter
+      when 'memgraph'
+        create_memgraph_adapter
+      else
+        nil
+      end
+    end
+
+    # Create a Neo4j adapter
+    def create_neo4j_adapter
+      ConnectionAdapters::Neo4jAdapter.new({
+                                             uri: build_uri,
+                                             username: @config[:username],
+                                             password: @config[:password],
+                                             database: @config[:database]
+                                           })
+    end
+
+    # Create a Memgraph adapter
+    def create_memgraph_adapter
+      ConnectionAdapters::MemgraphAdapter.new({
+                                                uri: build_uri,
+                                                username: @config[:username],
+                                                password: @config[:password],
+                                                database: @config[:database]
+                                              })
+    rescue NameError
+      # Fall back to Neo4j adapter if Memgraph adapter is not available
+      ConnectionAdapters::Neo4jAdapter.new({
+                                             uri: build_uri,
+                                             username: @config[:username],
+                                             password: @config[:password],
+                                             database: @config[:database]
+                                           })
+    end
+
+    # Build the URI string with the appropriate scheme based on SSL settings
+    def build_uri
+      scheme = if @config[:ssl]
+                 @config[:ssc] ? 'bolt+ssc' : 'bolt+s'
+               else
+                 'bolt'
+               end
+
+      "#{scheme}://#{@config[:host]}:#{@config[:port]}"
+    end
+
+    # Build the authentication token for the Bolt driver
+    def build_auth_token
+      {
+        scheme: 'basic',
+        principal: @config[:username],
+        credentials: @config[:password]
+      }
+    end
+  end
+end

data/lib/active_cypher/connection_handler.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  class ConnectionHandler
+    def initialize = @role_shard_map = Hash.new { |h, k| h[k] = {} }
+    def set(role, shard, pool) = (@role_shard_map[role][shard] = pool)
+    def pool(role, shard)      = @role_shard_map.dig(role, shard)
+  end
+end

data/lib/active_cypher/connection_pool.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'concurrent/atomic/atomic_reference'
+require 'timeout'
+
+module ActiveCypher
+  class ConnectionPool
+    attr_reader :spec
+
+    def initialize(spec)
+      @spec = spec.symbolize_keys
+
+      # Set defaults for pool configuration
+      @spec[:pool_size] ||= ENV.fetch('BOLT_POOL_SIZE', 10).to_i
+      @spec[:pool_timeout] ||= ENV.fetch('BOLT_POOL_TIMEOUT', 5).to_i
+      @spec[:max_retries] ||= ENV.fetch('BOLT_MAX_RETRIES', 3).to_i
+
+      # Handle URL-based configuration if present
+      if @spec[:url] && !@spec.key?(:adapter)
+        resolver = ActiveCypher::ConnectionUrlResolver.new(@spec[:url])
+        resolved_config = resolver.to_hash
+
+        raise ArgumentError, "Invalid connection URL: #{@spec[:url]}" unless resolved_config
+
+        # Merge the resolved config with any additional options
+        @spec = resolved_config.merge(@spec.except(:url))
+
+      end
+
+      @conn_ref = Concurrent::AtomicReference.new # holds the adapter instance
+      @creation_mutex = Mutex.new # prevents multiple threads from creating connections simultaneously
+      @retry_count = Concurrent::AtomicReference.new(0)
+    end
+
+    # Returns a live adapter, initialising it once in a thread‑safe way.
+    def connection
+      # Fast path —already connected and alive
+      conn = @conn_ref.value
+      return conn if conn&.active?
+
+      # Use mutex for the slow path to prevent thundering herd
+      @creation_mutex.synchronize do
+        # Check again inside the mutex in case another thread created it
+        conn = @conn_ref.value
+        return conn if conn&.active?
+
+        # Slow path —create a new connection with retry logic
+        retries = 0
+        max_retries = @spec[:max_retries]
+
+        begin
+          new_conn = build_connection
+          @conn_ref.set(new_conn)
+          @retry_count.set(0) # Reset retry count on success
+          return new_conn
+        rescue StandardError => e
+          retries += 1
+          if retries <= max_retries
+            # Exponential backoff
+            sleep_time = 0.1 * (2**(retries - 1))
+            sleep(sleep_time)
+            retry
+          else
+            # Track persistent failures
+            @retry_count.update { |count| count + 1 }
+            raise ConnectionError, "Failed to establish connection after #{max_retries} attempts: #{e.message}"
+          end
+        end
+      end
+    end
+    alias checkout connection
+
+    # Check if the pool has a persistent connection issue
+    def troubled?
+      @retry_count.value >= @spec[:max_retries]
+    end
+
+    # Explicitly close and reset the connection
+    def disconnect
+      conn = @conn_ref.value
+      return unless conn
+
+      begin
+        conn.disconnect
+      rescue StandardError => e
+        # Log but don't raise to ensure cleanup continues
+        puts "Warning: Error disconnecting: #{e.message}" if ENV['DEBUG']
+      ensure
+        @conn_ref.set(nil)
+      end
+    end
+
+    private
+
+    def build_connection
+      adapter_name = @spec[:adapter]
+      raise ArgumentError, 'Missing adapter name in connection specification' unless adapter_name
+
+      adapter_class = ActiveCypher::ConnectionAdapters
+                      .const_get("#{adapter_name}_adapter".camelize)
+
+      adapter = adapter_class.new(@spec)
+
+      # Use timeout to avoid hanging during connection
+      begin
+        Timeout.timeout(@spec[:pool_timeout]) do
+          adapter.connect
+        end
+      rescue Timeout::Error
+        begin
+          adapter.disconnect
+        rescue StandardError
+          nil
+        end
+        raise ConnectionError, "Connection timed out after #{@spec[:pool_timeout]} seconds"
+      end
+
+      adapter
+    rescue NameError
+      raise ActiveCypher::AdapterNotFoundError, "Could not find adapter class for '#{adapter_name}'"
+    end
+  end
+end

data/lib/active_cypher/connection_url_resolver.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'cgi'
+
+module ActiveCypher
+  # ConnectionUrlResolver accepts Cypher-based database URLs and converts them
+  # into a normalized configuration hash for adapter resolution.
+  #
+  # Supported URL prefixes:
+  # - neo4j://
+  # - neo4j+ssl://
+  # - neo4j+ssc://
+  # - memgraph://
+  # - memgraph+ssl://
+  # - memgraph+ssc://
+  #
+  # The output of to_hash follows a consistent pattern:
+  # {
+  #   adapter: "neo4j", # or "memgraph"
+  #   username: "user",
+  #   password: "pass",
+  #   host: "localhost",
+  #   port: 7687,
+  #   database: nil, # or optional
+  #   ssl: true,
+  #   ssc: false,
+  #   options: {} # future-proof for params like '?timeout=30'
+  # }
+  class ConnectionUrlResolver
+    SUPPORTED_ADAPTERS = %w[neo4j memgraph].freeze
+    DEFAULT_PORT = 7687
+
+    # Initialize with a URL string
+    # @param url_string [String] A connection URL string
+    def initialize(url_string)
+      @url_string = url_string
+      @parsed = parse_url(url_string)
+    end
+
+    # Convert the URL to a normalized hash configuration
+    # @return [Hash] Configuration hash with adapter, host, port, etc.
+    def to_hash
+      return nil unless @parsed
+
+      {
+        adapter: @parsed[:adapter],
+        host: @parsed[:host],
+        port: @parsed[:port],
+        username: @parsed[:username],
+        password: @parsed[:password],
+        database: @parsed[:database],
+        ssl: @parsed[:ssl],
+        ssc: @parsed[:ssc],
+        options: @parsed[:options]
+      }
+    end
+
+    private
+
+    def parse_url(url_string)
+      return nil if url_string.nil? || url_string.empty?
+
+      # Extract scheme and potential modifiers (ssl, ssc)
+      scheme_parts = url_string.split('://', 2)
+      return nil if scheme_parts.size != 2
+
+      scheme = scheme_parts[0]
+      rest = scheme_parts[1].to_s
+
+      adapter, modifiers = extract_adapter_and_modifiers(scheme)
+      return nil unless adapter
+
+      # Parse the remaining part as a standard URI
+      uri_string = "#{adapter}://#{rest}"
+      begin
+        uri = URI.parse(uri_string)
+      rescue URI::InvalidURIError
+        return nil
+      end
+
+      # Extract query parameters, if any
+      options = extract_query_params(uri.query)
+
+      # Extract database from path, if present
+      database = uri.path.empty? ? nil : uri.path.sub(%r{^/}, '')
+      database = nil if database&.empty?
+
+      # The to_s conversion handles nil values
+      username = uri.user.to_s.empty? ? nil : CGI.unescape(uri.user)
+      password = uri.password.to_s.empty? ? nil : CGI.unescape(uri.password)
+
+      # When using SSC (self-signed certificates), SSL must also be enabled
+      use_ssl = modifiers.include?('ssl')
+      use_ssc = modifiers.include?('ssc')
+
+      # Self-signed certificates imply SSL is also enabled
+      use_ssl = true if use_ssc
+
+      {
+        adapter: adapter,
+        host: uri.host || 'localhost',
+        port: uri.port || DEFAULT_PORT,
+        username: username,
+        password: password,
+        database: database,
+        ssl: use_ssl,
+        ssc: use_ssc,
+        options: options
+      }
+    end
+
+    def extract_adapter_and_modifiers(scheme)
+      parts = scheme.split('+')
+      adapter = parts.shift
+
+      return nil unless SUPPORTED_ADAPTERS.include?(adapter)
+
+      modifiers = parts.select { |mod| %w[ssl ssc].include?(mod) }
+
+      # If there are parts that are neither the adapter nor valid modifiers, the URL is invalid
+      remaining_parts = parts - modifiers
+      return nil if remaining_parts.any?
+
+      [adapter, modifiers]
+    end
+
+    def extract_query_params(query_string)
+      return {} unless query_string
+
+      query_string.split('&').each_with_object({}) do |pair, hash|
+        key, value = pair.split('=', 2)
+        hash[key.to_sym] = value if key && !key.empty? && value && !value.empty?
+      end
+    end
+  end
+end

data/lib/active_cypher/cypher_config.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# lib/active_cypher/cypher_config.rb
+require 'active_support'
+
+module ActiveCypher
+  module CypherConfig
+    #
+    # Read config/cypher_databases.yml the Rails‑native way and then
+    # pick a *named connection* (default :primary).
+    #
+    # Works **outside** Rails too by falling back to ActiveSupport::ConfigurationFile.
+    #
+    def self.for(name = :primary, env: nil, path: nil)
+      env  ||= defined?(Rails) ? Rails.env : ENV.fetch('CY_ENV', 'development')
+      file   = Pathname.new(path || default_path)
+
+      ## ------------------------------------------------------------
+      ## 1. Parse YAML using the same algorithm Rails::Application#config_for
+      ##    uses (shared‑section merge, ERB, symbolize_keys, etc.)
+      ## ------------------------------------------------------------
+      merged =
+        if defined?(Rails::Application)
+          # Leverage the very method you pasted:
+          Rails.application.config_for(file, env: env).deep_dup
+        else
+          # Stand‑alone Ruby script: replicate the merge rules.
+          raw     = ActiveSupport::ConfigurationFile.parse(file).deep_symbolize_keys
+          config  = raw[env.to_sym] || {}
+          shared  = raw[:shared]    || {}
+          shared.deep_merge(config)
+        end
+
+      return merged.with_indifferent_access if name.to_s == '*'
+
+      merged.fetch(name.to_sym) do
+        raise KeyError,
+              "No '#{name}' connection in #{env} section of #{file}"
+      end.with_indifferent_access
+    end
+
+    def self.default_path
+      if defined?(Rails)
+        Rails.root.join('config', 'cypher_databases.yml')
+      else
+        File.join(Dir.pwd, 'config', 'cypher_databases.yml')
+      end
+    end
+  end
+end

data/lib/active_cypher/generators/install_generator.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module ActiveCypher
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc 'Creates cypher_databases.yml and an initializer for ActiveCypher'
+
+      source_root File.expand_path('templates', __dir__)
+
+      def copy_configuration
+        template 'cypher_databases.yml', 'config/cypher_databases.yml'
+      end
+
+      def copy_base_classes
+        empty_directory 'app/graph'
+        template 'application_graph_node.rb',         'app/graph/application_graph_node.rb'
+        template 'application_graph_relationship.rb', 'app/graph/application_graph_relationship.rb'
+      end
+    end
+  end
+end

data/lib/active_cypher/generators/node_generator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'rails/generators/active_model'
+require 'rails/generators/named_base'
+
+module ActiveCypher
+  module Generators
+    class NodeGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      argument :attributes, type: :array,
+                            default: [], banner: 'name:type name:type'
+
+      class_option :labels, type: :string,
+                            desc: 'Comma‑separated Cypher labels',
+                            default: ''
+
+      def create_node_file
+        template 'node.rb.erb',
+                 File.join('app/graph', class_path, "#{file_name}.rb")
+      end
+
+      private
+
+      # helper for ERB
+      def labels_list
+        lbls = options[:labels].split(',').map(&:strip).reject(&:blank?)
+        lbls.empty? ? [class_name.gsub(/Node$/, '')] : lbls
+      end
+    end
+  end
+end

data/lib/active_cypher/generators/relationship_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'rails/generators/active_model'
+require 'rails/generators/named_base'
+
+module ActiveCypher
+  module Generators
+    class RelationshipGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      argument :attributes, type: :array,
+                            default: [], banner: 'name:type name:type'
+
+      class_option :from,  type: :string, required: true,
+                           desc: 'Source node class (e.g. UserNode)'
+      class_option :to,    type: :string, required: true,
+                           desc: 'Target node class (e.g. CompanyNode)'
+      class_option :type,  type: :string, default: '',
+                           desc: 'Cypher relationship type (defaults to class name)'
+
+      def create_relationship_file
+        template 'relationship.rb.erb',
+                 File.join('app/graph', class_path, "#{file_name}.rb")
+      end
+
+      private
+
+      def relationship_type
+        (options[:type].presence || class_name).upcase
+      end
+    end
+  end
+end

data/lib/active_cypher/generators/templates/application_graph_node.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class ApplicationGraphNode < ActiveCypher::Base
+  # Adapter‑specific helpers are injected after connection
+end

data/lib/active_cypher/generators/templates/application_graph_relationship.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class ApplicationGraphRelationship < ActiveCypher::Relationship
+  # Relationship‑level helpers or callbacks go here
+end

data/lib/active_cypher/generators/templates/cypher_databases.yml

@@ -0,0 +1,28 @@
+shared:
+  ssl: false  # Because encryption is for people who deploy to the public internet on purpose
+
+development:
+  primary: &local_memgraph
+      adapter: neo4j  # Because you like your graphs with a touch of existential dread
+      uri: neo4j://localhost:7687  # Port 7687: also known as Neo4j’s VIP lounge
+      username: neo4j  # Default username because who has time for originality
+      password: neo4j  # Seriously. Change this. Right now. I can see you not doing it.
+      multi_db: false  # One DB to rule them all, because multiple would involve effort
+
+test:
+  primary:
+    <<: *local_memgraph   # Reusing the dev config like a true copy-paste warrior
+    uri: bolt://localhost:9876  # Different port, same chaos
+
+production:
+  primary:
+    adapter:  memgraph  # Yes, it’s still memgraph... for now...
+    uri: bolt+s://<%= ENV["MG_HOST"] %>:7687  # Now with SSL, because prod gets the good stuff
+    username: <%= ENV["MG_USER"] %>  # You should probably not hardcode "admin"
+    password: <%= ENV["MG_PASS"] %>  # Hopefully not "password123"
+    ssl: true  # SSL: Because “oops, we got hacked” is a bad press release
+    multi_db: <%= ENV.fetch("MG_MULTI_DB", "false") %>  # Default is "false" because complexity is scary and licensing is expensive
+
+# Bonus content:
+# Neo4j used to run prod but got demoted when Memgraph bought us lunch
+# RIP Neo4j: gone but not forgotten... mostly because we still pay for the license

data/lib/active_cypher/generators/templates/node.rb.erb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+class <%= class_name %> < ApplicationGraphNode
+  <% labels_list.each do |lbl| %>
+  label :<%= lbl %>
+    <% end %>
+
+    <% attributes.each do |attr| -%>
+    attribute :<%= attr.name %>, :<%= attr.type || "string" %>
+  <% end -%>
+end

data/lib/active_cypher/generators/templates/relationship.rb.erb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < ApplicationGraphRelationship
+  from_class :<%= options[:from] %>
+    to_class   :<%= options[:to]   %>
+    type       :<%= relationship_type %>
+
+    <% attributes.each do |attr| -%>
+    attribute :<%= attr.name %>, :<%= attr.type || "string" %>
+  <% end -%>
+end

data/lib/active_cypher/logging.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'active_support/tagged_logging'
+
+module ActiveCypher
+  module Logging
+    class << self
+      # The one true logger object
+      attr_accessor :backend
+
+      # Public accessor used by the mix‑in
+      def logger
+        self.backend ||= begin
+          base = Logger.new($stdout)
+          base.level = ENV.fetch('AC_LOG_LEVEL', 'info').upcase
+                          .then do |lvl|
+            Logger.const_get(lvl)
+          rescue StandardError
+            Logger::INFO
+          end
+          ActiveSupport::TaggedLogging.new(base).tap { |l| l.tagged! 'ActiveCypher' }
+        end
+      end
+    end
+
+    # ------------------------------------------------------------------
+    #  Instance helpers
+    # ------------------------------------------------------------------
+    def logger         = Logging.logger
+    def log_debug(msg) = logger.debug { msg }
+    def log_info(msg)  = logger.info  { msg }
+    def log_warn(msg)  = logger.warn  { msg }
+    def log_error(msg) = logger.error { msg }
+
+    def log_bench(label)
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      yield
+    ensure
+      ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1_000).round(2)
+      logger.debug { "#{label} (#{ms} ms)" }
+    end
+  end
+end