rdbr 0.1.0

data/lib/rdbr/metadata/relationship_inference.rb

@@ -0,0 +1,75 @@
+require 'active_support/inflector'
+
+module RDBr
+  module Metadata
+    module RelationshipInference
+      INTEGER_TYPES = %i[bigint int2 int4 int8 integer oid smallint].freeze
+
+      private
+
+      def inferred_relationship_candidates(source_namespaces = namespaces)
+        source_namespaces.flat_map do |source_namespace|
+          source_namespace.relations.flat_map do |source_relation|
+            inferred_foreign_keys(source_namespace, source_relation).map do |foreign_key|
+              [ source_namespace, source_relation, foreign_key, true ]
+            end
+          end
+        end
+      end
+
+      def inferred_foreign_keys(source_namespace, source_relation)
+        matches = source_relation.columns.to_h do |column|
+          [ column, inferred_targets(source_namespace, source_relation, column) ]
+        end
+        matches.filter_map do |column, targets|
+          next unless targets.one?
+
+          inferred_foreign_key(source_namespace, column, targets.first)
+        end
+      end
+
+      def inferred_targets(namespace, source_relation, column)
+        return [] if source_relation.foreign_keys.any?{|foreign_key| foreign_key.columns.include?(column.name) }
+
+        namespace.relations.select do |target|
+          target_key = target.primary_key
+          next false unless target_key&.columns&.one?
+          next false unless inferred_column_names(target.name).include?(column.name)
+
+          target_column = target.column(target_key.columns.first)
+          target_column && compatible_relationship_types?(column, target_column)
+        end
+      end
+
+      def inferred_foreign_key(namespace, column, target)
+        ForeignKey.new(
+          columns: [ column.name ], referenced_namespace: namespace.name, referenced_relation: target.name,
+          referenced_columns: target.primary_key.columns
+        )
+      end
+
+      def inferred_column_names(relation_name)
+        singular = ActiveSupport::Inflector.singularize(relation_name)
+        snake = ActiveSupport::Inflector.underscore(singular)
+        camel = ActiveSupport::Inflector.camelize(snake, false)
+        pascal = ActiveSupport::Inflector.camelize(snake)
+        [ snake, "#{snake}_id", camel, "#{camel}Id", pascal, "#{pascal}Id" ]
+      end
+
+      def compatible_relationship_types?(source, target)
+        if source.logical_type && target.logical_type
+          return true if integer_relationship_types?(source.logical_type, target.logical_type)
+
+          return source.logical_type == target.logical_type
+        end
+        return source.sql_type.casecmp?(target.sql_type) if source.sql_type && target.sql_type
+
+        false
+      end
+
+      def integer_relationship_types?(source_type, target_type)
+        INTEGER_TYPES.include?(source_type.to_sym) && INTEGER_TYPES.include?(target_type.to_sym)
+      end
+    end
+  end
+end

data/lib/rdbr/metadata/relationships.rb

