pglpg 0.2.0 → 0.4.0

data/lib/pglpg/testing/leak_examples.rb

@@ -22,33 +22,36 @@
 # (rows, order, counts, exists?, first, pagination, lookups) is unchanged.
 # Execution time and timeouts are outside this guarantee.
 RSpec.shared_examples "a pglpg visibility policy" do
-  leak_graph = lambda do |visibility, columns|
+  leak_graph = lambda do |visibility, columns, temporal, open|
     Pglpg::Graph.define(:pglpg_leak, nodes_table: "pglpg_leak_nodes", edges_table: "pglpg_leak_edges",
                                      visibility:, write_policy: Pglpg::Testing::AllowAll,
                                      trusted_writer_allowed: ->(_context) { true }) do
       columns.each { |name, (type, options)| column(name, type, **(options || {})) }
-      node :Person do
+      node :Person, open: open do
         property :uid, :string, required: true
         property :name, :string
         property :rank, :integer
         property :namespace, :string, required: true
         key :uid, scope: :namespace
       end
-      node :Project do
+      node :Project, open: open do
         property :uid, :string, required: true
-        property :title, :string
-        key :uid
+        property :title, :string, required: true
+        key :uid, :title
       end
       node :Location do
         property :uid, :string, required: true
         key :uid
       end
-      edge :WORKS_ON, from: :Person, to: :Project do
+      edge :WORKS_ON, from: :Person, to: :Project, temporal: temporal, open: open do
         property :role, :string
+        property :uid, :string, required: true
+        property :batch, :integer, required: true
+        key :uid, :batch
       end
-      edge :BASED_AT, from: :Project, to: :Location
-      edge :KNOWS, from: :Person, to: :Person
-      edge :FRIEND, from: :Person, to: :Person, symmetric: true
+      edge :BASED_AT, from: :Project, to: :Location, temporal: temporal
+      edge :KNOWS, from: :Person, to: :Person, temporal: temporal
+      edge :FRIEND, from: :Person, to: :Person, symmetric: true, temporal: temporal
     end
   end
 
@@ -59,17 +62,32 @@ RSpec.shared_examples "a pglpg visibility policy" do
     end
   end
 
-  let(:pglpg_leak_graph) { leak_graph.call(pglpg_visibility, pglpg_columns) }
-  let(:pglpg_seed_graph) { leak_graph.call(Pglpg::Testing::SeeAll, pglpg_columns) }
+  # Optional: also exercise temporal validity with the application policy.
+  let(:pglpg_temporal) { false }
+  # Optional: also exercise extra properties through reads/models.
+  let(:pglpg_open_types) { false }
+
+  let(:pglpg_leak_graph) { leak_graph.call(pglpg_visibility, pglpg_columns, pglpg_temporal, pglpg_open_types) }
+  let(:pglpg_seed_graph) { leak_graph.call(Pglpg::Testing::SeeAll, pglpg_columns, pglpg_temporal, pglpg_open_types) }
 
   it "keeps every observation unchanged when hidden data is added" do
     pglpg_leak_graph.storage.create!
     seed = pglpg_seed_graph.for(viewer: nil).trusted_writer
     vis = pglpg_visible_attrs
     hid = pglpg_hidden_attrs
