tina4ruby 3.13.110 → 3.13.112

data/lib/tina4/drivers/ultipa_graph_driver.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+# Ultipa graph adapter — the portable core built in GQL over tina4-ultipa.
+#
+# Wraps the standalone +tina4-ultipa+ gem (an OPTIONAL dependency — required
+# here, so +require "tina4/graph"+ stays driver-free). The portable
+# node/edge/traverse surface is expressed in Ultipa GQL on top of the driver's
+# +query+/+execute+; raw +query+/+execute+ send GQL straight through.
+#
+# GQL note: the exact statements are verified against the live Ultipa community
+# edition on the lab (no mocks). Ultipa node ids come back as UUID strings; edge
+# ids need EDGE_ID enabled on the graph (a one-time per-graph setting the lab
+# provisions).
+
+# The gem is optional: this require is what makes a missing driver surface as the
+# actionable install error in GraphDatabase.create.
+require "tina4_ultipa"
+
+module Tina4
+  module Drivers
+    class UltipaGraphDriver < Tina4::GraphAdapter
+      # nil (unbounded) is mapped to a very large finite deadline for the gRPC
+      # driver, whose connect deadline is Time.now + connect_timeout (a 0 there
+      # would mean "do not wait", not "wait forever").
+      UNBOUNDED_CONNECT_TIMEOUT = 315_360_000 # ~10 years
+
+      def initialize(graph_url, username: "", password: "")
+        @url = graph_url
+        @last_error = nil
+        timeout = Tina4.resolve_graph_connect_timeout
+        @client = Tina4Ultipa::Client.new(
+          host: graph_url.host,
+          port: graph_url.port,
+          username: graph_url.username || (username unless username.to_s.empty?),
+          password: graph_url.password || (password unless password.to_s.empty?),
+          graph: graph_url.graph,
+          connect_timeout: timeout.nil? ? UNBOUNDED_CONNECT_TIMEOUT : timeout,
+          use_tls: graph_url.use_tls,
+        )
+      end
+
+      # -- connection + raw pass-through -----------------------------------
+
+      def query(text, params = nil)
+        result = run(text, params: params, read_only: true)
+        Tina4::GraphResult.new(records: result.dicts, columns: result.columns)
+      end
+
+      def execute(text, params = nil)
+        result = run(text, params: params, read_only: false)
+        Tina4::GraphResult.new(records: result.dicts, columns: result.columns)
+      end
+
+      # -- portable node/edge/traverse core (GQL) --------------------------
+
+      def add_node(label, properties = nil)
+        prop_map, params = prop_clause(properties)
+        gql = "INSERT (n:`#{label}` #{prop_map}) " \
+              "RETURN id(n) AS id, labels(n) AS labels, properties(n) AS props"
+        rows = run(gql, params: params, read_only: false).dicts
+        node_from_row(rows[0])
+      end
+
+      def add_edge(from_id, to_id, type, properties = nil)
+        # id(e) requires EDGE_ID enabled on the Ultipa graph
+        # (`ALTER GRAPH <g> SET EDGE_ID ENABLED`), a one-time per-graph setting.
+        prop_map, params = prop_clause(properties)
+        params["from_id"] = from_id
+        params["to_id"] = to_id
+        gql = "MATCH (a), (b) WHERE id(a) = $from_id AND id(b) = $to_id " \
+              "INSERT (a)-[e:`#{type}` #{prop_map}]->(b) " \
+              "RETURN id(e) AS id, type(e) AS type, id(a) AS f, id(b) AS t, " \
+              "properties(e) AS props"
+        rows = run(gql, params: params, read_only: false).dicts
+        return nil if rows.empty?
+
+        row = rows[0]
+        Tina4::GraphEdge.new(
+          id: row["id"], type: row["type"], from: row["f"], to: row["t"],
+          properties: row["props"] || {},
+        )
+      end
+
+      def get_node(node_id)
+        gql = "MATCH (n) WHERE id(n) = $id " \
+              "RETURN id(n) AS id, labels(n) AS labels, properties(n) AS props"
+        rows = run(gql, params: { "id" => node_id }, read_only: true).dicts
+        node_from_row(rows[0])
+      end
+
+      def update_node(node_id, properties)
+        properties ||= {}
+        sets = properties.keys.map { |key| "n.#{key} = $p_#{key}" }.join(", ")
+        params = {}
+        properties.each { |key, value| params["p_#{key}"] = value }
+        params["id"] = node_id
+        gql = "MATCH (n) WHERE id(n) = $id SET #{sets} " \
+              "RETURN id(n) AS id, labels(n) AS labels, properties(n) AS props"
+        rows = run(gql, params: params, read_only: false).dicts
+        node_from_row(rows[0])
+      end
+
+      def delete_node(node_id)
+        run("MATCH (n) WHERE id(n) = $id DETACH DELETE n",
+            params: { "id" => node_id }, read_only: false)
+        true
+      end
+
+      def neighbors(node_id, direction: "both", edge_type: nil, limit: 100)
+        edge = edge_type ? ":`#{edge_type}`" : ""
+        pattern = case direction
+                  when "out" then "(n)-[#{edge}]->(m)"
+                  when "in" then "(n)<-[#{edge}]-(m)"
+                  else "(n)-[#{edge}]-(m)"
+                  end
+        gql = "MATCH #{pattern} WHERE id(n) = $id " \
+              "RETURN DISTINCT id(m) AS id, labels(m) AS labels, properties(m) AS props " \
+              "LIMIT #{limit.to_i}"
+        rows = run(gql, params: { "id" => node_id }, read_only: true).dicts
+        rows.map { |row| node_from_row(row) }
+      end
+
+      def traverse(start_id, depth: 1, direction: "both", edge_type: nil, limit: 1000)
+        # Ultipa GQL uses the ISO quantified-path form `-[]->{1,N}`, NOT Cypher's
+        # `-[*1..N]->` (which is a parse error on gqldb).
+        edge = edge_type ? ":`#{edge_type}`" : ""
+        quant = "{1,#{depth.to_i}}"
+        pattern = case direction
+                  when "out" then "(n)-[#{edge}]->#{quant}(m)"
+                  when "in" then "(n)<-[#{edge}]-#{quant}(m)"
+                  else "(n)-[#{edge}]-#{quant}(m)"
+                  end
+        gql = "MATCH #{pattern} WHERE id(n) = $start " \
+              "RETURN DISTINCT id(m) AS id, labels(m) AS labels, properties(m) AS props " \
+              "LIMIT #{limit.to_i}"
+        rows = run(gql, params: { "start" => start_id }, read_only: true).dicts
+        rows.map { |row| node_from_row(row) }
+      end
+
+      def close
+        @client.close
+      end
+
+      private
+
+      # Run a GQL statement, wrapping the driver's connect/query errors as the
+      # framework's GraphConnectTimeout / GraphError. ConnectError is rescued
+      # FIRST because it subclasses the driver's Error.
+      def run(gql, params: nil, read_only: true)
+        @client.query(gql, params: params, read_only: read_only)
+      rescue Tina4Ultipa::ConnectError => e
+        @last_error = e.message
+        raise Tina4::GraphConnectTimeout,
+              "Graph connect to #{@url.host}:#{@url.port} timed out " \
+              "(TINA4_GRAPH_CONNECT_TIMEOUT). Raise TINA4_GRAPH_CONNECT_TIMEOUT if the " \
+              "server is simply slow, or set it to 0 to wait indefinitely. Cause: #{e.message}"
+      rescue Tina4Ultipa::Error => e
+        @last_error = e.message
+        raise Tina4::GraphError, e.message
+      end
+
+      # Build a GQL property map `{k1: $p_k1, ...}` + the param hash for it.
+      #
+      # Params are BOUND (never interpolated), matching the relational
+      # ?-placeholder rule. Keys are namespaced (`p_`) so they never collide with
+      # an id param.
+      def prop_clause(properties)
+        properties ||= {}
+        return ["{}", {}] if properties.empty?
+
+        pairs = properties.keys.map { |key| "#{key}: $p_#{key}" }.join(", ")
+        params = {}
+        properties.each { |key, value| params["p_#{key}"] = value }
+        ["{#{pairs}}", params]
+      end
+
+      def node_from_row(row)
+        return nil if row.nil?
+
+        Tina4::GraphNode.new(
+          id: row["id"], labels: row["labels"], properties: row["props"] || {},
+        )
+      end
+    end
+  end
+end

