fresco 0.0.1

data/lib/fresco/runtime/db_sqlite.rb

@@ -0,0 +1,495 @@
+# Fresco SQLite adapter. Copied verbatim to generated/db_adapter.rb
+# by `fresco build` when config/database.rb declares `Fresco.database
+# :sqlite`. Always loaded between runtime.rb and config/app.rb — boot
+# order in lib/fresco/runtime/boot.rb.
+#
+# Contains everything an action needs to talk to SQLite under both
+# CRuby (dev) and Spinel (release): the FFI module pointing at
+# generated/runtime/sqlite.c, the Ruby wrapper, and the
+# `Fresco::Db::Active` alias that the M3+ codegen will target.
+#
+# The `Sqlite` module's ffi_cflags/ffi_lib pull
+# generated/runtime/sqlite.c into Spinel's cc invocation and
+# `-lsqlite3` into the link line. Under CRuby the same declarations
+# are no-ops (`fresco dev` stubs them on Module) and dev installs
+# singleton-method stand-ins that route through the `sqlite3` gem.
+module Sqlite
+  ffi_cflags "generated/runtime/sqlite.c"
+  ffi_lib    "sqlite3"
+
+  ffi_func :fresco_sqlite_open,              [:str],             :int
+  ffi_func :fresco_sqlite_close,             [:int],             :int
+  ffi_func :fresco_sqlite_exec,              [:int, :str],       :int
+  ffi_func :fresco_sqlite_prepare,           [:int, :str],       :int
+  ffi_func :fresco_sqlite_bind_str,          [:int, :int, :str], :int
+  ffi_func :fresco_sqlite_bind_int,          [:int, :int, :int], :int
+  ffi_func :fresco_sqlite_step,              [:int],             :int
+  ffi_func :fresco_sqlite_col_str,           [:int, :int],       :str
+  ffi_func :fresco_sqlite_col_int,           [:int, :int],       :int
+  ffi_func :fresco_sqlite_col_count,         [:int],             :int
+  ffi_func :fresco_sqlite_finalize,          [:int],             :int
+  ffi_func :fresco_sqlite_reset,             [:int],             :int
+  ffi_func :fresco_sqlite_last_insert_rowid, [:int],             :int
+end
+
+module Fresco
+  module Db
+    # Thin Ruby cover over the Sqlite FFI module. Methods return values
+    # straight from the C side — handle ids as Int, cursor ids as Int,
+    # status codes as Int (0 success, -1 error), column values as Str
+    # or Int. No exceptions on DB errors; callers branch on `< 0`.
+    #
+    # Spinel-shape constraints worth flagging up front:
+    #   - Attribute is named `dbh` (not `handle`) — the latter widens
+    #     poly-dispatch return types across classes that also define
+    #     `handle` (see Tep's same workaround). Keeps every method
+    #     name on this class collision-free across the framework.
+    #   - `cursor_id` is returned by #prepare and threaded through
+    #     #step/#bind_*/#col_*/#finalize/#reset. The single-cursor
+    #     pattern works too — just call them with one cursor id at a
+    #     time — but the API allows several open at once (M3+ codegen
+    #     stacks finders inside each other).
+    #   - Defaults on every typed parameter pin Spinel's analyzer to
+    #     the right slot type — same rule as Params/Response in this
+    #     file. Required-but-defaultless params collapse to mrb_int
+    #     under Spinel (see [[spinel_initialize_kwargs]]).
+    class SQLite
+      attr_accessor :dbh
+
+      def initialize
+        @dbh = -1
+      end
+
+      # Returns true on success, false on failure. Path may be a real
+      # file or `:memory:` for an anonymous in-memory database. Calling
+      # #open twice on the same instance leaks the prior handle — close
+      # first.
+      def open(path = "")
+        h = Sqlite.fresco_sqlite_open(path)
+        return false if h < 0
+        @dbh = h
+        true
+      end
+
+      def close
+        if @dbh >= 0
+          Sqlite.fresco_sqlite_close(@dbh)
+          @dbh = -1
+        end
+        0
+      end
+
+      # Run a no-bind statement (DDL, BEGIN/COMMIT, queries with literal
+      # constants). Returns true on success. For any user-supplied value
+      # always use prepare + bind + step + finalize.
+      def exec(sql = "")
+        return false if @dbh < 0
+        Sqlite.fresco_sqlite_exec(@dbh, sql) == 0
+      end
+
+      # Open a cursor on a parameterised statement. Returns an Int
+      # cursor id (>= 1) on success, -1 on failure. Subsequent bind_str/
+      # bind_int/step/col_str/col_int/col_count/finalize/reset calls
+      # take this id as their first argument. Always pair with #finalize.
+      def prepare(sql = "")
+        return -1 if @dbh < 0
+        Sqlite.fresco_sqlite_prepare(@dbh, sql)
+      end
+
+      def bind_str(cid = 0, idx = 0, value = "")
+        Sqlite.fresco_sqlite_bind_str(cid, idx, value)
+      end
+
+      def bind_int(cid = 0, idx = 0, value = 0)
+        Sqlite.fresco_sqlite_bind_int(cid, idx, value)
+      end
+
+      # 1 -> row available, 0 -> done, -1 -> error or invalid cursor.
+      def step(cid = 0);             Sqlite.fresco_sqlite_step(cid);            end
+      def col_str(cid = 0, idx = 0); Sqlite.fresco_sqlite_col_str(cid, idx);    end
+      def col_int(cid = 0, idx = 0); Sqlite.fresco_sqlite_col_int(cid, idx);    end
+      def col_count(cid = 0);        Sqlite.fresco_sqlite_col_count(cid);       end
+      def finalize(cid = 0);         Sqlite.fresco_sqlite_finalize(cid);        end
+      def reset(cid = 0);            Sqlite.fresco_sqlite_reset(cid);           end
+
+      def last_rowid
+        return -1 if @dbh < 0
+        Sqlite.fresco_sqlite_last_insert_rowid(@dbh)
+      end
+
+      # Convenience: prepare a single-row single-column query with at
+      # most one Str bind, step once, return col 0 as Str, finalize.
+      # Pass `""` for no bind. Mirrors Tep::SQLite#first_str so M1
+      # smoke tests stay terse.
+      def first_str(sql = "", p1 = "")
+        return "" if @dbh < 0
+        cid = Sqlite.fresco_sqlite_prepare(@dbh, sql)
+        return "" if cid < 0
+        if p1.length > 0
+          Sqlite.fresco_sqlite_bind_str(cid, 1, p1)
+        end
+        result = ""
+        if Sqlite.fresco_sqlite_step(cid) == 1
+          result = Sqlite.fresco_sqlite_col_str(cid, 0)
+        end
+        Sqlite.fresco_sqlite_finalize(cid)
+        result
+      end
+
+      def first_int(sql = "", p1 = "")
+        return 0 if @dbh < 0
+        cid = Sqlite.fresco_sqlite_prepare(@dbh, sql)
+        return 0 if cid < 0
+        if p1.length > 0
+          Sqlite.fresco_sqlite_bind_str(cid, 1, p1)
+        end
+        result = 0
+        if Sqlite.fresco_sqlite_step(cid) == 1
+          result = Sqlite.fresco_sqlite_col_int(cid, 0)
+        end
+        Sqlite.fresco_sqlite_finalize(cid)
+        result
+      end
+    end
+
+    # Alias the chosen adapter so generated code (M3+) and user actions
+    # can refer to one name regardless of which is linked.
+    #
+    # Don't call `Fresco::Db::Active.new` directly from action code:
+    # Spinel's analyzer doesn't chase constant aliases through Active,
+    # treats the receiver as int, and emits 0 for every subsequent
+    # method call on the returned object. Use `Fresco::Db.new_instance`
+    # below instead — the typed factory gives Spinel a concrete class
+    # to bind dispatch against.
+    Active = SQLite
+
+    # Adapter-agnostic factory. Returns a fresh unopened SQLite (or
+    # Postgres, in the other template) instance. Action code that
+    # wants to be DB-agnostic calls this; Spinel's analyzer sees the
+    # concrete return type per-build and dispatches correctly.
+    def self.new_instance
+      SQLite.new
+    end
+
+    # Lazy connection handle for the generated model layer. Held as
+    # an Int (the slot-table index returned by fresco_sqlite_open),
+    # NOT as a wrapper instance — module-level `@x = SQLite.new` at
+    # load time tripped Spinel's static-initializer requirement; an
+    # int default sidesteps it entirely. Initialised to -1 ("not
+    # opened yet"); ensure_connection_dbh! lazy-opens on first model
+    # call and re-uses the slot for the process lifetime. M5 replaces
+    # this with explicit per-worker boot!/shutdown! plumbing.
+    @conn_dbh = -1
+
+    def self.ensure_connection_dbh!
+      if @conn_dbh < 0
+        h = Sqlite.fresco_sqlite_open(Fresco.database_path)
+        @conn_dbh = h if h > 0
+      end
+      @conn_dbh
+    end
+
+    # SQL query logging. Off by default — set FRESCO_LOG_SQL to any
+    # non-empty value to enable (mirrors the NO_COLOR convention used
+    # by Color.enabled? in runtime.rb).
+    #
+    # Output format — lines are nested under the [request] log line by
+    # buffering during the request and flushing after log_request_full
+    # prints. With bindings captured at bind_int/bind_str call time,
+    # the rendered line looks like:
+    #
+    #   [request] GET /users 200 (1234us)
+    #     [db cached] SELECT id, name FROM users WHERE id = ?  [$1=5]
+    #
+    # Buffering uses a single "current pending entry" (per-module, not
+    # per-cursor) — codegen always sequences `prepare → bind* → step`
+    # without interleaving, so the latest pending row is the right one
+    # to attribute binds to. Each new prepare/exec flushes the prior
+    # pending entry to the buffer first, so nothing is lost even if a
+    # caller does two prepares back-to-back without intervening steps.
+    #
+    # Outside a request (migrations, db:migrate, db:rollback) buffering
+    # is off — lines print directly so they interleave naturally with
+    # the [migrate] progress lines. The runtime toggles `@in_request`
+    # via begin_request! / flush_log! around each request.
+    def self.log_sql?
+      ENV.fetch("FRESCO_LOG_SQL", "") != ""
+    end
+
+    # In-request buffering state. `@in_request` flips on at the start
+    # of each request via begin_request! and back off when flush_log!
+    # drains the buffer. `@log_buffer` is seeded with a placeholder
+    # entry that's immediately deleted — the same seed-and-clear trick
+    # the rest of runtime.rb uses to pin an Array<String> shape under
+    # Spinel's analyzer (a bare `[]` would lower to a poly-typed array
+    # and the first push would widen each entry to RbVal).
+    @in_request = false
+    @log_buffer = [""]
+    @log_buffer.delete_at(0)
+
+    # `@has_pending` is the timing-state flag: true between a
+    # prepare/cached_prepare and the first step that follows. We need
+    # it independent of `@pending_sql` because timing runs even when
+    # FRESCO_LOG_SQL is off (so @pending_sql may be empty), but the
+    # prepare→step bracket still needs to be measured for the
+    # request-line roll-up.
+    @has_pending    = false
+    @pending_t0     = 0
+    @pending_sql    = ""
+    @pending_label  = ""
+    @pending_binds  = ""
+
+    # The per-request SQL totals (`@db_sql_total_micros`,
+    # `@db_sql_count`) live on the `Fresco` module in runtime.rb,
+    # not here. That's the workaround for the Spinel cross-file-
+    # value-return collapse — see the comment on those counters in
+    # runtime.rb. Below we call `Fresco.add_sql_micros!` (side-effect
+    # cross-file call, works fine) and `Fresco.reset_db_sql_stats!`
+    # (same).
+    def self.begin_request!
+      @in_request = true
+      Fresco.reset_db_sql_stats!
+    end
+
+    # Called from the request handler after log_request_full prints.
+    # Drains any pending entry (covering queries that prepared but
+    # never reached step — rare, but possible if a handler raises
+    # mid-bind), then dumps every buffered line indented under the
+    # [request] line. Resets state for the next request.
+    #
+    # NB: clear the buffer in place rather than re-assigning the
+    # ivar. Reassigning `@log_buffer = [""]; @log_buffer.delete_at(0)`
+    # every request orphans the old array; Spinel doesn't reclaim it
+    # and a few hundred requests in we get a bus error on the next
+    # access. delete_at-from-the-tail is a safe in-place reset —
+    # `sp_StrArray_delete_at` is a slot pop, no realloc.
+    def self.flush_log!
+      flush_pending!
+      i = 0
+      while i < @log_buffer.length
+        puts @log_buffer[i]
+        i += 1
+      end
+      while @log_buffer.length > 0
+        @log_buffer.delete_at(@log_buffer.length - 1)
+      end
+      @in_request = false
+    end
+
+    # Emit the current pending entry (if any) and clear it. Two jobs:
+    #   1. Compute the [prepare → now] duration and fold it into the
+    #      per-request totals. Runs even when FRESCO_LOG_SQL is off so
+    #      the request-line roll-up stays accurate.
+    #   2. When FRESCO_LOG_SQL is on, emit the formatted log line with
+    #      that duration, the column-binding annotation, and the
+    #      [db] / [db cached] marker.
+    # Used as a boundary between consecutive prepares (so a prepare-
+    # without-step still gets timed and surfaced) and as the bind→step
+    # hand-off (so step's emission picks up the accumulated binds).
+    def self.flush_pending!
+      return unless @has_pending
+      dt = Sock.sphttp_elapsed_micros - @pending_t0
+      Fresco.add_sql_micros!(dt)
+      if @pending_sql != ""
+        line = @pending_label + Color.dim("(" + fmt_micros(dt) + ") ") + color_sql(@pending_sql)
+        if @pending_binds != ""
+          line += Color.dim("  [" + @pending_binds + "]")
+        end
+        emit(line)
+      end
+      @has_pending   = false
+      @pending_t0    = 0
+      @pending_sql   = ""
+      @pending_label = ""
+      @pending_binds = ""
+    end
+
+    # Single-line emit. Routes through the buffer when we're inside a
+    # request (so the line lands under the [request] log), or straight
+    # to stdout for migrations / one-off CLI work where there's no
+    # request to nest under.
+    def self.emit(line = "")
+      if @in_request
+        @log_buffer.push(line)
+      else
+        puts line
+      end
+    end
+
+    # Record one bind on the current pending entry. When `name` is
+    # non-empty, use it as the label (`email="bob"`); when empty, fall
+    # back to the placeholder index (`$1="bob"`). Model codegen passes
+    # the column name through; ad-hoc `Db.exec` / `Model.query` / hand-
+    # written SQL paths call without a name and get the `$N` form.
+    # Strings get double-quoted so a numeric-looking string ("42")
+    # isn't ambiguous with the int 42 when reading logs.
+    def self.record_bind_int(idx = 0, value = 0, name = "")
+      return if @pending_sql == ""
+      sep   = @pending_binds == "" ? "" : ", "
+      label = name == "" ? "$" + idx.to_s : name
+      @pending_binds = @pending_binds + sep + label + "=" + value.to_s
+    end
+
+    def self.record_bind_str(idx = 0, value = "", name = "")
+      return if @pending_sql == ""
+      sep   = @pending_binds == "" ? "" : ", "
+      label = name == "" ? "$" + idx.to_s : name
+      @pending_binds = @pending_binds + sep + label + "=\"" + value + "\""
+    end
+
+    # Adapter-agnostic surface for the model codegen. Each generated
+    # `User.find` / `User.insert` etc. calls these (rather than the
+    # wrapper class) so the same model source runs against either
+    # backend — only the SQL strings differ (and those are emitted
+    # by bin/build at model-codegen time).
+    def self.exec(sql = "")
+      h = ensure_connection_dbh!
+      return false if h < 0
+      flush_pending! if @has_pending
+      t0 = Sock.sphttp_elapsed_micros
+      result = Sqlite.fresco_sqlite_exec(h, sql) == 0
+      dt = Sock.sphttp_elapsed_micros - t0
+      Fresco.add_sql_micros!(dt)
+      if log_sql?
+        emit(Color.dim("  [db] (" + fmt_micros(dt) + ") ") + color_sql(sql))
+      end
+      result
+    end
+
+    def self.prepare(sql = "")
+      h = ensure_connection_dbh!
+      return -1 if h < 0
+      flush_pending! if @has_pending
+      @pending_t0  = Sock.sphttp_elapsed_micros
+      @has_pending = true
+      if log_sql?
+        @pending_sql   = sql
+        @pending_label = Color.dim("  [db] ")
+        @pending_binds = ""
+      end
+      Sqlite.fresco_sqlite_prepare(h, sql)
+    end
+
+    # Prepared-statement cache. Seed-and-clear pins the hash to
+    # StrIntHash for Spinel's analyzer — sql string → cursor id.
+    # Generated model methods call `cached_prepare` and skip the
+    # matching `finalize`; the cursor lives for the process lifetime
+    # and gets reset (rewound + bindings preserved) on subsequent
+    # calls. Ad-hoc callers writing one-shot queries still use the
+    # plain `prepare` / `finalize` pair below.
+    @stmt_cache = { "__t" => 0 }
+    @stmt_cache.delete("__t")
+
+    def self.cached_prepare(sql = "")
+      if @stmt_cache.key?(sql)
+        cid = @stmt_cache[sql]
+        Sqlite.fresco_sqlite_reset(cid)
+        flush_pending! if @has_pending
+        @pending_t0  = Sock.sphttp_elapsed_micros
+        @has_pending = true
+        if log_sql?
+          @pending_sql   = sql
+          @pending_label = Color.dim("  [db cached] ")
+          @pending_binds = ""
+        end
+        return cid
+      end
+      cid = prepare(sql)
+      @stmt_cache[sql] = cid if cid > 0
+      cid
+    end
+
+    # The trailing `name = ""` is the column-name annotation for log
+    # output — codegen passes it from the schema, ad-hoc callers omit
+    # it. The FFI delegate ignores it; it's purely for the log layer.
+    def self.bind_str(cid = 0, idx = 0, value = "", name = "")
+      record_bind_str(idx, value, name) if log_sql?
+      Sqlite.fresco_sqlite_bind_str(cid, idx, value)
+    end
+
+    def self.bind_int(cid = 0, idx = 0, value = 0, name = "")
+      record_bind_int(idx, value, name) if log_sql?
+      Sqlite.fresco_sqlite_bind_int(cid, idx, value)
+    end
+
+    # Two timing paths:
+    #   - First step after a prepare/cached_prepare: flush_pending!
+    #     computes `dt = now - @pending_t0` (covers prepare + binds
+    #     + this step) and folds it into the per-request totals.
+    #   - Iteration step on an already-flushed cursor (SELECT row
+    #     pump): time just this call and accumulate. A 1000-row
+    #     SELECT counts every row's micros toward the request total,
+    #     not just the first.
+    def self.step(cid = 0)
+      if @has_pending
+        result = Sqlite.fresco_sqlite_step(cid)
+        flush_pending!
+        return result
+      end
+      t0 = Sock.sphttp_elapsed_micros
+      result = Sqlite.fresco_sqlite_step(cid)
+      Fresco.add_sql_micros!(Sock.sphttp_elapsed_micros - t0)
+      result
+    end
+
+    def self.col_str(cid = 0, idx = 0); Sqlite.fresco_sqlite_col_str(cid, idx); end
+    def self.col_int(cid = 0, idx = 0); Sqlite.fresco_sqlite_col_int(cid, idx); end
+    def self.finalize(cid = 0);         Sqlite.fresco_sqlite_finalize(cid);     end
+    def self.reset(cid = 0);            Sqlite.fresco_sqlite_reset(cid);        end
+
+    def self.last_rowid
+      h = ensure_connection_dbh!
+      return -1 if h < 0
+      Sqlite.fresco_sqlite_last_insert_rowid(h)
+    end
+
+    # Eager-open the connection. Called once from Fresco::App#run at
+    # startup. ensure_connection_dbh! already lazy-opens on first
+    # use, but eager-open surfaces a bad DSN at process start
+    # instead of inside the first request — cheaper to fail there.
+    def self.boot!
+      ensure_connection_dbh!
+    end
+
+    # Transaction support. The block runs between BEGIN and COMMIT;
+    # set `Fresco::Db.rollback!` inside the block to force a
+    # ROLLBACK instead. We don't rely on Ruby `rescue` for rollback-
+    # on-exception — Spinel's rescue handling across FFI boundaries
+    # is iffy, and the explicit-opt-in shape is what the plan
+    # specifies. Returns true on commit, false on rollback.
+    @tx_rollback_requested = false
+
+    def self.rollback!
+      @tx_rollback_requested = true
+    end
+
+    # Transaction primitives. Spinel doesn't lower custom `&block`
+    # parameters cleanly (see the `each(&blk)` note in runtime.rb's
+    # Params class), so we expose explicit begin/commit/rollback
+    # instead of a block-yielding `transaction { ... }`. Pattern:
+    #
+    #   Fresco::Db.begin_tx
+    #   User.insert(...)
+    #   Fresco::Db.rollback! if some_condition
+    #   Fresco::Db.commit_tx
+    #
+    # commit_tx checks the rollback flag and emits ROLLBACK instead
+    # of COMMIT if it's set. Returns true on commit, false on
+    # rollback so callers can branch on the outcome.
+    def self.begin_tx
+      exec("BEGIN")
+      @tx_rollback_requested = false
+      true
+    end
+
+    def self.commit_tx
+      if @tx_rollback_requested
+        exec("ROLLBACK")
+        @tx_rollback_requested = false
+        return false
+      end
+      exec("COMMIT")
+      true
+    end
+  end
+end