-    person = ->(uid, name, rank, attrs) { seed.insert_node(:Person, properties: { uid:, name:, rank:, namespace: attrs == hid ? "hidden" : "visible" }, attrs:) }
-    node = ->(type, uid, attrs, **props) { seed.insert_node(type, properties: { uid:, **props }, attrs:) }
-    edge = ->(type, from, to, attrs, **props) { seed.insert_edge(type, from:, to:, properties: props, attrs:) }
+    person = lambda do |uid, name, rank, attrs|
+      extras = pglpg_open_types ? { source_note: uid, evidence: ["one", "two"] } : {}
+      seed.insert_node(:Person, properties: { uid:, name:, rank:, namespace: attrs == hid ? "hidden" : "visible", **extras }, attrs:)
+    end
+    node = lambda do |type, uid, attrs, **props|
+      extras = pglpg_open_types && type == :Project ? { source_note: uid } : {}
+      seed.insert_node(type, properties: { uid:, **props, **extras }, attrs:)
+    end
+    edge = lambda do |type, from, to, attrs, **props|
+      props = props.merge(uid: "#{from.id}-#{to.id}", batch: 1) if type == :WORKS_ON
+      props = props.merge(source_note: "evidence", evidence: [1, 2]) if pglpg_open_types && type == :WORKS_ON
+      seed.insert_edge(type, from:, to:, properties: props, attrs:, **(pglpg_temporal ? { valid_from: nil } : {}))
+    end
 
     # Created first, so it has the smallest id: symmetric edges to it are
     # stored with the hidden node in the source column.
@@ -92,7 +110,7 @@ RSpec.shared_examples "a pglpg visibility policy" do
     ]
     visible_refs = [p1, p2, p3, j1, j2, l1, *visible_edges]
 
-    ctx = pglpg_leak_graph.for(viewer: pglpg_viewer)
+    ctx = pglpg_leak_graph.for(viewer: pglpg_viewer, **(pglpg_temporal ? { as_of: Date.new(2020, 6, 1) } : {}))
     before = Pglpg::Testing.observe(ctx, visible_refs)
     # Three visible People plus two visible Projects in this fixture.
     raise "lazy association observations are missing" unless before.keys.count { _1.to_s.start_with?("assoc_") } == 5
@@ -127,6 +145,16 @@ RSpec.shared_examples "a pglpg visibility policy" do
       edge.(:KNOWS, h1, h2, hid)
     ]
 
+    if pglpg_temporal
+      # Visible but ineligible edges must be just as unobservable as hidden
+      # data, including expired shortcuts and a disjoint-time bridge.
+      [[p1, p3], [p3, p2]].each do |from, to|
+        hidden_refs << seed.insert_edge(:KNOWS, from:, to:, attrs: vis, valid_from: nil, valid_to: Date.new(2020, 6, 1))
+      end
+      hidden_refs << seed.insert_edge(:FRIEND, from: p1, to: p3, attrs: vis, valid_from: Date.new(2020, 6, 2))
+      hidden_refs << seed.insert_edge(:WORKS_ON, from: p1, to: j2, properties: { uid: "expired", batch: 1 }, attrs: vis, valid_from: nil, valid_to: Date.new(2020, 6, 1))
+    end
+
     after = Pglpg::Testing.observe(ctx, visible_refs)
     before.each_key { |name| expect(after[name]).to eq(before[name]), "observation #{name} changed" }
 

data/lib/pglpg/testing.rb

@@ -25,6 +25,7 @@ module Pglpg
         persons: -> { m.().node(:p, :Person).order(p: :name) },
         works_on: -> { m.().node(:p, :Person).out(:WORKS_ON, :j, :Project, edge: :w) },
         two_hops: -> { m.().node(:p, :Person).out(:WORKS_ON, :j, :Project).out(:BASED_AT, :l, :Location) },
+        parsed_knows_chain: -> { ctx.parse_match("MATCH (a:Person)-[:KNOWS]->(b:Person)-[:KNOWS]->(c:Person) RETURN a, b, c") },
         knows_chain: -> { m.().node(:a, :Person).out(:KNOWS, :b, :Person).out(:KNOWS, :c, :Person) },
         inbound: -> { m.().node(:l, :Location).in(:BASED_AT, :j, :Project).in(:WORKS_ON, :p, :Person) },
         branch: -> { m.().node(:j, :Project).in(:WORKS_ON, :p, :Person).out(:BASED_AT, :l, :Location, from: :j) },