@@ -0,0 +1,126 @@
+module RDBr
+  module Metadata
+    DirectRelationship = Data.define(
+      :source_namespace, :source_relation, :target_namespace, :target_relation, :foreign_key, :inferred
+    )
+    ThroughRelationship = Data.define(
+      :source_namespace, :source_relation, :target_namespace, :target_relation,
+      :junction_namespace, :junction_relation, :source_foreign_key, :target_foreign_key, :inferred
+    )
+
+    module Relationships
+      include RelationshipInference
+
+      def outgoing_relationships(namespace, relation)
+        relationship_candidates.filter_map do |source_namespace, source_relation, foreign_key, inferred|
+          next unless source_namespace == namespace && source_relation == relation
+
+          direct_relationship(source_namespace, source_relation, foreign_key, inferred)
+        end.freeze
+      end
+
+      def incoming_relationships(namespace, relation)
+        relationship_candidates.filter_map do |source_namespace, source_relation, foreign_key, inferred|
+          next unless reference_matches?(source_namespace, foreign_key, namespace, relation)
+
+          DirectRelationship.new(
+            source_namespace: source_namespace, source_relation: source_relation,
+            target_namespace: namespace, target_relation: relation, foreign_key: foreign_key, inferred: inferred
+          )
+        end.freeze
+      end
+
+      def through_relationships(namespace, relation)
+        relationship_candidates.filter_map do |junction_namespace, junction_relation, source_foreign_key, inferred|
+          next unless reference_matches?(junction_namespace, source_foreign_key, namespace, relation)
+
+          through_relationships_from(
+            junction_namespace, junction_relation, source_foreign_key, namespace, relation, inferred
+          )
+        end.flatten.freeze
+      end
+
+      private
+
+      def relationship_candidates
+        @relationship_candidates || build_relationship_candidates(namespaces)
+      end
+
+      def build_relationship_candidates(source_namespaces)
+        declared = source_namespaces.flat_map do |namespace|
+          namespace.relations.flat_map do |relation|
+            relation.foreign_keys.map{|foreign_key| [ namespace, relation, foreign_key, false ] }
+          end
+        end
+        declared + inferred_relationship_candidates(source_namespaces)
+      end
+
+      def through_relationships_from(junction_namespace, junction_relation, source_key, source_namespace, source,
+                                     source_inferred)
+        candidates = relationship_candidates.select do |namespace, relation, _key, _inferred|
+          namespace == junction_namespace && relation == junction_relation
+        end
+        candidates.filter_map do |_namespace, _relation, target_key, target_inferred|
+          next if target_key == source_key
+
+          target_namespace = namespace(target_key.referenced_namespace || junction_namespace.name)
+          target = target_namespace&.relation(target_key.referenced_relation)
+          next unless target
+          next unless junction_table?(junction_relation, source_key, target_key, source, target)
+
+          ThroughRelationship.new(
+            source_namespace: source_namespace, source_relation: source,
+            target_namespace: target_namespace, target_relation: target,
+            junction_namespace: junction_namespace, junction_relation: junction_relation,
+            source_foreign_key: source_key, target_foreign_key: target_key,
+            inferred: source_inferred || target_inferred
+          )
+        end
+      end
+
+      def direct_relationship(source_namespace, source_relation, foreign_key, inferred)
+        target_namespace = namespace(foreign_key.referenced_namespace || source_namespace.name)
+        target = target_namespace&.relation(foreign_key.referenced_relation)
+        return unless target
+
+        DirectRelationship.new(
+          source_namespace: source_namespace, source_relation: source_relation,
+          target_namespace: target_namespace, target_relation: target, foreign_key: foreign_key, inferred: inferred
+        )
+      end
+
+      def junction_key?(relation, columns)
+        names = columns.sort
+        return true if relation.primary_key&.columns&.sort == names
+        return true if relation.unique_constraints.any?{|constraint| constraint.columns.sort == names }
+
+        relation.indexes.any? do |index|
+          index.unique && !index.partial? && !index.expression? && index.columns.sort == names
+        end
+      end
+
+      def junction_table?(relation, source_key, target_key, source, target)
+        columns = source_key.columns | target_key.columns
+        junction_key?(relation, columns) || conventional_junction_name?(relation.name, source.name, target.name)
+      end
+
+      def conventional_junction_name?(junction_name, source_name, target_name)
+        source_forms = relationship_name_forms(source_name)
+        target_forms = relationship_name_forms(target_name)
+        source_forms.product(target_forms).any? do |source, target|
+          [ "#{source}_#{target}", "#{target}_#{source}" ].include?(junction_name)
+        end
+      end
+
+      def relationship_name_forms(name)
+        snake = ActiveSupport::Inflector.underscore(name)
+        [ snake, ActiveSupport::Inflector.singularize(snake) ].uniq
+      end
+
+      def reference_matches?(source_namespace, foreign_key, target_namespace, target_relation)
+        namespace_name = foreign_key.referenced_namespace || source_namespace.name
+        namespace_name == target_namespace.name && foreign_key.referenced_relation == target_relation.name
+      end
+    end
+  end
+end

