diamond-orm 0.1.0

data/lib/diamond.rb

@@ -0,0 +1,436 @@
+# shareable_constant_value: literal
+#
+# makes every top-level constant declared below shareable across Ractors.
+# `Users` etc. become references to shareable objects, so a Ractor can
+# resolve `Users` without going through any global mutable state.
+#
+# After this file runs, every Diamond::* constant (and every public
+# constant nested under Diamond::Parser / ::Compiler / ::Domains / ::DSL /
+# ::Operators) is registered via Module#autoload — referencing one
+# loads the corresponding file from gems/diamond/lib on first use.
+# The eager top-half defines the error classes, RACTOR_KEYS, IDENT_RE
+# and the global const_missing prepend, all of which must exist before
+# any user code touches a Diamond table.
+
+require 'extralite'
+require 'prism'
+require 'did_you_mean'
+
+module Diamond
+  class Error < StandardError; end
+  class TableNotFound < Error; end
+  class RecordNotFound < Error; end
+  class InertObjectError < Error; end
+
+  class UnknownColumnError < StandardError
+    def self.build(schema, name)
+      cols = schema[:columns].map(&:to_s)
+
+      spell_checker = DidYouMean::SpellChecker.new(dictionary: cols)
+      suggestions = spell_checker.correct(name.to_s)
+
+      message = "Table has no column '#{name}'."
+      message += " Did you mean '#{suggestions.first}'?" unless suggestions.empty?
+
+      new(message)
+    end
+  end
+
+  # Central registry of keys used to stash per-Ractor state in
+  # `Ractor.current[...]`. One place so the namespace stays grep-able and
+  # collisions are impossible. Each consumer module has a constant pointing
+  # here: `Diamond::RACTOR_KEYS[:engine]`, etc.
+  RACTOR_KEYS = {
+    engine:           :_diamond_engine,
+    parser_caches:    :_diamond_parser_caches,
+    struct_caches:    :_diamond_struct_caches,
+    where_ops:        :_diamond_where_ops,
+    derive_ops:       :_diamond_derive_ops,
+    compiler_ops:     :_diamond_compiler_ops,
+    finder_cols:      :_diamond_finder_cols
+  }.freeze
+
+  IDENT_RE = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/.freeze
+
+  @db_path = nil
+
+  # Engine tuning inherited by lazily-booted worker-Ractor engines
+  # (see .engine). Engine-safe keys only: on_progress procs can never
+  # cross Ractors and auto_fiber_yield is wake_up-only, so neither is
+  # stored here. Always a frozen Hash of shareable values.
+  @diamond_opts = {}.freeze
+
+  # Autoloads — one entry per public constant. Loading :Parser / :Compiler
+  # / :Domains / :DSL / :Operators pulls in the namespace AND its sibling
+  # implementation files via require_relative inside each namespace-opener
+  # (see diamond/parser.rb, diamond/compiler/base.rb, diamond/domains/dql.rb).
+  autoload :VERSION,       'diamond/version'
+  autoload :Operator,      'diamond/operator'
+  autoload :Engine,        'diamond/engine'
+  autoload :Changeset,     'diamond/changeset'
+  autoload :AST,           'diamond/ast'
+  autoload :NullTable,     'diamond/null_table'
+  autoload :StructJSON,    'diamond/struct_factory'
+  autoload :StructFactory, 'diamond/struct_factory'
+  autoload :Parser,        'diamond/parser'
+  autoload :Compiler,      'diamond/compiler/base'
+  autoload :Domains,       'diamond/domains/dql'
+  autoload :DSL,           'diamond/dsl/default'
+  autoload :Operators,     'diamond/operators/like'
+  autoload :Table,         'diamond/table'
+  autoload :QueryObject,   'diamond/query_object'
+  autoload :Cursor,        'diamond/cursor'
+  autoload :JsonString,    'diamond/json_string'
+end
+
+# const_missing is kept as a fallback only. wake_up's bind_tables! already
+# defines every schema table; this hook only fires for typo'd constants
+# (where Diamond can't help) or in older code paths. Either way it raises
+# NameError cleanly instead of silently inventing proxies.
+#
+# Prepended to Module — must run exactly once at load time so every
+# later const lookup goes through it.
+module DiamondConstMissing
+  def const_missing(name)
+    table_sym = name.to_s.downcase.to_sym
+
+    # This hook is prepended to every Module, so it fires for missing
+    # constants anywhere (not just table proxies). When Diamond was
+    # never woken, the engine cannot boot (nil path) — degrade to a
+    # clean NameError instead of leaking a TypeError from Extralite.
+    engine = begin
+      Diamond.engine
+    rescue StandardError
+      nil
+    end
+
+    if engine && engine.schema_cache.key?(table_sym)
+      # schema had this table but it wasn't eager-bound (e.g., bind_tables!
+      # ran before this table existed). bind it now.
+      proxy = Diamond::Table.new(table_sym).freeze
+      Object.const_set(name, proxy)
+      Diamond.note_bound_table(name)
+      proxy
+    else
+      super
+    end
+  end
+end
+Module.prepend(DiamondConstMissing)
+
+module Diamond
+  def self.quote_ident(name)
+    "\"#{name.to_s.gsub('"', '""')}\""
+  end
+
+  def self.validate_ident!(name, what = "identifier")
+    unless name.to_s.match?(IDENT_RE)
+      raise ArgumentError, "invalid #{what} #{name.inspect}: must match #{IDENT_RE.inspect}"
+    end
+    name
+  end
+
+  # Names we've bound as frozen constants, so a later wake_up can unbind them
+  # instead of leaving them pinned to the dead engine's schema.
+  @bound_tables = []
+
+  # Phase 7 + Fiber amendment: when waking up, auto-detect whether a
+  # Fiber::Scheduler is running and, if so, install an on_progress hook
+  # that yields to the scheduler while SQLite is waiting on I/O. This
+  # turns Diamond into a non-blocking database when used inside Async /
+  # Polyphony / any Fiber.scheduler-driven runtime.
+  def self.wake_up(db_path, busy_timeout: nil, gvl_release_threshold: nil,
+                   on_progress: nil, extensions: [], auto_fiber_yield: true)
+    @db_path = db_path.freeze
+    # Stash engine-safe tuning for worker Ractors that boot lazily via
+    # .engine long after this returns. Deep-frozen (dup-freeze each
+    # extension path so caller-owned strings are never mutated) and
+    # shareable, so cross-Ractor reads never trip isolation.
+    @diamond_opts = {
+      busy_timeout: busy_timeout,
+      gvl_release_threshold: gvl_release_threshold,
+      extensions: Array(extensions).map { |p| p.dup.freeze }.freeze
+    }.freeze
+
+    # Phase 7: the caller may pass a custom on_progress; otherwise we
+    # build one that yields to the running Fiber::Scheduler when present.
+    # auto_fiber_yield=false opts out (e.g. for tests) — passed through
+    # as `false` so Engine#initialize can tell "explicitly none" apart
+    # from "absent" (absent + scheduler present would auto-install).
+    progress = on_progress
+    if progress.nil?
+      if auto_fiber_yield && Fiber.scheduler
+        progress = method(:fiber_yield_on_progress)
+      elsif !auto_fiber_yield
+        progress = false
+      end
+    end
+
+    # Main Ractor initializes its connection immediately for backward compat
+    # (so existing tests that touch `Diamond.engine` after wake_up still work).
+    Ractor.current[Diamond::RACTOR_KEYS[:engine]] = Engine.new(
+      @db_path,
+      busy_timeout: busy_timeout,
+      gvl_release_threshold: gvl_release_threshold,
+      on_progress: progress,
+      extensions: extensions
+    ).freeze!
+
+    # including twice is a no-op for ancestors but still busts ruby's global
+    # method cache. guard it so per-test wake_up stays cheap.
+    unless Diamond::Table.include?(Diamond::DSL::Default)
+      Diamond::Table.include(Diamond::DSL::Default)
+      Diamond::Table.include(Diamond::Domains::DQL)
+      Diamond::Table.include(Diamond::Domains::DML)
+      Diamond::Table.include(Diamond::Domains::DynamicFinders)
+
+      Diamond::QueryObject.include(Diamond::DSL::Default)
+      Diamond::QueryObject.include(Diamond::Domains::DQL)
+      Diamond::QueryObject.include(Diamond::Domains::DML)
+      Diamond::QueryObject.include(Diamond::Domains::DynamicFinders)
+
+      Diamond.extend(Diamond::Domains::DDL)
+      Diamond.extend(Diamond::Domains::CTE)
+      Diamond.extend(Diamond::DSL::Default)
+    end
+
+    rebind_tables!
+    bind_tables!
+  end
+
+  # Phase 7 Fiber-amendment hook. Called by Extralite while waiting on
+  # SQLite I/O. `Kernel.sleep(0)` dispatches to the running
+  # Fiber::Scheduler's kernel_sleep (a real yield) when inside a
+  # fiber, and is a fast no-op on plain threads — so one body covers
+  # both worlds with no scheduler sniffing here (presence was already
+  # checked at install time). Ends falsy; the return value is never
+  # an abort signal. `Kernel.` prefix is mandatory: bare `sleep`
+  # would resolve to Diamond.sleep itself and recurse forever.
+  # Defaulted arg: Extralite 3.0.1 invokes the handler with zero
+  # arguments (the documented busy flag is not passed).
+  def self.fiber_yield_on_progress(_busy = nil)
+    Kernel.sleep(0)
+    nil
+  end
+
+  # drop old constants so the next reference re-resolves (or raises
+  # NameError) instead of serving the dead engine's table.
+  def self.rebind_tables!
+    @bound_tables.each do |const_name|
+      Object.send(:remove_const, const_name) if Object.const_defined?(const_name, false)
+    end
+    @bound_tables.clear
+  end
+
+  # eager-bind every schema table as a frozen top-level constant. Ractor-safe
+  # because the Table object is immutable after .freeze, and the engine's
+  # schema cache is frozen (see Engine#freeze!).
+  def self.bind_tables!
+    return unless Ractor.current[Diamond::RACTOR_KEYS[:engine]]
+    Ractor.current[Diamond::RACTOR_KEYS[:engine]].schema_cache.each_key do |table_sym|
+      const_name = table_sym.to_s.split('_').map(&:capitalize).join
+      next if Object.const_defined?(const_name, false)
+      proxy = Table.new(table_sym).freeze
+      Object.const_set(const_name, proxy)
+      @bound_tables << const_name unless @bound_tables.include?(const_name)
+    end
+  end
+
+  def self.note_bound_table(name)
+    @bound_tables << name unless @bound_tables.include?(name)
+  end
+
+  # Per-Ractor engine. Each Ractor opens its own Extralite::Database connection
+  # lazily on first access. The shared schema/FK caches are loaded from the
+  # same DB file/connection-string, so every Ractor sees the same logical
+  # schema — but live query execution goes through each Ractor's own connection.
+  def self.engine
+    # Workers inherit the main Ractor's engine tuning (busy_timeout,
+    # gvl_release_threshold, extensions) stashed at wake_up. Hooks are
+    # deliberately NOT inherited: procs can't cross Ractors, and each
+    # engine re-runs presence detection for its own Ractor (which has
+    # no scheduler, so no hook — same as before).
+    engine = Ractor.current[Diamond::RACTOR_KEYS[:engine]] ||= Engine.new(@db_path, **@diamond_opts).freeze!
+    # Late-bind the yield hook if a scheduler appeared after this
+    # engine booted (no-op when already installed, opted out, or
+    # schedulerless — see Engine#sync_scheduler_hook!).
+    engine.sync_scheduler_hook!
+    engine
+  end
+
+  # Phase 7: backup to a file or another Engine. Block (if given) gets
+  # called with (remaining, total_pages) on each step.
+  def self.backup(target, &block)
+    engine.db.backup(target, &block)
+  end
+
+  # Phase 7: track changes to the given tables inside a block. Returns
+  # a Diamond::Changeset wrapper around the underlying Extralite
+  # changeset. Use .apply(target_db) to replay on another connection,
+  # .invert to undo, .to_blob / .load(blob) to serialize over the wire.
+  #
+  # Requires the extralite-bundle build (sqlite3 session extension).
+  # Plain extralite 3.0.1 does NOT include track_changes — calling
+  # here raises FeatureNotAvailableError.
+  def self.track_changes(*tables, &block)
+    raise ArgumentError, "track_changes requires a block" unless block
+    unless defined?(Extralite::Changeset)
+      raise FeatureNotAvailableError,
+            "track_changes requires extralite-bundle (sqlite3 session extension). " \
+            "Install with `gem install extralite-bundle` and activate it with " \
+            "`gem \"extralite-bundle\"` before `require \"extralite\"`."
+    end
+    # NOTE: the block must run *inside* Changeset#track — that method
+    # creates the sqlite session, yields, materializes via
+    # sqlite3session_changeset, and tears down in ensure. The db-level
+    # track_changes never yields, so calling it blockless dies in
+    # rb_yield (LocalJumpError) and calling it first would leave the
+    # session closed before the block runs (empty changeset).
+    raw = Extralite::Changeset.new
+    raw.track(engine.db, tables, &block)
+    Diamond::Changeset.new(raw)
+  end
+
+  RUNTIME_STATUS_CODES = {
+    memory_used:        Extralite::SQLITE_STATUS_MEMORY_USED,
+    pagecache_used:     Extralite::SQLITE_STATUS_PAGECACHE_USED,
+    pagecache_overflow: Extralite::SQLITE_STATUS_PAGECACHE_OVERFLOW,
+    scratch_used:       Extralite::SQLITE_STATUS_SCRATCH_USED,
+    scratch_overflow:   Extralite::SQLITE_STATUS_SCRATCH_OVERFLOW,
+    malloc_size:        Extralite::SQLITE_STATUS_MALLOC_SIZE,
+    parser_stack:       Extralite::SQLITE_STATUS_PARSER_STACK
+  }.freeze
+
+  # Phase 7: run a query with a wall-clock timeout. After `seconds`, a
+  # background timer calls Diamond.engine.db.interrupt; the query raises
+  # Extralite::InterruptError which we re-wrap as our own error class.
+  def self.query_with_timeout(seconds, &block)
+    raise ArgumentError, "query_with_timeout requires a block" unless block
+    return block.call if seconds.nil? || seconds <= 0
+
+    timer = Thread.new do
+      Kernel.sleep(seconds)
+      Diamond.engine.db.interrupt
+    end
+    begin
+      block.call
+    rescue Extralite::InterruptError => e
+      raise QueryInterruptedError, "Query interrupted after #{seconds}s: #{e.message}"
+    ensure
+      timer.kill rescue nil
+      timer.join rescue nil
+    end
+  end
+
+  # Raised by query_with_timeout when the wall-clock deadline fires.
+  class QueryInterruptedError < Error; end
+
+  # Feature gate: raises if the running Extralite build doesn't expose
+  # the requested feature. Use for changesets, etc. that require the
+  # extralite-bundle build.
+  class FeatureNotAvailableError < Error; end
+
+  # Phase 7 Fiber amendment + Kino integration. Prefer Kino.sleep when
+  # available — it uses the OS clock instead of MRI's coarse timer and
+  # is correct inside non-main Ractors. Otherwise Kernel.sleep, which
+  # dispatches to the running Fiber::Scheduler's kernel_sleep on its
+  # own when one is present (no explicit scheduler branch needed) and
+  # sleeps normally when not.
+  # `Kernel.sleep` explicitly: bare `sleep` here would resolve to
+  # Diamond.sleep itself (self == Diamond) and recurse forever.
+  def self.sleep(seconds)
+    if defined?(Kino) && Kino.respond_to?(:sleep)
+      Kino.sleep(seconds)
+    else
+      Kernel.sleep(seconds)
+    end
+  end
+
+  # Wrap a block in BEGIN/COMMIT. Rolls back on exception.
+  #
+  #   Diamond.transaction do
+  #     Users.create(name: 'A')
+  #     Posts.create(title: 'B', user_id: 1)
+  #   end
+  #
+  # Pass a mode for explicit transaction type:
+  #   Diamond.transaction(:deferred)  { ... }
+  #   Diamond.transaction(:immediate) { ... }   # default
+  #   Diamond.transaction(:exclusive) { ... }
+  #
+  # Returns the block's return value on commit, re-raises on rollback.
+  def self.transaction(mode = :immediate, &block)
+    raise ArgumentError, "transaction requires a block" unless block
+    engine.db.transaction(mode) { block.call }
+  end
+
+  # Phase 7: nested transactions via SQLite savepoints.
+  #   Diamond.transaction do
+  #     Users.create(name: 'A')
+  #     Diamond.savepoint(:risky_op) do
+  #       Users.create(name: 'Bad')
+  #       raise 'oops'
+  #     end  # rolls back to savepoint
+  #   end  # commits Users.create(:A)
+  def self.savepoint(name, &block)
+    raise ArgumentError, "savepoint requires a block" unless block
+    db = engine.db
+    db.savepoint(name)
+    begin
+      result = block.call
+      db.release(name)
+      result
+    rescue StandardError
+      db.rollback_to(name)
+      raise
+    end
+  end
+
+  # table names the calling Ractor's engine knows about, sorted.
+  def self.tables
+    engine.schema_cache.keys.sort
+  end
+
+  # Phase 7: concurrency tuning shortcuts
+  def self.busy_timeout=(val); engine.busy_timeout = val; end
+  def self.busy_timeout; engine.busy_timeout; end
+  def self.gvl_release_threshold=(val); engine.gvl_release_threshold = val; end
+  def self.gvl_release_threshold; engine.gvl_release_threshold; end
+
+  # Phase 7: progress hook
+  def self.on_progress(&block); engine.on_progress(&block); end
+
+  # Phase 7: load extension
+  def self.load_extension(path); engine.load_extension(path); end
+
+  # Phase 7: tracing
+  def self.trace(&block)
+    if block
+      engine.db.trace(&block)
+    else
+      engine.db.trace
+    end
+  end
+
+  # Phase 7: runtime status and limits
+  def self.runtime_status(code)
+    Extralite.runtime_status(RUNTIME_STATUS_CODES.fetch(code))
+  end
+
+  def self.status(code)
+    engine.db.status(Engine::DBSTATUS_CODES.fetch(code))
+  end
+
+  def self.limit(code, value = nil)
+    engine.db.limit(code, value)
+  end
+
+  # drop everything derived from the old schema. runs on reload_schema!.
+  # per-Ractor: clears only the calling Ractor's parser/struct/finder
+  # caches. operator registries are untouched (use their `clear!`).
+  def self.clear_caches!
+    Parser.clear_caches!
+    StructFactory.clear_caches!
+    Domains::DynamicFinders.clear_caches!
+  end
+end