@@ -69,6 +70,15 @@ module Pglpg
       out[:last_by_name] = element_data(m.().node(:p, :Person).order(p: { name: :desc }).first&.fetch(:p))
       out[:find] = refs.map { element_data(ctx.find(_1)) }
       out[:find_node] = %w[P1 P2 P3 H1].map { element_data(ctx.find_node(:Person, namespace: _1 == "H1" ? "hidden" : "visible", uid: _1)) }
+      out[:find_composite_node] = [["J1", "Apollo"], ["J2", "Gemini"], ["HJ", "Apollo"]].map do |uid, title|
+        element_data(ctx.find_node(:Project, uid:, title:))
+      end
+      persons = refs.select(&:node?).select { ctx.find(_1)&.key_label == :Person }
+      projects = refs.select(&:node?).select { ctx.find(_1)&.key_label == :Project }
+      out[:find_edge] = persons.product(projects).map do |person, project|
+        element_data(ctx.find_edge(:WORKS_ON, uid: "#{person.id}-#{project.id}", batch: 1))
+      end
+      out[:find_expired_edge] = element_data(ctx.find_edge(:WORKS_ON, uid: "expired", batch: 1)) if ctx.as_of.instance_of?(Date)
       out.merge(observe_models(ctx, refs))
     end
 

data/lib/pglpg/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pglpg
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/pglpg/writer.rb

@@ -11,7 +11,7 @@ module Pglpg
   # Scope-wide occupancy permission, distinct from write or read access.
   KeyScopeRequest = Data.define(:context, :domain, :scope)
 
-  WriteRequest = Data.define(:viewer, :operation, :type, :target, :from, :to, :key, :properties, :attrs, :trusted)
+  WriteRequest = Data.define(:viewer, :operation, :type, :target, :from, :to, :key, :properties, :attrs, :trusted, :validity, :validity_supplied)
 
   # Compiles writes into single statements. Visibility of the existing row,
   # the policy's conditions on it and endpoint checks all run inside the
@@ -21,6 +21,7 @@ module Pglpg
     attr_reader :context
 
     def initialize(context, trusted:)
+      context.writable!
       @context = context
       @graph = context.graph
       @trusted = trusted
@@ -28,14 +29,8 @@ module Pglpg
 
     def insert_node(type, properties: {}, attrs: {})
       node_type = concrete_node_type!(type)
-      props = properties.transform_keys(&:to_sym)
-      if (key = node_type.key)
-        if props.key?(key.property)
-          raise ArgumentError, "#{node_type.name}.#{key.property} is a key and is generated" unless @trusted || key.scope
-        else
-          props[key.property] = key.generate(node_type.name)
-        end
-      end
+      props = prepare_key(node_type, properties)
+      key = node_type.key
       json = node_type.encode_properties(props)
       cols = encode_attrs(@graph.type.node_columns, attrs, insert: true)
       authorize!(:insert_node, node_type.name, properties: props, attrs:)
@@ -56,7 +51,7 @@ module Pglpg
       @graph.check_ref!(ref, :node)
       node = @context.find(ref) or raise WriteRejected
       node_type = @graph.type.node_type!(node.key_label)
-      props = properties.transform_keys(&:to_sym)
+      props = node_type.normalize_properties(properties)
       raise ArgumentError, "keys cannot be changed" if node_type.key && (props.keys & node_type.key.properties).any?
 
       json = node_type.encode_properties(props, partial: true)
@@ -81,9 +76,9 @@ module Pglpg
       node_type = concrete_node_type!(type)
       node_key = node_type.key or raise ArgumentError, "#{node_type.name} has no key"
       key = key.transform_keys(&:to_sym)
-      raise ArgumentError, "#{node_type.name} is upserted by #{node_key.properties.inspect}" unless key.keys.sort == node_key.properties.sort
+      node_key.validate_values!(node_type, key)
 
-      props = properties.transform_keys(&:to_sym)
+      props = node_type.normalize_properties(properties)
       raise ArgumentError, "pass the key in key:, not properties:" if (props.keys & node_key.properties).any?
 
       props = props.merge(key)
