pglpg 0.1.0 → 0.3.0

data/lib/pglpg/context.rb

@@ -4,11 +4,12 @@ module Pglpg
   # A graph seen by one viewer. Created by Graph#for; immutable. Every query
   # and write built from it applies the graph's policies for this viewer.
   class Context
-    attr_reader :graph, :viewer
+    attr_reader :graph, :viewer, :as_of
 
-    def initialize(graph, viewer)
+    def initialize(graph, viewer, as_of: nil)
       @graph = graph
       @viewer = viewer
+      @as_of = as_of.equal?(:any) ? :any : Temporal.date(as_of, error: ArgumentError)
       freeze
     end
 
@@ -23,6 +24,7 @@ module Pglpg
       graph.check_ref!(ref, ref.kind)
       return match.node(:n, ref:).first&.fetch(:n) if ref.node?
 
+      temporal_mode!(graph.type.edge_types.values)
       sql = Sql.new(graph.connection)
       e = "e"
       sql << "SELECT to_jsonb(e) AS e FROM " << table_sql(graph.edges_table) << " AS e"
@@ -33,6 +35,7 @@ module Pglpg
       sql << " WHERE e.id = "
       sql.bind(ref.id, "bigint") << " AND "
       append_edge_visible(sql, e)
+      append_temporal(sql, e, graph.type.edge_types.values)
       row = read(sql).first
       row && graph.build_edge(JSON.parse(row["e"]))
     end
@@ -40,21 +43,44 @@ module Pglpg
     # The visible node of +type+ (or a subtype) with the given key, or nil.
     #   ctx.find_node(:Person, uid: "PER-12")
     def find_node(type, **key)
+      key = key.transform_keys(&:to_sym)
       node_type = graph.type.node_type!(type)
-      unless node_type.key && key.keys == [node_type.key.property]
-        raise ArgumentError, "#{type} is looked up by #{node_type.key&.property.inspect}"
-      end
+      raise ArgumentError, "#{type} has no key" unless node_type.key
 
+      node_type.key.validate_values!(node_type, key)
       match.node(:n, type, **key).first&.fetch(:n)
     end
 
+    # Lookup by an exact edge property key. Compiler guards apply to the
+    # edge, both endpoints and the context's selected date.
+    def find_edge(type, **key)
+      edge_type = graph.type.edge_type!(type)
+      raise ArgumentError, "#{type} has no property key" unless edge_type.key
+
+      key = key.transform_keys(&:to_sym)
+      edge_type.key.validate_values!(edge_type, key)
+      query = match.node(:s)
+      query = query.public_send(edge_type.symmetric? ? :both : :out, type, :t, edge: :e)
+      query.where(e: key).return(:e).first&.fetch(:e)
+    end
+
+    # Visible nodes reachable from +from+ within +max_depth+ hops over the
+    # edge types in +via+, each with its minimum depth (a Reachability).
+    # Hidden nodes and edges are never traversed. The traversal is one
+    # statement; +deadline+ (seconds) can only shorten the configured
+    # statement timeout. See ADR-0009.
+    #   ctx.reachable(from: ref, via: %i[KNOWS], max_depth: 3, max_nodes: 500)
+    def reachable(from:, via:, max_depth:, max_nodes:, direction: :out, deadline: nil)
+      Reachable.new(self, from:, via:, direction:, max_depth:, max_nodes:, deadline:).call
+    end
+
     def insert_node(type, properties: {}, attrs: {}) = writer.insert_node(type, properties:, attrs:)
 
     def update_node(ref, properties: {}, attrs: {}) = writer.update_node(ref, properties:, attrs:)
 
-    def insert_edge(type, from:, to:, properties: {}, attrs: {}) = writer.insert_edge(type, from:, to:, properties:, attrs:)
+    def insert_edge(type, from:, to:, properties: {}, attrs: {}, **validity) = writer.insert_edge(type, from:, to:, properties:, attrs:, **validity)
 
-    def update_edge(ref, properties: {}, attrs: {}) = writer.update_edge(ref, properties:, attrs:)
+    def update_edge(ref, properties: {}, attrs: {}, **validity) = writer.update_edge(ref, properties:, attrs:, **validity)
 
     def delete_edge(ref) = writer.delete_edge(ref)
 