data/lib/rdbr/metadata/values.rb

@@ -0,0 +1,73 @@
+module RDBr
+  module Metadata
+    class InvalidMetadataError < ArgumentError
+    end
+
+    module Values
+      module_function
+
+      def name(value, field:)
+        raise InvalidMetadataError, "#{field} must be a non-empty String" unless value.is_a?(String) && !value.empty?
+
+        value.dup.freeze
+      end
+
+      def optional_name(value, field:)
+        return if value.nil?
+
+        name(value, field: field)
+      end
+
+      def optional_string(value, field:)
+        return if value.nil?
+        raise InvalidMetadataError, "#{field} must be a String" unless value.is_a?(String)
+
+        value.dup.freeze
+      end
+
+      def collection(value, member:, field:, allow_empty: true)
+        unless value.is_a?(Array) && value.all?{|item| item.is_a?(member) }
+          raise InvalidMetadataError, "#{field} must be an Array of #{member}"
+        end
+        raise InvalidMetadataError, "#{field} must not be empty" if !allow_empty && value.empty?
+
+        value.dup.freeze
+      end
+
+      def names(value, field:, allow_empty: false)
+        unless value.is_a?(Array) && value.all?{|item| item.is_a?(String) && !item.empty? }
+          raise InvalidMetadataError, "#{field} must be an Array of non-empty Strings"
+        end
+        raise InvalidMetadataError, "#{field} must not be empty" if !allow_empty && value.empty?
+
+        value.map{|item| item.dup.freeze }.freeze
+      end
+
+      def boolean(value, field:)
+        return value if [ true, false ].include?(value)
+
+        raise InvalidMetadataError, "#{field} must be true or false"
+      end
+
+      def deep_copy_freeze(value)
+        case value
+        when Array
+          value.map{|item| deep_copy_freeze(item) }.freeze
+        when Hash
+          value.to_h{|key, item| [ deep_copy_freeze(key), deep_copy_freeze(item) ] }.freeze
+        when String
+          value.dup.freeze
+        else
+          value.freeze
+        end
+      end
+
+      def unique_names!(items, field:)
+        duplicates = items.group_by(&:name).reject{|name, _| name.nil? }.select{|_, matches| matches.length > 1 }.keys
+        return if duplicates.empty?
+
+        raise InvalidMetadataError, "#{field} contains duplicate names: #{duplicates.join(', ')}"
+      end
+    end
+  end
+end

data/lib/rdbr/metadata.rb

@@ -0,0 +1,10 @@
+require_relative 'metadata/values'
+require_relative 'metadata/column'
+require_relative 'metadata/keys'
+require_relative 'metadata/constraints'
+require_relative 'metadata/index'
+require_relative 'metadata/relation'
+require_relative 'metadata/namespace'
+require_relative 'metadata/relationship_inference'
+require_relative 'metadata/relationships'
+require_relative 'metadata/database'

data/lib/rdbr/presentation/record_identity.rb