@@ -94,11 +89,7 @@ module Pglpg
       sql = new_sql
       insert_node_values(sql, node_type, json, cols)
       sql << " ON CONFLICT ("
-      node_key.properties.each_with_index do |property, i|
-        sql << ", " if i.positive?
-        sql << "(properties->>"
-        sql.literal(property) << ")"
-      end
+      sql << node_key.expressions(@graph.connection).join(", ")
       sql << ") WHERE labels @> ARRAY["
       sql.literal(node_key.declared_on) << "]::text[] DO UPDATE SET "
       set_properties(sql, "tgt.properties", json, null_keys(props), excluded: true)
@@ -126,32 +117,50 @@ module Pglpg
       true
     end
 
-    def insert_edge(type, from:, to:, properties: {}, attrs: {})
+    def insert_edge(type, from:, to:, properties: {}, attrs: {}, valid_from: Temporal::OMITTED, valid_to: Temporal::OMITTED)
       edge_type = @graph.type.edge_type!(type)
-      if edge_type.unique_pair? && !@trusted
-        raise ArgumentError, "#{edge_type.name} is unique per pair; write it through the trusted writer"
+      if edge_type.unique_tuple? && !@trusted
+        raise ArgumentError, "#{edge_type.name} is unique per pair or property tuple; write it through the trusted writer"
       end
 
-      write_edge(:insert_edge, edge_type, from, to, properties, attrs)
+      write_edge(:insert_edge, edge_type, from, to, properties, attrs, valid_from, valid_to)
     end
 
-    # Trusted only, for edge types declared unique: :pair.
-    def upsert_edge(type, from:, to:, properties: {}, attrs: {})
+    # Trusted only. A declared edge key takes precedence as conflict arbiter;
+    # otherwise the endpoint/property tuple is used.
+    def upsert_edge(type, from:, to:, key: nil, properties: {}, attrs: {}, valid_from: Temporal::OMITTED, valid_to: Temporal::OMITTED)
       trusted!(:upsert_edge)
       edge_type = @graph.type.edge_type!(type)
-      raise ArgumentError, "#{edge_type.name} is not unique per pair; use insert_edge" unless edge_type.unique_pair?
-
-      write_edge(:upsert_edge, edge_type, from, to, properties, attrs)
+      if edge_type.key
+        raise ArgumentError, "#{edge_type.name} requires key:" unless key.is_a?(Hash)
+
+        key = key.transform_keys(&:to_sym)
+        edge_type.key.validate_values!(edge_type, key)
+        properties = edge_type.normalize_properties(properties)
+        raise ArgumentError, "pass the key in key:, not properties:" if (properties.keys & edge_type.key.properties).any?
+
+        properties = properties.merge(key)
+      else
+        raise ArgumentError, "#{edge_type.name} has no property key" unless key.nil?
+        raise ArgumentError, "#{edge_type.name} is not unique; use insert_edge" unless edge_type.unique_tuple?
+      end
+      write_edge(:upsert_edge, edge_type, from, to, properties, attrs, valid_from, valid_to, key:)
     end
 
-    def update_edge(ref, properties: {}, attrs: {})
+    def update_edge(ref, properties: {}, attrs: {}, valid_from: Temporal::OMITTED, valid_to: Temporal::OMITTED)
       @graph.check_ref!(ref, :edge)
-      edge = @context.find(ref) or raise WriteRejected
+      edge = @graph.for(viewer: @context.viewer, as_of: :any).find(ref) or raise WriteRejected
       edge_type = @graph.type.edge_type!(edge.type)
-      props = properties.transform_keys(&:to_sym)
+      validity = Temporal.bounds(edge_type, valid_from, valid_to)
+      Temporal.validate_interval!(validity.fetch(:valid_from, edge.valid_from), validity.fetch(:valid_to, edge.valid_to))
+      props = edge_type.normalize_properties(properties)
+      if (props.keys & edge_type.immutable_properties).any?
+        raise ArgumentError, "key and uniqueness properties cannot be changed"
+      end
       json = edge_type.encode_properties(props, partial: true)
       cols = encode_attrs(@graph.type.edge_columns, attrs, insert: false)