@@ -63,13 +89,43 @@ module Pglpg
     # callable approves this context. It does not bypass validation, the
     # write policy or endpoint checks.
     def trusted_writer
+      writable!
       allowed = graph.trusted_writer_allowed
       raise NotTrusted, "trusted writer not granted" unless allowed.respond_to?(:call) && allowed.call(self) == true
 
       Writer.new(self, trusted: true)
     end
 
-    def inspect = "#<Pglpg::Context #{graph.name} viewer=#{viewer.inspect}>"
+    def inspect
+      value = as_of.instance_of?(Date) ? as_of.iso8601 : as_of.inspect
+      mode = " as_of=#{value}" unless as_of.nil?
+      "#<Pglpg::Context #{graph.name} viewer=#{viewer.inspect}#{mode}>"
+    end
+
+    def writable!
+      raise ReadOnlyContext, "dated contexts are read-only" if as_of.instance_of?(Date)
+    end
+
+    def temporal_mode!(types)
+      if as_of.nil? && types.any?(&:temporal?)
+        raise TemporalModeRequired, "temporal reads require as_of: Date or :any"
+      end
+    end
+
+    # Appended alongside visibility, before every join/expansion/terminal.
+    def append_temporal(sql, name, types)
+      temporal_mode!(types)
+      temporal = types.select(&:temporal?)
+      return unless as_of.instance_of?(Date) && temporal.any?
+
+      sql << " AND ("
+      if temporal.size != types.size
+        sql << name << ".type <> ALL("
+        sql.bind_text_array(temporal.map(&:name)) << ") OR "
+      end
+      sql << "daterange(" << name << ".valid_from, " << name << ".valid_to, '[)') @> "
+      sql.bind(as_of.iso8601, "date") << ")"
+    end
 
     # -- internal ------------------------------------------------------------
 
@@ -88,13 +144,15 @@ module Pglpg
       sql << ")"
     end
 
-    # Runs a read under the configured statement timeout.
-    def read(sql)
+    # Runs a read under +timeout+ (ms; default: the configured statement
+    # timeout). nil leaves the session's timeout as it is. The read always
+    # runs in a savepoint, so a timeout (ours or the session's) never leaves
+    # the caller's transaction aborted.
+    def read(sql, timeout: Pglpg.configuration.statement_timeout)
       graph.with_connection do |c|
-        timeout = Pglpg.configuration.statement_timeout
-        next c.select_all(sql.to_s, "Pglpg", sql.binds).to_a if timeout.nil?
-
         c.transaction(requires_new: true) do
+          next c.select_all(sql.to_s, "Pglpg", sql.binds).to_a if timeout.nil?
+
           previous = c.select_value("SELECT current_setting('statement_timeout')")
           c.select_value("SELECT set_config('statement_timeout', '#{Integer(timeout)}', true)")
           rows = c.select_all(sql.to_s, "Pglpg", sql.binds).to_a

data/lib/pglpg/element.rb

@@ -31,11 +31,13 @@ module Pglpg
     def inspect = "#<Pglpg::Node #{ref} #{key_label} #{properties.inspect}>"
   end
 
-  # An edge read from the graph. Values are frozen.
+  # An edge read from the graph. Values are frozen. For a symmetric edge type,
+  # source and target are the stored (canonical) endpoints and carry no
+  # direction; use #other to walk from one end to the other.
   class Edge
     attr_reader :ref, :type, :source, :target, :properties, :attrs, :created_at, :updated_at
 
-    def initialize(ref:, type:, source:, target:, properties:, attrs:, created_at:, updated_at:)
+    def initialize(ref:, type:, source:, target:, properties:, attrs:, created_at:, updated_at:, symmetric: false, temporal: false, valid_from: nil, valid_to: nil)
       @ref = ref
       @type = type
       @source = source
@@ -44,6 +46,10 @@ module Pglpg
       @attrs = attrs
       @created_at = created_at
       @updated_at = updated_at
+      @temporal = temporal
+      @valid_from = valid_from
+      @valid_to = valid_to
+      @symmetric = symmetric
       freeze
     end
 
@@ -51,12 +57,26 @@ module Pglpg
 
     def [](name) = properties[name.to_sym]
 