data/lib/tina4/graph.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require "uri"
+
+# Tina4 graph data layer — a URL-selected graph database, shaped like Database.
+#
+# Feature 139. One factory (+GraphDatabase.create+ / +.from_env+), one portable
+# node/edge/traverse surface plus a raw +query+/+execute+ pass-through, and
+# neutral +GraphNode+ / +GraphEdge+ / +GraphResult+ shapes — the exact mirror of
+# the relational +Database+ layer, for graph engines (Ultipa first). Engine
+# drivers are OPTIONAL and loaded only on first use, so the zero-dependency core
+# is preserved.
+#
+# See ADR-0059 and tina4-documentation/plan/v3/features/139-graph-databases.md.
+module Tina4
+  # The graph connect bound — sibling of TINA4_DATABASE_CONNECT_TIMEOUT.
+  GRAPH_CONNECT_TIMEOUT_VAR = "TINA4_GRAPH_CONNECT_TIMEOUT"
+  DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS = 10.0
+
+  # Seconds a graph connect may block; +nil+ means unbounded (a value <= 0).
+  #
+  # Mirrors the relational connect-timeout resolver: a value <= 0 disables the
+  # bound, a non-number warns and falls back to the default rather than waiting
+  # forever.
+  def self.resolve_graph_connect_timeout
+    raw = (ENV[GRAPH_CONNECT_TIMEOUT_VAR] || "").strip
+    return DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS if raw.empty?
+
+    begin
+      seconds = Float(raw)
+    rescue ArgumentError, TypeError
+      Tina4::Log.warning(
+        "#{GRAPH_CONNECT_TIMEOUT_VAR}=#{raw.inspect} is not a number of seconds — " \
+        "bounding graph connects at the #{DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS.to_i}s default instead",
+      )
+      return DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS
+    end
+    seconds <= 0 ? nil : seconds
+  end
+
+  # A graph operation failed (bad statement, engine error).
+  class GraphError < StandardError; end
+
+  # A graph connect exceeded TINA4_GRAPH_CONNECT_TIMEOUT.
+  #
+  # A subclass of +GraphError+, so a +rescue GraphError+ catches a connect
+  # timeout too — mirroring the driver's ConnectError < Error hierarchy.
+  class GraphConnectTimeout < GraphError; end
+
+  # A parsed graph connection URL — the DatabaseUrl sibling for graph engines.
+  #
+  # +engine+ is the CANONICAL name the factory selects an adapter by; a scheme
+  # alias resolves to its engine here. bolt/neo4j/memgraph all speak Bolt/Cypher
+  # and share ONE adapter ("bolt"); the engine label only tunes per-engine
+  # defaults.
+  class GraphUrl
+    SCHEME_ENGINE = {
+      "ultipa" => "ultipa",
+      "ultipas" => "ultipa", # TLS variant
+      "neo4j" => "bolt",
+      "neo4j+s" => "bolt",
+      "bolt" => "bolt",
+      "bolt+s" => "bolt",
+      "memgraph" => "bolt",
+      "arango" => "arango",
+      "arangodb" => "arango",
+    }.freeze
+
+    # Default port per engine when the URL omits one.
+    ENGINE_DEFAULT_PORT = {
+      "ultipa" => 60_061,
+      "bolt" => 7687,
+      "arango" => 8529,
+    }.freeze
+
+    attr_reader :raw, :scheme, :engine, :host, :port, :graph, :username,
+                :password, :params, :use_tls
+
+    def initialize(url)
+      @raw = url
+      parsed = begin
+        URI.parse(url.to_s)
+      rescue URI::InvalidURIError
+        raise ArgumentError, "GraphUrl: Invalid URL format — expected scheme://host:port/graph"
+      end
+
+      scheme = (parsed.scheme || "").downcase
+      engine = SCHEME_ENGINE[scheme]
+      if engine.nil?
+        raise ArgumentError,
+              "GraphUrl: Unsupported graph URL scheme '#{scheme}'. Supported: " \
+              "#{SCHEME_ENGINE.keys.sort.join(', ')} (e.g. ultipa://host:60061/mygraph)."
+      end
+
+      @scheme = scheme
+      @engine = engine
+      @host = parsed.host && !parsed.host.empty? ? parsed.host : "localhost"
+      @port = parsed.port || ENGINE_DEFAULT_PORT[engine]
+      # The path is the graph/database name (one leading slash stripped).
+      graph = (parsed.path || "").sub(%r{\A/}, "")
+      @graph = graph.empty? ? nil : graph
+      @username = parsed.user ? URI.decode_www_form_component(parsed.user) : nil
+      @password = parsed.password ? URI.decode_www_form_component(parsed.password) : nil
+      @params = URI.decode_www_form(parsed.query || "").to_h
+      # TLS if the scheme says so (…s) or ?tls=1.
+      @use_tls = scheme.end_with?("s") || %w[1 true].include?(@params["tls"])
+    end
+
+    # host:port/graph — for messages, never carrying credentials.
+    def dsn
+      target = @port ? "#{@host}:#{@port}" : @host
+      @graph ? "#{target}/#{@graph}" : target
+    end
+
+    # Parse the configured URL, or +nil+ when the variable is not set.
+    def self.from_env(env_key = "TINA4_GRAPH_URL")
+      url = (ENV[env_key] || "").strip
+      url.empty? ? nil : new(url)
+    end
+  end
+
+  # An engine-neutral vertex: id, labels, properties.
+  class GraphNode
+    attr_reader :id, :labels, :properties
+
+    def initialize(id:, labels: nil, properties: nil)
+      @id = id
+      @labels = Array(labels)
+      @properties = properties || {}
+    end
+
+    def to_h
+      { "id" => @id, "labels" => @labels, "properties" => @properties }
+    end
+
+    def inspect
+      "#<Tina4::GraphNode id=#{@id.inspect} labels=#{@labels.inspect}>"
+    end
+  end
+
+  # An engine-neutral edge: id, type, from/to node ids, properties.
+  class GraphEdge
+    attr_reader :id, :type, :from, :to, :properties
+
+    def initialize(id:, type:, from:, to:, properties: nil)
+      @id = id
+      @type = type
+      @from = from
+      @to = to
+      @properties = properties || {}
+    end
+
+    def to_h
+      { "id" => @id, "type" => @type, "from" => @from, "to" => @to,
+        "properties" => @properties }
+    end
+
+    def inspect
+      "#<Tina4::GraphEdge id=#{@id.inspect} type=#{@type.inspect} " \
+        "#{@from.inspect}->#{@to.inspect}>"
+    end
+  end
+
+  # A raw-query result — records + columns, same shape as DatabaseResult.
+  class GraphResult
+    include Enumerable
+
+    attr_reader :records, :columns
+
+    def initialize(records: nil, columns: nil)
+      @records = records || []
+      @columns = columns || []
+    end
+
+    def to_a
+      @records
+    end
+
+    def scalar
+      return nil if @records.empty?
+
+      first = @records[0]
+      if first.is_a?(Hash)
+        first.values.first
+      elsif first.is_a?(Array)
+        first.empty? ? nil : first[0]
+      else
+        first
+      end
+    end
+
+    def each(&block)
+      @records.each(&block)
+    end
+
+    def length
+      @records.length
+    end
+    alias size length
+  end
+
+  # The one surface every graph engine implements. Raising stubs — a driver that
+  # does not override a method fails LOUDLY, naming itself and the method.
+  class GraphAdapter
+    # -- portable node/edge/traverse core ---------------------------------
+    def add_node(_label, _properties = nil)
+      not_implemented(__method__)
+    end
+
+    def add_edge(_from_id, _to_id, _type, _properties = nil)
+      not_implemented(__method__)
+    end
+
+    def get_node(_node_id)
+      not_implemented(__method__)
+    end
+
+    def update_node(_node_id, _properties)
+      not_implemented(__method__)
+    end
+
+    def delete_node(_node_id)
+      not_implemented(__method__)
+    end
+
+    def neighbors(_node_id, direction: "both", edge_type: nil, limit: 100)
+      not_implemented(__method__)
+    end
+
+    def traverse(_start_id, depth: 1, direction: "both", edge_type: nil, limit: 1000)
+      not_implemented(__method__)
+    end
+
+    # -- raw pass-through (engine-native dialect) -------------------------
+    def query(_text, _params = nil)
+      not_implemented(__method__)
+    end
+
+    def execute(_text, _params = nil)
+      not_implemented(__method__)
+    end
+
+    # -- lifecycle --------------------------------------------------------
+    def close
+      not_implemented(__method__)
+    end
+
+    # Cause of the last failed operation, or +nil+.
+    def get_error
+      @last_error
+    end
+
+    private
+
+    def not_implemented(method_name)
+      raise NotImplementedError, "#{self.class.name} does not implement #{method_name}"
+    end
+  end
+
+  # The URL-selected graph factory — the GraphDatabase sibling of Database.
+  class GraphDatabase
+    # engine -> { require:, class:, package:, install: }. Selected lazily so
+    # requiring +tina4/graph+ pulls in NO engine driver.
+    #
+    # ultipa wraps the OPTIONAL +tina4-ultipa+ gem (a missing gem surfaces as the
+    # actionable install error). bolt (Neo4j/Memgraph) and arango are pure-Ruby
+    # over stdlib (+socket+ / +Net::HTTP+) — zero third-party gems, so their
+    # +require+ always succeeds and the install line is never reached; it stays
+    # declared for a uniform registry shape.
+    ENGINE_ADAPTERS = {
+      "ultipa" => {
+        require: "tina4/drivers/ultipa_graph_driver",
+        class: "Tina4::Drivers::UltipaGraphDriver",
+        package: "tina4-ultipa",
+        install: "gem install tina4-ultipa   # or add gem \"tina4-ultipa\" to your Gemfile",
+      },
+      "bolt" => {
+        require: "tina4/drivers/bolt_graph_driver",
+        class: "Tina4::Drivers::BoltGraphDriver",
+        package: "tina4ruby (built-in, stdlib socket)",
+        install: "no install needed — the Bolt driver ships with tina4ruby",
+      },
+      "arango" => {
+        require: "tina4/drivers/arango_graph_driver",
+        class: "Tina4::Drivers::ArangoGraphDriver",
+        package: "tina4ruby (built-in, stdlib Net::HTTP)",
+        install: "no install needed — the ArangoDB driver ships with tina4ruby",
+      },
+    }
+
+    # Parse the URL, pick the engine adapter, connect lazily.
+    #
+    # The engine driver is required only here (first use of that engine); if it
+    # is absent the error names the package and the install command.
+    def self.create(url, username: "", password: "")
+      graph_url = GraphUrl.new(url)
+      registration = ENGINE_ADAPTERS[graph_url.engine]
+      if registration.nil?
+        raise GraphError,
+              "No graph adapter for engine '#{graph_url.engine}' yet " \
+              "(scheme '#{graph_url.scheme}'). Available: " \
+              "#{ENGINE_ADAPTERS.keys.sort.join(', ')}."
+      end
+
+      begin
+        require registration[:require]
+      rescue LoadError => e
+        # The adapter file requires its driver gem at the top; a missing gem
+        # surfaces here as an actionable install error, never a bare LoadError.
+        raise GraphError,
+              "The graph driver for '#{graph_url.engine}' is not installed " \
+              "(#{registration[:package]}). Install it with:\n    #{registration[:install]}",
+          cause: e
+      end
+
+      adapter_class = Object.const_get(registration[:class])
+      adapter_class.new(graph_url, username: username, password: password)
+    end
+
+    # Build from TINA4_GRAPH_URL (+ TINA4_GRAPH_USERNAME/_PASSWORD).
+    def self.from_env(env_key: "TINA4_GRAPH_URL")
+      url = ENV[env_key]
+      return nil if url.nil? || url.strip.empty?
+
+      create(url,
+             username: ENV["TINA4_GRAPH_USERNAME"].to_s,
+             password: ENV["TINA4_GRAPH_PASSWORD"].to_s)
+    end
+  end
+end