@@ -0,0 +1,125 @@
+module RDBr
+  module Presentation
+    class RecordIdentity
+      Candidate = Data.define(:columns, :score)
+      TEXT_TYPES = %i[bpchar char citext name text varchar].freeze
+      EXACT_SCORES = {
+        'display_name' => 1000, 'full_name' => 990, 'name' => 980, 'title' => 970,
+        'legal_name' => 960, 'trading_name' => 955, 'label' => 940, 'caption' => 930,
+        'heading' => 925, 'subject' => 920, 'username' => 880, 'login' => 875,
+        'reference' => 850, 'reference_number' => 845, 'code' => 830, 'slug' => 810,
+        'email' => 780, 'summary' => 700, 'description' => 400
+      }.freeze
+      SENSITIVE_PATTERN = /password|passwd|secret|token|digest|hash|salt|api_?key|private_?key|credential/i
+      UNHELPFUL_NAMES = %w[type status state kind category body content notes].freeze
+      PERSON_NAME_PAIRS = [
+        %w[first_name last_name], %w[given_name family_name], %w[forename surname]
+      ].freeze
+
+      def initialize(relation)
+        @relation = relation
+        @candidates = (person_name_candidates + column_candidates).sort_by{|candidate| -candidate.score }.freeze
+      end
+
+      def label(row, exclude: [])
+        excluded = exclude.map(&:to_s)
+        candidate = @candidates.find do |item|
+          item.columns.none?{|column| excluded.include?(column.name) } &&
+            item.columns.all?{|column| present?(row[column.name]) }
+        end
+        return join_values(candidate.columns, row) if candidate
+
+        fallback_label(row)
+      end
+
+      private
+
+      attr_reader :relation
+
+      def person_name_candidates
+        PERSON_NAME_PAIRS.filter_map do |names|
+          columns = names.filter_map{|name| relation.column(name) }
+          next unless columns.length == names.length
+          next if columns.any?{|column| !text_column?(column) }
+
+          Candidate.new(columns: columns, score: 965 + constraint_bonus(columns))
+        end
+      end
+
+      def column_candidates
+        relation.columns.filter_map do |column|
+          next unless text_column?(column)
+          next if sensitive_column?(column) || foreign_key_column?(column)
+
+          Candidate.new(columns: [ column ], score: column_score(column))
+        end
+      end
+
+      def column_score(column)
+        name = normalized_name(column.name)
+        score = EXACT_SCORES.fetch(name, inferred_name_score(name))
+        score -= 250 if UNHELPFUL_NAMES.include?(name)
+        score + constraint_bonus([ column ]) + (column.nullable ? 0 : 10)
+      end
+
+      def inferred_name_score(name)
+        return 950 if relation_name_forms.any?{|form| name == "#{form}_name" }
+        return 900 if name.end_with?('_name')
+
+        200
+      end
+
+      def constraint_bonus(columns)
+        names = columns.map(&:name)
+        return 25 if relation.primary_key&.columns == names
+        return 20 if uniquely_constrained?(names)
+
+        0
+      end
+
+      def uniquely_constrained?(names)
+        return true if relation.unique_constraints.any?{|constraint| constraint.columns == names }
+
+        relation.indexes.any? do |index|
+          index.unique && !index.partial? && !index.expression? && index.columns == names
+        end
+      end
+
+      def relation_name_forms
+        normalized = normalized_name(relation.name)
+        singular = normalized.end_with?('ies') ? "#{normalized.delete_suffix('ies')}y" : normalized.delete_suffix('s')
+        [ normalized, singular ].uniq
+      end
+
+      def normalized_name(name)
+        name.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').tr(' -', '__').downcase.gsub(/_+/, '_')
+      end
+
+      def text_column?(column)
+        TEXT_TYPES.include?(column.logical_type.to_s.to_sym)
+      end
+
+      def sensitive_column?(column)
+        column.name.match?(SENSITIVE_PATTERN)
+      end
+
+      def foreign_key_column?(column)
+        relation.foreign_keys.any?{|key| key.columns.include?(column.name) }
+      end
+
+      def present?(value)
+        !value.nil? && !value.to_s.strip.empty?
+      end
+
+      def join_values(columns, row)
+        columns.map{|column| row[column.name].to_s.strip }.join(' ')
+      end
+
+      def fallback_label(row)
+        columns = relation.primary_key&.columns || relation.columns.map(&:name)
+        values = columns.filter_map{|column| row[column] unless row[column].nil? }
+        values.empty? ? 'Record' : values.map(&:to_s).join(' · ')
+      end
+    end
+  end
+end