+    attr_reader :valid_from, :valid_to
+
+    def temporal? = @temporal
+
+    def symmetric? = @symmetric
+
+    # The endpoint opposite +ref+ (the same node for a self-loop).
+    def other(ref)
+      return target if ref == source
+      return source if ref == target
+
+      raise ArgumentError, "#{ref} is not an endpoint of #{self.ref}"
+    end
+
     def ==(other) = other.is_a?(Edge) && other.ref == ref
 
     alias eql? ==
 
     def hash = ref.hash
 
-    def inspect = "#<Pglpg::Edge #{ref} #{type} #{source.id}->#{target.id} #{properties.inspect}>"
+    def inspect = "#<Pglpg::Edge #{ref} #{type} #{source.id}#{symmetric? ? "--" : "->"}#{target.id} #{properties.inspect}>"
   end
 end

data/lib/pglpg/errors.rb

@@ -10,6 +10,10 @@ module Pglpg
   # pglpg is used without a required policy or setting.
   class ConfigurationError < Error; end
 
+  class ReadOnlyContext < Error; end
+  class TemporalModeRequired < Error; end
+  class TemporalMigrationRequired < Error; end
+
   # A Ref belongs to another graph or is the wrong kind of element.
   class InvalidRef < Error; end
 

data/lib/pglpg/graph.rb

@@ -18,15 +18,15 @@ module Pglpg
     attr_reader :name, :type, :storage
 
     def self.define(name, nodes_table: nil, edges_table: nil, visibility: nil, write_policy: nil,
-                    trusted_writer_allowed: nil, connection_class: nil, &block)
+                    trusted_writer_allowed: nil, key_scope_allowed: nil, connection_class: nil, &block)
       type = Schema::GraphType.new
       Schema::Builder.new(type).instance_eval(&block) if block
       type.resolve!
       new(name, type, nodes_table: nodes_table || "#{name}_nodes", edges_table: edges_table || "#{name}_edges",
-                      visibility:, write_policy:, trusted_writer_allowed:, connection_class:)
+                      visibility:, write_policy:, trusted_writer_allowed:, key_scope_allowed:, connection_class:)
     end
 
-    def initialize(name, type, nodes_table:, edges_table:, visibility:, write_policy:, trusted_writer_allowed:,
+    def initialize(name, type, nodes_table:, edges_table:, visibility:, write_policy:, trusted_writer_allowed:, key_scope_allowed:,
                    connection_class:)
       @name = Schema.check_name!(name, "graph")
       @type = type
@@ -34,14 +34,15 @@ module Pglpg
       @visibility = visibility
       @write_policy = write_policy
       @trusted_writer_allowed = trusted_writer_allowed
+      @key_scope_allowed = key_scope_allowed
       @connection_class = connection_class
       freeze
     end
 
     # The only entry point for queries and writes. The returned context is
     # immutable and carries the viewer to everything built from it.
-    def for(viewer:)
-      Context.new(self, viewer)
+    def for(viewer:, as_of: nil)
+      Context.new(self, viewer, as_of:)
     end
 
     def ref(kind, id) = Ref.new(graph: name, kind:, id:)
@@ -77,6 +78,8 @@ module Pglpg
 
     def trusted_writer_allowed = @trusted_writer_allowed || Pglpg.configuration.trusted_writer_allowed
 
+    def key_scope_allowed = @key_scope_allowed.nil? ? Pglpg.configuration.key_scope_allowed : @key_scope_allowed
+
     def connection_class = @connection_class || Pglpg.configuration.connection_class || ActiveRecord::Base
 
     def with_connection(&) = connection_class.with_connection(&)
@@ -111,7 +114,11 @@ module Pglpg
         source: ref(:node, row["source_id"]), target: ref(:node, row["target_id"]),
         properties: edge_type ? edge_type.decode_properties(row["properties"]) : row["properties"].transform_keys(&:to_sym).freeze,
         attrs: decode_attrs(type.edge_columns, row),
-        created_at: Time.iso8601(row["created_at"]), updated_at: Time.iso8601(row["updated_at"])
+        created_at: Time.iso8601(row["created_at"]), updated_at: Time.iso8601(row["updated_at"]),
+        temporal: edge_type&.temporal? || false,
+        valid_from: edge_type&.temporal? && row["valid_from"] ? Date.iso8601(row["valid_from"], Date::GREGORIAN).freeze : nil,
+        valid_to: edge_type&.temporal? && row["valid_to"] ? Date.iso8601(row["valid_to"], Date::GREGORIAN).freeze : nil,
+        symmetric: edge_type&.symmetric? || false
       )
     end
 

