pglpg 0.2.0 → 0.3.0

data/lib/pglpg/storage.rb

@@ -60,7 +60,7 @@ module Pglpg
             source_id bigint NOT NULL REFERENCES #{n} (id) ON DELETE RESTRICT,
             target_id bigint NOT NULL REFERENCES #{n} (id) ON DELETE RESTRICT,
             properties jsonb NOT NULL DEFAULT '{}',
-            #{columns_sql(connection, type.edge_columns)}created_at timestamptz NOT NULL DEFAULT now(),
+            #{type.temporal? ? "valid_from date, valid_to date, " : ""}#{columns_sql(connection, type.edge_columns)}created_at timestamptz NOT NULL DEFAULT now(),
             updated_at timestamptz NOT NULL DEFAULT now(),
             CHECK (jsonb_typeof(properties) = 'object')
           )
@@ -83,18 +83,29 @@ module Pglpg
       type.node_types.each_value do |t|
         has_label = "labels @> ARRAY[#{connection.quote(t.name.to_s)}]::text[]"
         if (key = t.own_key)
-          expressions = key.properties.map { "(properties->>#{connection.quote(_1.to_s)})" }.join(", ")
-          list << [:index, nodes_table, "key_#{t.name}_#{key.property}",
+          expressions = key.expressions(connection).join(", ")
+          list << [:index, nodes_table, "key_#{t.name}_#{key.property || key.properties.join("_")}",
                    "ON #{n} (#{expressions}) WHERE #{has_label}"]
         end
+        key_component_checks(list, connection, nodes_table, t, t.own_key, has_label) if t.own_key
         t.own_properties.each_value.select(&:required?).each do |p|
           list << [:check, nodes_table, "req_#{t.name}_#{p.name}", "NOT (#{has_label}) OR #{typed_check(connection, p)}"]
         end
       end
 
+      temporal_storage = type.temporal? || temporal_columns?(connection)
       type.edge_types.each_value do |t|
         is_type = "type = #{connection.quote(t.name.to_s)}"
-        list << [:index, edges_table, "pair_#{t.name}", "ON #{e} (source_id, target_id) WHERE #{is_type}"] if t.unique_pair?
+        list << [:check, edges_table, "validity_#{t.name}", temporal_check(connection, t)] if temporal_storage
+        if t.unique_tuple?
+          expressions = ["source_id", "target_id", *(t.pair_key&.expressions(connection) || [])].join(", ")
+          list << [:index, edges_table, "pair_#{t.name}", "ON #{e} (#{expressions}) WHERE #{is_type}"]
+        end
+        if t.key
+          list << [:index, edges_table, "key_#{t.name}_#{t.key.properties.join("_")}",
+                   "ON #{e} (#{t.key.expressions(connection).join(", ")}) WHERE #{is_type}"]
+        end
+        [t.key, t.pair_key].compact.each { key_component_checks(list, connection, edges_table, t, _1, is_type) }
         if t.symmetric?
           # Canonical orientation, so a pair is stored one way only (ADR-0008).
           list << [:check, edges_table, "sym_#{t.name}",
@@ -123,6 +134,28 @@ module Pglpg
       connection.transaction(requires_new: true) { synchronize_constraints(connection) }
     end
 
+    # Acknowledges only the named temporal types. The caller supplies any
+    # backfill, on the same locked connection, after checks are installed.
+    def enable_temporal!(types:, backfill: nil, connection: graph.connection)
+      names = Array(types).map { type.edge_type!(_1) }.uniq
+      raise ArgumentError, "types: needs temporal edge types" if names.empty? || names.any? { !_1.temporal? }
+      raise ArgumentError, "backfill must be callable" if backfill && !backfill.respond_to?(:call)
+
+      connection.transaction(requires_new: true) do
+        lock_temporal_table(connection)
+        check_temporal_columns!(connection, allow_missing: true)
+        acknowledge_temporal!(connection, names.map(&:name))
+        existing = connection.columns(edges_table).map(&:name)
+        Temporal::NAMES.each do |name|
+          next if existing.include?(name.to_s)
+          connection.execute("ALTER TABLE #{q(connection, edges_table)} ADD COLUMN #{q(connection, name)} date")
+        end
+        synchronize_constraints(connection, acknowledged: names.map(&:name))
+        backfill.call(connection) if backfill
+        nil
+      end
+    end
+
     # Rewrites stored label sets to match the graph type.
     def relabel!(connection = graph.connection)
       return 0 if concrete_types.empty?
@@ -148,7 +181,12 @@ module Pglpg
 
     private
 
-    def synchronize_constraints(connection)
+    def synchronize_constraints(connection, acknowledged: [])
+      if type.temporal? || temporal_columns?(connection)
+        lock_temporal_table(connection)
+        check_temporal_columns!(connection)
+        acknowledge_temporal!(connection, acknowledged)
+      end
       wanted = constraints(connection)
       existing = existing_constraints(connection)
       (existing.keys - wanted.keys).each do |name|
@@ -160,9 +198,70 @@ module Pglpg
         end
       end
       (wanted.keys - existing.keys).each { connection.execute(wanted[_1][:sql]) }
+      wanted.each_key do |name|
+        next unless existing[name] && existing[name][:validated] == false
+        connection.execute("ALTER TABLE #{q(connection, existing[name][:table])} VALIDATE CONSTRAINT #{q(connection, name)}")
+      end
       nil
     end
 
+    def lock_temporal_table(connection)
+      connection.execute("LOCK TABLE #{q(connection, edges_table)} IN ACCESS EXCLUSIVE MODE")
+    end
+
+    def temporal_columns?(connection)
+      return false unless connection.data_source_exists?(edges_table)
+      return false unless (connection.columns(edges_table).map(&:name) & Temporal::NAMES.map(&:to_s)).any?
+      return true if (type.edge_columns.keys & Temporal::NAMES).empty?
+
+      # Legacy application columns are allowed until explicitly migrated.
+      # Once metadata checks exist, redeclaring them as application columns
+      # must not silently bypass the temporal-disable transition.
+      existing_constraints(connection).values.any? do |info|
+        info[:table] == edges_table && Temporal::NAMES.all? { info[:definition]&.include?(_1.to_s) }
+      end
+    end
+
+    def check_temporal_columns!(connection, allow_missing: false)
+      if (type.edge_columns.keys & Temporal::NAMES).any?
+        raise TemporalMigrationRequired, "remove reserved validity metadata from application column declarations"
+      end
+      columns = connection.columns(edges_table).to_h { [_1.name, _1] }
+      Temporal::NAMES.each do |name|
+        column = columns[name.to_s]
+        if column.nil?
+          raise TemporalMigrationRequired, "run enable_temporal! to add #{name}" unless allow_missing
+        elsif column.type != :date || !column.null || column.default || column.default_function
+          raise TemporalMigrationRequired, "#{name} must be a nullable date column without a default; migrate incompatible columns explicitly"
+        end
+      end
+    end
+
+    def acknowledge_temporal!(connection, acknowledged)
+      existing = existing_constraints(connection)
+      type.edge_types.each_value do |t|
+        next unless t.temporal?
+        name = constraint_name(edges_table, "validity_#{t.name}", temporal_check(connection, t))
+        next if existing[name] && existing[name][:validated] != false
+        next if acknowledged.include?(t.name)
+        populated = connection.select_value("SELECT EXISTS (SELECT 1 FROM #{q(connection, edges_table)} WHERE type = #{connection.quote(t.name.to_s)})")
+        raise TemporalMigrationRequired, "acknowledge #{t.name} with enable_temporal!(types: [#{t.name.inspect}])" if populated
+      end
+    end
+
+    def temporal_check(connection, edge_type)
+      body = if edge_type.temporal?
+        checks = Temporal::NAMES.map do |name|
+          "(#{name} IS NULL OR #{name} BETWEEN DATE '0001-01-01' AND DATE '9999-12-31')"
+        end
+        checks << "(valid_from IS NULL OR valid_to IS NULL OR valid_from < valid_to)"
+        checks.join(" AND ")
+      else
+        "valid_from IS NULL AND valid_to IS NULL"
+      end
+      "NOT (type = #{connection.quote(edge_type.name.to_s)}) OR (#{body})"
+    end
+
     def type = graph.type
 
     def q(connection, name) = connection.quote_table_name(name)
@@ -192,6 +291,20 @@ module Pglpg
 
     # Rejects a missing key, JSON null and the wrong JSON type: a CHECK passes
     # on NULL, so the comparison is wrapped in IS TRUE.
+    def key_component_checks(list, connection, table, type, key, predicate)
+      key.properties.each do |name|
+        prop = type.properties.fetch(name)
+        value = "properties->#{connection.quote(name.to_s)}"
+        detail = case prop.type
+                 when :integer then "CASE WHEN jsonb_typeof(#{value}) = 'number' THEN (#{value})::numeric = trunc((#{value})::numeric) ELSE false END"
+                 when :enum then "properties->>#{connection.quote(name.to_s)} IN (#{prop.values.map { connection.quote(_1) }.join(", ")})"
+                 end
+        next unless detail
+
+        list << [:check, table, "keyval_#{type.name}_#{name}", "NOT (#{predicate}) OR (#{detail}) IS TRUE"]
+      end
+    end
+
     def typed_check(connection, prop)
       "(jsonb_typeof(properties->#{connection.quote(prop.name.to_s)}) = #{connection.quote(prop.json_type)}) IS TRUE"
     end
@@ -206,17 +319,17 @@ module Pglpg
     def existing_constraints(connection)
       prefixes = [nodes_table, edges_table].map { "pglpg\\_#{_1.gsub("_", "\\_")}\\_%" }
       rows = connection.select_rows(<<~SQL, "Pglpg constraints")
-        SELECT c.conname, 'check', t.relname FROM pg_constraint c JOIN pg_class t ON t.oid = c.conrelid
+        SELECT c.conname, 'check', t.relname, c.convalidated, pg_get_constraintdef(c.oid) FROM pg_constraint c JOIN pg_class t ON t.oid = c.conrelid
         WHERE t.relname IN (#{connection.quote(nodes_table)}, #{connection.quote(edges_table)})
           AND t.relnamespace = to_regnamespace(current_schema())
           AND (c.conname LIKE #{connection.quote(prefixes[0])} OR c.conname LIKE #{connection.quote(prefixes[1])})
         UNION ALL
-        SELECT i.indexname, 'index', i.tablename FROM pg_indexes i
+        SELECT i.indexname, 'index', i.tablename, true, NULL FROM pg_indexes i
         WHERE i.tablename IN (#{connection.quote(nodes_table)}, #{connection.quote(edges_table)})
           AND i.schemaname = current_schema()
           AND (i.indexname LIKE #{connection.quote(prefixes[0])} OR i.indexname LIKE #{connection.quote(prefixes[1])})
       SQL
-      rows.to_h { |name, kind, table| [name, { kind: kind.to_sym, table: }] }
+      rows.to_h { |name, kind, table, validated, definition| [name, { kind: kind.to_sym, table:, validated:, definition: }] }
     end
   end
 end

data/lib/pglpg/temporal.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Pglpg
+  # Internal validity metadata, deliberately separate from application columns.
+  module Temporal
+    NAMES = %i[valid_from valid_to].freeze
+    OMITTED = Object.new.freeze
+    MIN = Date.new(1, 1, 1, Date::GREGORIAN).freeze
+    MAX = Date.new(9999, 12, 31, Date::GREGORIAN).freeze
+
+    module_function
+
+    # PostgreSQL dates are proleptic Gregorian calendar dates. Interpret Ruby
+    # Dates by their civil fields, never by timezone or an implicit Time cast.
+    def date(value, error: ValidationError)
+      return nil if value.nil?
+      raise error, "expected an exact Date in 0001-01-01..9999-12-31" unless value.instance_of?(Date)
+
+      begin
+        result = Date.new(value.year, value.month, value.day, Date::GREGORIAN)
+      rescue Date::Error
+        raise error, "invalid Gregorian date"
+      end
+      raise error, "date outside 0001-01-01..9999-12-31" unless (MIN..MAX).cover?(result)
+
+      result.freeze
+    end
+
+    def bounds(type, lower, upper, required: false)
+      supplied = { valid_from: lower, valid_to: upper }.reject { |_, v| v.equal?(OMITTED) }
+      unless type.temporal?
+        raise ArgumentError, "#{type.name} is not temporal" unless supplied.empty?
+        return {}.freeze
+      end
+      raise ArgumentError, "temporal insert/upsert requires valid_from:" if required && lower.equal?(OMITTED)
+
+      result = supplied.transform_values { date(_1) }
+      validate_interval!(result[:valid_from], result[:valid_to])
+      result.freeze
+    end
+
+    def validate_interval!(lower, upper)
+      raise ValidationError, "valid_from must precede valid_to" if lower && upper && lower >= upper
+    end
+  end
+end

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

@@ -69,6 +69,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.3.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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pglpg
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Anton Fefilov
@@ -66,10 +66,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