data/lib/rdbr/query/connection.rb

@@ -0,0 +1,138 @@
+module RDBr
+  module Query
+    class Connection
+      module Records
+        MUTEX = Mutex.new
+
+        module_function
+
+        def build(parent)
+          MUTEX.synchronize do
+            name = "Record#{next_identifier}"
+            const_set(name, Class.new(parent))
+            [ const_get(name), name ]
+          end
+        end
+
+        def remove(name)
+          MUTEX.synchronize{ remove_const(name) if const_defined?(name, false) }
+        end
+
+        def next_identifier
+          @next_identifier = @next_identifier.to_i + 1
+        end
+      end
+
+      class Record < ActiveRecord::Base
+        self.abstract_class = true
+
+        def readonly?
+          true
+        end
+      end
+
+      DEFAULT_OPTIONS = {
+        statement_timeout: 5000, pool_size: 5, checkout_timeout: 5000, max_value_bytes: 1_048_576
+      }.freeze
+
+      def initialize(database_url, options: {}, access_policy: nil)
+        options = DEFAULT_OPTIONS.merge(options)
+        @record_class, @record_class_name = Records.build(Record)
+        @access_policy = access_policy || Access::ReadOnly.new(statement_timeout: options.fetch(:statement_timeout))
+        @value_limiter = ValueLimiter.new(max_bytes: options.fetch(:max_value_bytes))
+        @record_class.establish_connection(
+          url: database_url,
+          pool: positive_integer(options.fetch(:pool_size), 'pool size'),
+          checkout_timeout: positive_integer(options.fetch(:checkout_timeout), 'checkout timeout').fdiv(1000)
+        )
+        with_connection do |database_connection|
+          @adapter_name = database_connection.adapter_name.downcase
+          @mariadb = database_connection.select_value('SELECT VERSION()').to_s.include?('MariaDB') if mysql?
+          @access_policy.configure(database_connection, adapter_name: @adapter_name, mariadb: @mariadb)
+        end
+      rescue ActiveRecord::ActiveRecordError, ArgumentError => e
+        raise ExecutionError, "Unable to configure read-only database connection (#{e.class})"
+      end
+
+      def quote_identifier(identifier)
+        with_connection{|database_connection| database_connection.quote_column_name(identifier.to_s) }
+      end
+
+      def quote(value)
+        with_connection{|database_connection| database_connection.quote(value) }
+      end
+
+      def select_all(sql)
+        @access_policy.validate_statement!(sql)
+        with_connection do |database_connection|
+          configure_session(database_connection)
+          @value_limiter.call(database_connection.select_all(sql).to_a)
+        end
+      rescue ActiveRecord::ActiveRecordError => e
+        raise classified_error(e), classified_message(e)
+      end
+
+      def select_value(sql)
+        @access_policy.validate_statement!(sql)
+        with_connection do |database_connection|
+          configure_session(database_connection)
+          @value_limiter.call(database_connection.select_value(sql))
+        end
+      rescue ActiveRecord::ActiveRecordError => e
+        raise classified_error(e), classified_message(e)
+      end
+
+      def disconnect
+        @record_class.connection_pool.disconnect!
+        Records.remove(@record_class_name)
+      end
+
+      private
+
+      def configure_session(database_connection)
+        database_connection.verify!
+        @access_policy.configure(database_connection, adapter_name: @adapter_name, mariadb: @mariadb)
+      end
+
+      def mysql?
+        [ 'mysql', 'mysql2', 'trilogy' ].include?(@adapter_name)
+      end
+
+      def positive_integer(value, label)
+        number = Integer(value)
+        raise ArgumentError, "#{label} must be positive" unless number.positive?
+
+        number
+      end
+
+      def with_connection(&)
+        @record_class.connection_pool.with_connection(&)
+      end
+
+      def classified_error(error)
+        return TimeoutError if error.is_a?(ActiveRecord::ConnectionTimeoutError) || timeout_error?(error)
+        return ConnectionUnavailableError if error.is_a?(ActiveRecord::ConnectionNotEstablished)
+        return AccessDeniedError if permission_error?(error)
+
+        ExecutionError
+      end
+
+      def classified_message(error)
+        case classified_error(error).name
+        when ConnectionUnavailableError.name then 'Database connection is unavailable'
+        when TimeoutError.name then 'Database operation timed out'
+        when AccessDeniedError.name then 'Database denied access to this relation'
+        else "Read-only database query failed (#{error.class})"
+        end
+      end
+
+      def timeout_error?(error)
+        error.message.match?(/(?:statement timeout|query execution was interrupted|maximum statement execution time)/i)
+      end
+
+      def permission_error?(error)
+        error.message.match?(/(?:permission denied|access denied|command denied|not authorized)/i)
+      end
+    end
+  end
+end