-      request = authorize!(:update_edge, edge_type.name, target: ref, properties: props, attrs:)
+      cols += validity_columns(validity)
+      request = authorize!(:update_edge, edge_type.name, target: ref, properties: props, attrs:, validity:)
 
       sql = new_sql
       sql << "UPDATE " << table(@graph.edges_table) << " AS tgt SET "
@@ -165,7 +174,7 @@ module Pglpg
 
     def delete_edge(ref)
       @graph.check_ref!(ref, :edge)
-      edge = @context.find(ref) or raise WriteRejected
+      edge = @graph.for(viewer: @context.viewer, as_of: :any).find(ref) or raise WriteRejected
       request = authorize!(:delete_edge, edge.type, target: ref)
 
       sql = new_sql
@@ -179,7 +188,8 @@ module Pglpg
 
     private
 
-    def write_edge(operation, edge_type, from, to, properties, attrs)
+    def write_edge(operation, edge_type, from, to, properties, attrs, valid_from, valid_to, key: nil)
+      validity = Temporal.bounds(edge_type, valid_from, valid_to, required: true)
       @graph.check_ref!(from, :node)
       @graph.check_ref!(to, :node)
       if edge_type.symmetric?
@@ -190,10 +200,12 @@ module Pglpg
         # Stored in canonical orientation, so either order names the same pair.
         from, to = to, from if from.id > to.id
       end
-      props = properties.transform_keys(&:to_sym)
+      props = prepare_key(edge_type, properties)
       json = edge_type.encode_properties(props)
       cols = encode_attrs(@graph.type.edge_columns, attrs, insert: true)
-      request = authorize!(operation, edge_type.name, from:, to:, properties: props, attrs:)
+      update_cols = cols + validity_columns(validity)
+      cols += validity_columns(edge_type.temporal? ? { valid_from: nil, valid_to: nil }.merge(validity) : {})
+      request = authorize!(operation, edge_type.name, from:, to:, key:, properties: props, attrs:, validity:)
 
       sql = new_sql
       sql << "INSERT INTO " << table(@graph.edges_table) << " AS tgt (type, source_id, target_id, properties"
@@ -221,17 +233,49 @@ module Pglpg
       # Endpoints stay locked against concurrent change until commit.
       sql << " FOR SHARE OF s, t"
       if operation == :upsert_edge
-        sql << " ON CONFLICT (source_id, target_id) WHERE type = "
+        expressions = if edge_type.key
+                        edge_type.key.expressions(@graph.connection)
+                      else
+                        ["source_id", "target_id", *(edge_type.pair_key&.expressions(@graph.connection) || [])]
+                      end
+        sql << " ON CONFLICT (" << expressions.join(", ") << ") WHERE type = "
         sql.literal(edge_type.name) << " DO UPDATE SET "
         set_properties(sql, "tgt.properties", json, null_keys(props), excluded: true)
-        set_columns(sql, cols, excluded: true)
-        sql << " WHERE "
+        set_columns(sql, update_cols, excluded: true)
+        # A property key must never redirect an existing relationship. Pair
+        # properties are immutable too, including when a global key arbitrates.
+        sql << " WHERE tgt.source_id = EXCLUDED.source_id AND tgt.target_id = EXCLUDED.target_id"
+        edge_type.unique_pair_properties.each do |property|
+          sql << " AND tgt.properties->"
+          sql.literal(property) << " = EXCLUDED.properties->"
+          sql.literal(property)
+        end
+        sql << " AND "
         existing_row(sql, :edge, request)
       end
       sql << " RETURNING id"
       ref(:edge, write(sql))
     end
 