data/lib/pglpg/model/base.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+module Pglpg
+  module Model
+    # Shared by Model::Node and Model::Edge. A model class binds a graph and
+    # a schema type; its attributes are the type's properties and the
+    # graph's application columns. Models keep the Context they were read
+    # or built through, and write through its guarded write API (ADR-0010).
+    class Base
+      include ActiveModel::API
+      include ActiveModel::Attributes
+      include ActiveModel::Dirty
+
+      # Attributes are assigned as given: no form coercion ("42" stays a
+      # String). The schema checks values on validation.
+      #
+      # Every conversion copies Strings and Arrays, so the dirty baseline and
+      # the caller's object never share the record's value, and in-place
+      # edits (tags << "b", name << "e") count as changes.
+      class StrictType < ActiveModel::Type::Value
+        def cast(value) = copy(value)
+
+        def deserialize(value) = copy(value)
+
+        def serialize(value) = copy(value)
+
+        def changed_in_place?(raw_old_value, new_value) = raw_old_value != new_value
+
+        private
+
+        def copy(value)
+          case value
+          when Array then value.map { copy(_1) }
+          when String then value.dup
+          else value
+          end
+        end
+      end
+
+      STRICT = StrictType.new
+
+      CORE_OWNERS = [Kernel, Object, BasicObject].freeze
+      CORE_METHODS = %i[
+        class hash freeze frozen? send public_send object_id method methods respond_to? dup clone
+        equal? eql? is_a? kind_of? instance_of? nil? itself instance_variable_get instance_variable_set
+      ].freeze
+
+      validate :validate_schema
+
+      class << self
+        # Binds the model to a graph and a schema type:
+        #   graph Kg, type: :Person
+        # Without arguments, returns the bound graph.
+        def graph(graph = nil, type: nil)
+          return @graph if graph.nil? && type.nil?
+          raise ConfigurationError, "#{self} is already bound to graph #{@graph.name}" if @graph
+          raise ArgumentError, "graph must be a Pglpg::Graph" unless graph.is_a?(Pglpg::Graph)
+
+          schema_type = resolve_type(graph, type)
+          check_parent!(graph, schema_type)
+          property_names = schema_type.properties.keys
+          column_names = element_columns(graph).keys
+          check_attribute_names!(schema_type, property_names, column_names)
+
+          property_names.each { attribute(_1, STRICT) }
+          column_names.each { attribute(_1, STRICT) }
+          if kind == :edge && schema_type.temporal?
+            Temporal::NAMES.each do |name|
+              if instance_methods(false).include?(name) || instance_methods(false).include?(:"#{name}=")
+                raise SchemaError, "#{schema_type.name}.#{name} clashes with temporal metadata"
+              end
+              attribute(name, Edge::BOUND)
+            end
+          end
+          @graph = graph
+          @schema_type = schema_type
+          @property_names = property_names.freeze
+          @column_names = column_names.freeze
+          Model.register(graph, kind, schema_type.name, self)
+          graph
+        end
+
+        attr_reader :schema_type, :property_names, :column_names
+
+        # The model's elements as seen through +context+: a Relation.
+        def in(context)
+          raise ConfigurationError, "#{self} is not bound to a graph; declare graph Kg, type: ..." unless @graph
+          raise ArgumentError, "expected a Pglpg::Context" unless context.is_a?(Pglpg::Context)
+          raise ArgumentError, "the context belongs to graph #{context.graph.name}, not #{@graph.name}" unless context.graph.equal?(@graph)
+
+          Relation.new(self, context)
+        end
+
+        # Anonymous model classes are named after their schema type, so
+        # validation messages work for them too.
+        def model_name
+          return super if name
+
+          @model_name ||= ActiveModel::Name.new(self, nil, schema_type&.name&.to_s || base_class.name.split("::").last)
+        end
+
+        # -- internal ----------------------------------------------------------
+
+        # A model of +element+, read through +context+: the model registered
+        # for its concrete type, else this one.
+        def instantiate(context, element)
+          klass = Model.lookup(graph, kind, element_type_name(element)) || self
+          klass.allocate.tap { _1.send(:load_element, context, element) }
+        end
+
+        # A new record bound to +context+.
+        def build(context, attributes)
+          new(attributes).tap { _1.instance_variable_set(:@context, context) }
+        end
+
+        private
+
+        # A model may extend another model only along the schema's inheritance,
+        # checked against the nearest bound ancestor (unbound classes between
+        # them still inherit its attributes).
+        def check_parent!(graph, schema_type)
+          parent = superclass
+          parent = parent.superclass while parent < Base && parent.schema_type.nil?
+          return unless parent < Base
+          return if parent.graph.equal?(graph) && inherits_type?(schema_type, parent.schema_type)
+
+          raise SchemaError, "#{self} (#{schema_type.name}) cannot extend #{parent} (#{parent.schema_type.name})"
+        end
+
+        def check_attribute_names!(schema_type, property_names, column_names)
+          clashes = property_names & column_names
+          raise SchemaError, "#{schema_type.name} has properties named like columns: #{clashes.join(", ")}" if clashes.any?
+
+          (property_names + column_names).each do |name|
+            if inherited_member_names.include?(name)
+              raise SchemaError, "#{schema_type.name}.#{name} clashes with the inherited association #{name}"
+            end
+            next unless reserved_name?(name)
+
+            raise SchemaError, "#{schema_type.name}.#{name} clashes with a method of #{base_class}"
+          end
+        end
+
+        # Names a model inherits that attributes may not take (associations).
+        def inherited_member_names = []
+
+        # Methods of the model classes and ActiveModel, public or private, plus
+        # the core Object methods an attribute must never shadow. Other
+        # Kernel and Object methods (format, display, ...) may be shadowed.
+        def reserved_name?(name)
+          [name, :"#{name}="].any? do |m|
+            next true if CORE_METHODS.include?(m)
+            next false unless base_class.method_defined?(m) || base_class.private_method_defined?(m)
+
+            !CORE_OWNERS.include?(base_class.instance_method(m).owner)
+          end
+        end
+      end
+
+      attr_reader :context, :ref, :created_at, :updated_at
+
+      # Properties stored on the element that this model's type does not
+      # declare (a subtype read through a base-type model). Read-only.
+      def extra_properties = @extra_properties || {}.freeze
+
+      def id = ref&.id
+
+      def persisted? = !ref.nil? && !destroyed?
+
+      def new_record? = ref.nil?
+
+      def destroyed? = @destroyed == true
+
+      def to_key = persisted? ? [id] : nil
+
+      # The ref as a String; Relation#find accepts it back.
+      def to_param = ref&.to_s
+
+      # Validates, then writes through the context's guarded write API: an
+      # insert for a new record, else an update of the changed attributes
+      # only. Returns false when validation fails. Refusals (WriteRejected,
+      # NotTrusted), timeouts and database errors raise; changes are kept on
+      # any failure. +writer:+ hands over the context's trusted writer, for
+      # trusted-only operations; generated keys remain unassignable.
+      #
+      # Success means the statement succeeded in the caller's transaction.
+      # Local state is what was assigned, not a stored snapshot (generated
+      # keys and timestamps are unknown until #reload), and a caller's
+      # rollback is not tracked: discard or reload the record after one.
+      def save(writer: nil)
+        target = write_target(writer)
+        return false unless valid?
+
+        persist(target)
+      end
+
+      # As #save, but raises RecordInvalid when validation fails.
+      def save!(writer: nil)
+        target = write_target(writer)
+        raise RecordInvalid, self unless valid?
+
+        persist(target)
+      end
+
+      # Deletes the element through the guarded write API (a node only
+      # through the trusted writer). Returns true.
+      def destroy(writer: nil)
+        context&.writable!
+        raise ArgumentError, "only a persisted record can be destroyed" unless persisted?
+
+        delete_element(write_target(writer))
+        @association_cache = nil
+        @destroyed = true
+      end
+
+      # Replaces attributes, timestamps and the dirty baseline from the
+      # stored element. Raises RecordNotFound, leaving the record unchanged,
+      # when it is missing or no longer visible.
+      def reload
+        element = ref && context&.find(ref)
+        raise RecordNotFound unless element && self.class.matches?(element)
+
+        load_element(context, element)
+        self
+      end
+
+      def ==(other) = other.is_a?(self.class.base_class) && !ref.nil? && other.ref == ref
+
+      alias eql? ==
+
+      def hash = ref ? ref.hash : super
+
+      def inspect
+        attrs = attributes.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")
+        "#<#{self.class.name || self.class.base_class.name} #{ref || "new"} #{attrs}>"
+      end
+
+      private
+
+      # ActiveModel casts lazily, on first read; copy on assignment so a
+      # caller who changes the object afterwards doesn't change the record.
+      def _write_attribute(name, value) = super(name, STRICT.cast(value))
+
+      def load_element(context, element)
+        @association_cache = nil
+        @attributes = self.class._default_attributes.deep_dup
+        @context = context
+        @ref = element.ref
+        @created_at = element.created_at
+        @updated_at = element.updated_at
+        properties = element.properties
+        self.class.property_names.each { @attributes.write_from_database(_1.to_s, properties[_1]) }
+        self.class.column_names.each { @attributes.write_from_database(_1.to_s, element.attrs[_1]) }
+        @extra_properties = properties.except(*self.class.property_names).freeze
+        load_identity(element)
+        clear_changes_information
+        self
+      end
+
+      # The context's interactive writes, or the given writer, which must
+      # belong to this record's own context (identity).
+      def write_target(writer)
+        raise ArgumentError, "#{self.class} has no context; build it with Model.in(ctx).new" unless context
+        context.writable!
+        raise ArgumentError, "#{self.class} was destroyed" if destroyed?
+        return context if writer.nil?
+        raise ArgumentError, "writer: expects a Pglpg::Writer" unless writer.is_a?(Pglpg::Writer)
+        raise ArgumentError, "the writer belongs to another context" unless writer.context.equal?(context)
+
+        writer
+      end
+
+      def persist(target)
+        if new_record?
+          create_element(target, assigned(self.class.property_names), assigned(self.class.column_names))
+        elsif changed?
+          update_element(target, changes_to(self.class.property_names), changes_to(self.class.column_names))
+        end
+        changes_applied
+        @association_cache = nil
+        true
+      end
+
+      # Non-nil values to insert (nil means absent).
+      def assigned(names)
+        names.each_with_object({}) do |name, out|
+          value = attribute(name.to_s)
+          out[name] = value unless value.nil?
+        end
+      end
+
+      # Changed values to update (nil removes a property).
+      def changes_to(names) = names.select { attribute_changed?(_1.to_s) }.to_h { [_1, attribute(_1.to_s)] }
+
+      def element_columns = self.class.send(:element_columns, self.class.graph)
+
+      # Schema checks: property values per the stored type, required
+      # properties and columns.
+      def validate_schema
+        type = schema_type
+        self.class.property_names.each do |name|
+          prop = type.property_named(name)
+          value = attribute(name.to_s)
+          if value.nil?
+            errors.add(name, :blank) if prop.required? && required_now?(name)
+          else
+            begin
+              prop.encode(value)
+            rescue ValidationError
+              errors.add(name, :invalid, message: "is not a valid #{prop.type == :list ? "list of #{prop.of}" : prop.type}")
+            end
+          end
+        end
+        element_columns.each_value do |column|
+          next unless attribute(column.name.to_s).nil?
+
+          blank = new_record? ? column.required? : attribute_changed?(column.name.to_s) && !column.null?
+          errors.add(column.name, :blank) if blank
+        end
+      end
+
+      # A missing required property is an error on insert, and when an
+      # update would remove it.
+      def required_now?(name) = new_record? || attribute_changed?(name.to_s)
+    end
+
+    # save! or create! found validation errors. #record has them.
+    class RecordInvalid < Error
+      attr_reader :record
+
+      def initialize(record)
+        @record = record
+        super("validation failed: #{record.errors.full_messages.join(", ")}")
+      end
+    end
+  end
+end