data/lib/rdbr/query/errors.rb

@@ -0,0 +1,33 @@
+module RDBr
+  module Query
+    class Error < StandardError
+    end
+
+    class ConfigurationError < Error
+    end
+
+    class InvalidQueryError < Error
+    end
+
+    class RelationNotFoundError < Error
+    end
+
+    class UnsupportedAdapterError < Error
+    end
+
+    class ExecutionError < Error
+    end
+
+    class AccessViolationError < ExecutionError
+    end
+
+    class AccessDeniedError < ExecutionError
+    end
+
+    class TimeoutError < ExecutionError
+    end
+
+    class ConnectionUnavailableError < ExecutionError
+    end
+  end
+end

data/lib/rdbr/query/lookup.rb

@@ -0,0 +1,40 @@
+module RDBr
+  module Query
+    module Lookup
+      def lookup(namespace:, relation:, keys:)
+        _namespace, relation_metadata = find_relation(namespace, relation)
+        normalized_keys = normalize_lookup_keys(relation_metadata, keys)
+        return [] if normalized_keys.empty?
+
+        table = [ namespace, relation ].map{|name| connection.quote_identifier(name) }.join('.')
+        predicates = normalized_keys.map{|key| lookup_predicate(key) }
+        connection.select_all("SELECT * FROM #{table} WHERE #{predicates.join(' OR ')}")
+      end
+
+      private
+
+      def normalize_lookup_keys(relation, keys)
+        normalized = keys.map{|key| key.to_h.transform_keys(&:to_s) }.uniq
+        normalized.each{|key| validate_lookup_key!(relation, key) }
+        column_sets = normalized.map{|key| key.keys.sort }.uniq
+        raise InvalidQueryError, 'Every lookup key must contain the same columns' unless column_sets.length <= 1
+
+        normalized.reject{|key| key.values.any?(&:nil?) }
+      end
+
+      def validate_lookup_key!(relation, key)
+        raise InvalidQueryError, 'Lookup keys must contain at least one column' if key.empty?
+
+        unknown = key.keys.reject{|name| relation.column(name) }
+        raise InvalidQueryError, "Unknown lookup column: #{unknown.first}" unless unknown.empty?
+      end
+
+      def lookup_predicate(key)
+        conditions = key.map do |column, value|
+          "#{connection.quote_identifier(column)} = #{connection.quote(value)}"
+        end
+        "(#{conditions.join(' AND ')})"
+      end
+    end
+  end
+end

data/lib/rdbr/query/mysql.rb

@@ -0,0 +1,15 @@
+module RDBr
+  module Query
+    class Mysql < Relational
+      private
+
+      def pattern_expression(identifier, value)
+        "#{identifier} LIKE #{value} ESCAPE '\\\\'"
+      end
+
+      def text_expression(identifier)
+        "CAST(#{identifier} AS CHAR)"
+      end
+    end
+  end
+end