+    def prepare_key(type, properties)
+      props = type.normalize_properties(properties)
+      key = type.key
+      return props unless key
+      unless key.generated?
+        raise ArgumentError, "#{type.name} has a caller-chosen key; use the trusted writer" unless @trusted
+
+        return props
+      end
+      if props.key?(key.property)
+        unless @trusted || (type.is_a?(Schema::NodeType) && key.scope)
+          raise ArgumentError, "#{type.name}.#{key.property} is a key and is generated"
+        end
+      else
+        props[key.property] = key.generate(type.name)
+      end
+      props
+    end
+
     def endpoint_labels(sql, source_label, target_label)
       sql << "(s.labels @> "
       sql.bind_text_array([source_label]) << " AND t.labels @> "
@@ -300,12 +344,17 @@ module Pglpg
       end
     end
 
+    def validity_columns(validity)
+      validity.map { |name, value| [Schema::Column.new(name, :date), value&.iso8601] }
+    end
+
     def null_keys(props) = props.select { |_, v| v.nil? }.keys.map(&:to_s)
 
-    def authorize!(operation, type, target: nil, from: nil, to: nil, key: nil, properties: {}, attrs: {})
+    def authorize!(operation, type, target: nil, from: nil, to: nil, key: nil, properties: {}, attrs: {}, validity: {}.freeze)
       request = WriteRequest.new(viewer: @context.viewer, operation:, type: type.to_sym, target:, from:, to:, key:,
                                  properties: properties.freeze, attrs: attrs.transform_keys(&:to_sym).freeze,
-                                 trusted: @trusted)
+                                 trusted: @trusted, validity:,
+                                 validity_supplied: Temporal::NAMES.to_h { [_1, validity.key?(_1)] }.freeze)
       raise WriteRejected unless @graph.write_policy.authorize?(request) == true
 
       request
@@ -348,7 +397,7 @@ module Pglpg
     rescue ActiveRecord::StatementInvalid => e
       case e.cause
       when PG::UniqueViolation, PG::ForeignKeyViolation, PG::RestrictViolation then raise WriteRejected, cause: nil
-      when PG::NotNullViolation, PG::CheckViolation then raise ValidationError, e.message
+      when PG::NotNullViolation, PG::CheckViolation then raise ValidationError, "write violates schema constraints", cause: nil
       else raise
       end
     end

data/lib/pglpg.rb

@@ -6,8 +6,10 @@ require "json"
 require_relative "pglpg/version"
 require_relative "pglpg/errors"
 require_relative "pglpg/configuration"
+require_relative "pglpg/temporal"
 require_relative "pglpg/schema/property"
 require_relative "pglpg/schema/element_type"
+require_relative "pglpg/schema/key"
 require_relative "pglpg/schema/node_type"
 require_relative "pglpg/schema/edge_type"
 require_relative "pglpg/schema/column"
@@ -21,6 +23,7 @@ require_relative "pglpg/graph"
 require_relative "pglpg/context"
 require_relative "pglpg/writer"
 require_relative "pglpg/query"
+require_relative "pglpg/match_parser"
 require_relative "pglpg/reachability"
 
 # Labeled property graphs stored in plain PostgreSQL tables.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pglpg
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Anton Fefilov
@@ -54,6 +54,7 @@ files:
 - lib/pglpg/element.rb
 - lib/pglpg/errors.rb
 - lib/pglpg/graph.rb
+- lib/pglpg/match_parser.rb
 - lib/pglpg/model.rb
 - lib/pglpg/model/base.rb
 - lib/pglpg/model/edge.rb
@@ -66,10 +67,12 @@ files:
 - lib/pglpg/schema/edge_type.rb
 - lib/pglpg/schema/element_type.rb
 - lib/pglpg/schema/graph_type.rb
+- lib/pglpg/schema/key.rb
 - lib/pglpg/schema/node_type.rb
 - lib/pglpg/schema/property.rb
 - lib/pglpg/sql.rb
 - lib/pglpg/storage.rb
+- lib/pglpg/temporal.rb
 - lib/pglpg/testing.rb
 - lib/pglpg/testing/leak_examples.rb
 - lib/pglpg/version.rb