instant_record 0.1.0

data/lib/instant_record/local_schema.rb

@@ -0,0 +1,75 @@
+module InstantRecord
+  # Bringing a local database up to the app's current schema, at boot.
+  #
+  # `DatabaseTasks.prepare_all` is the whole story on a server: a process starts
+  # in Rails.root, so the relative "db/migrate" that ActiveRecord::Migrator
+  # defaults to resolves. In the browser the VM's working directory is "/" while
+  # the app is mounted at "/rails", so that path finds nothing: the migrator sees
+  # zero migrations, reports nothing pending, and `prepare_all` is a silent
+  # no-op. A returning visitor therefore keeps whatever schema their local
+  # database was created with, and the first page touching a table added since
+  # fails with "relation does not exist" — which is how two demos broke for
+  # anyone who had booted the app before they existed.
+  #
+  # Pointing the migrator at absolute paths is not enough, and alone it is worse
+  # than the no-op. These databases were built by `load_schema`, and its
+  # `assume_migrated_upto_version` could only record the versions it could find —
+  # which, with the paths broken, was the schema's own version and nothing else.
+  # Make every migration discoverable and they all look pending, so boot replays
+  # `create_table :issues` against a database that already has it, the install
+  # raises, and the worker never activates.
+  #
+  # So the versions are reconciled first, by the rule
+  # `assume_migrated_upto_version` would have used: db/schema.rb describes every
+  # migration up to its own version, so a migration older than the highest
+  # version this database has recorded is already in it, and gets stamped rather
+  # than run. Anything newer is genuinely pending, and is migrated for real.
+  #
+  # That inherits one property from `assume_migrated_upto_version`: a migration
+  # back-dated below a version this database already has is taken as applied,
+  # not run. On a server `db:migrate` would run it. Here there is no history to
+  # consult — only a schema that was loaded whole — so the version order is the
+  # only evidence there is.
+  module LocalSchema
+    class << self
+      # The browser runtime's schema step, in place of a bare `prepare_all`.
+      def prepare!
+        ActiveRecord::Tasks::DatabaseTasks.prepare_all
+
+        # On a server the working directory already makes migrations findable,
+        # and the stamping below would be wrong there: a back-dated migration on
+        # a real migration history is genuinely pending, not implied by a schema
+        # load that never happened.
+        return unless InstantRecord.browser?
+
+        catch_up!(migration_paths)
+      end
+
+      # Reconcile, then migrate. Takes the paths explicitly because the whole
+      # bug is a path that only resolves from the right working directory.
+      def catch_up!(paths)
+        context = ActiveRecord::MigrationContext.new(paths)
+        stamp_migrations_the_loaded_schema_already_contains(context)
+        context.migrate
+      end
+
+      private
+
+      # Absolute, and the app's own configured paths, so the engine's migrations
+      # travel with the app's (see the "instant_record.migrations" initializer).
+      def migration_paths
+        Rails.application.config.paths["db/migrate"].existent
+      end
+
+      def stamp_migrations_the_loaded_schema_already_contains(context)
+        recorded = context.get_all_versions
+        baseline = recorded.max
+        return unless baseline
+
+        (context.migrations.map(&:version) - recorded)
+          .select { |version| version < baseline }
+          .each { |version| context.schema_migration.create_version(version) }
+      end
+    end
+  end
+end

data/lib/instant_record/outbox_mutation.rb

@@ -0,0 +1,24 @@
+module InstantRecord
+  # Browser-local durable outbox. One row per write, created in the same
+  # transaction as the record change. Drained in insertion order on sync.
+  class OutboxMutation < ActiveRecord::Base
+    self.table_name = "instant_record_outbox"
+
+    serialize :changes_payload, coder: JSON
+
+    before_create { self.id ||= SecureRandom.uuid }
+
+    scope :ordered, -> { order(:created_at, :id) }
+
+    def as_mutation
+      {
+        id: id,
+        record_type: record_type,
+        record_id: record_id,
+        operation: operation,
+        changes: changes_payload,
+        base_version: base_version
+      }
+    end
+  end
+end

data/lib/instant_record/pglite_compat.rb

@@ -0,0 +1,40 @@
+# DDL in the browser runtime, made possible.
+#
+# wasmify-rails' PGlite adapter inherits Rails' PostgreSQL statement pool, whose
+# `dealloc` asks the raw connection whether it is still usable before sending a
+# DEALLOCATE:
+#
+#   if (conn = ...) && conn.status == PG::CONNECTION_OK
+#
+# Neither piece exists on the wasm side — the interface has no `status`, and the
+# pg stub defines transaction statuses but not connection ones. Nothing hits that
+# path until the pool is cleared, and the pool is cleared by DDL, so every
+# migration in the browser died with `undefined method 'status'`: the boot
+# catch-up (see InstantRecord::LocalSchema) and the demo that ships a migration
+# on demand both.
+#
+# The fix is to say what is true rather than to make the deallocation work.
+# PGlite's `prepare` only records the SQL in a Ruby-side map; nothing is prepared
+# on the database, so there is nothing to deallocate, and a raw connection that
+# does not answer PG::CONNECTION_OK is exactly how the pool is told to skip it.
+# That covers every route into `dealloc` — a cleared cache, a deleted statement,
+# and the eviction once the pool passes its limit.
+#
+# This belongs upstream in wasmify-rails; it lives here so the runtime this gem
+# ships can run a migration at all.
+require "active_record/connection_adapters/pglite_adapter"
+
+module PG
+  CONNECTION_OK = 0 unless defined?(CONNECTION_OK)
+  CONNECTION_BAD = 1 unless defined?(CONNECTION_BAD)
+end
+
+module ActiveRecord
+  module ConnectionAdapters
+    class PGliteAdapter
+      class ExternalInterface
+        def status = PG::CONNECTION_BAD
+      end
+    end
+  end
+end

data/lib/instant_record/runtime_scoped.rb

@@ -0,0 +1,21 @@
+module InstantRecord
+  # Class-level blocks that only exist in one runtime. Syncable models get
+  # these automatically; any other class (controllers, jobs, POROs) opts in:
+  #
+  #   class IssuesController < ApplicationController
+  #     extend InstantRecord::RuntimeScoped
+  #
+  #     server_only do
+  #       before_action :authenticate_user!   # sessions exist only on the server
+  #     end
+  #   end
+  module RuntimeScoped
+    def server_only(&block)
+      class_eval(&block) unless InstantRecord.browser?
+    end
+
+    def browser_only(&block)
+      class_eval(&block) if InstantRecord.browser?
+    end
+  end
+end

data/lib/instant_record/sync_metadata.rb

@@ -0,0 +1,16 @@
+module InstantRecord
+  # Browser-local key/value store; holds the SSE cursor across reloads.
+  class SyncMetadata < ActiveRecord::Base
+    self.table_name = "instant_record_sync_metadata"
+    self.primary_key = "key"
+
+    def self.get(key)
+      find_by(key: key)&.value
+    end
+
+    def self.set(key, value)
+      record = find_or_initialize_by(key: key)
+      record.update!(value: value.to_s)
+    end
+  end
+end

data/lib/instant_record/sync_window.rb

@@ -0,0 +1,82 @@
+module InstantRecord
+  # A bounded sync window declared on a Syncable model: the newest `limit`
+  # rows, per partition when partition_by is set, ordered by (created_at, id).
+  # Bootstrap serializes in_window, history pages walk below it, and the
+  # browser client evicts beyond_window at boot.
+  class SyncWindow
+    attr_reader :model, :limit, :partition_by
+
+    def initialize(model, limit:, partition_by: nil)
+      unless limit.is_a?(Integer) && limit.positive?
+        raise ArgumentError, "sync_window limit must be a positive integer (got #{limit.inspect})"
+      end
+
+      @model = model
+      @limit = limit
+      @partition_by = partition_by&.to_s
+    end
+
+    # Rows inside the window (the newest `limit` per partition).
+    def in_window
+      @model.where("#{quoted_primary_key} IN (#{ranked_ids_sql("<=")})")
+    end
+
+    # Rows outside the window — eviction's target. An extra `scope` narrows
+    # further (e.g. excluding sync_state "pending").
+    def beyond_window(scope = @model.all)
+      scope.where("#{quoted_primary_key} IN (#{ranked_ids_sql(">")})")
+    end
+
+    # Keyset page scope: rows strictly below the (created_at, id) tuple within
+    # one partition, newest first. Shared by the records endpoint (server) and
+    # the client's local-page checks — one predicate, no OFFSET.
+    def keyset_below(at:, id:, partition: nil)
+      pk = @model.primary_key
+      scope = @partition_by ? @model.where(@partition_by => partition) : @model.all
+      scope
+        .where("created_at < :at OR (created_at = :at AND #{pk} < :id)", at: at, id: id)
+        .order(created_at: :desc, pk => :desc)
+    end
+
+    private
+
+    # ROW_NUMBER() runs identically on Postgres, PGlite, and SQLite >= 3.25 —
+    # the three engines the same model file can find itself on.
+    def ranked_ids_sql(comparison)
+      validate_columns!
+      connection = @model.connection
+      table = connection.quote_table_name(@model.table_name)
+      created_at = connection.quote_column_name("created_at")
+      over = [partition_clause(connection), "ORDER BY #{created_at} DESC, #{quoted_primary_key} DESC"].compact.join(" ")
+
+      <<~SQL.squish
+        SELECT #{quoted_primary_key} FROM (
+          SELECT #{quoted_primary_key}, ROW_NUMBER() OVER (#{over}) AS instant_record_rank
+          FROM #{table}
+        ) instant_record_ranked
+        WHERE instant_record_rank #{comparison} #{@limit}
+      SQL
+    end
+
+    def partition_clause(connection)
+      @partition_by && "PARTITION BY #{connection.quote_column_name(@partition_by)}"
+    end
+
+    def quoted_primary_key
+      @model.connection.quote_column_name(@model.primary_key)
+    end
+
+    # Deferred to first use: at declaration time the table may not exist yet
+    # (class load precedes migrations).
+    def validate_columns!
+      return if @validated
+
+      %w[created_at].concat([@partition_by].compact).each do |column|
+        unless @model.column_names.include?(column)
+          raise ArgumentError, "sync_window column #{column.inspect} does not exist on #{@model.table_name}"
+        end
+      end
+      @validated = true
+    end
+  end
+end

data/lib/instant_record/syncable.rb

@@ -0,0 +1,106 @@
+require "securerandom"
+
+module InstantRecord
+  # Makes a model local-first syncable. The same file loads in both runtimes:
+  # in the browser (ruby.wasm) every write also records an outbox mutation in
+  # the same local transaction; on the server the concern only provides the
+  # shared column conventions (uuid ids, server_version, sync_state).
+  module Syncable
+    extend ActiveSupport::Concern
+
+    included do
+      extend InstantRecord::RuntimeScoped
+
+      before_create :assign_instant_record_uuid
+
+      # Guarded at call time, not include time, so the same class works in
+      # both runtimes and tests can stub the runtime without re-including.
+      # after_create/update/destroy run INSIDE the wrapping transaction
+      # (unlike after_commit), which is what gives us write+outbox atomicity.
+      before_save   { self.sync_state = "pending" if instant_record_local_write? }
+      after_create  { record_outbox_mutation("create") if instant_record_local_write? }
+      after_update  { record_outbox_mutation("update") if instant_record_local_write? }
+      after_destroy { record_outbox_mutation("destroy") if instant_record_local_write? }
+
+      # Server-originated writes (jobs, console, seeds) are change-logged so
+      # they stream to clients like any other change. Client mutations are
+      # excluded — MutationApplier versions and logs those itself.
+      before_create { self.server_version = 1 if instant_record_server_write? }
+      before_update { self.server_version += 1 if instant_record_server_write? }
+      after_create  { record_server_change("create") if instant_record_server_write? }
+      after_update  { record_server_change("update") if instant_record_server_write? }
+      after_destroy { record_server_change("destroy") if instant_record_server_write? }
+    end
+
+    class_methods do
+      def instant_record_syncable? = true
+
+      # Declare a bounded sync window: only the newest `limit` rows (per
+      # `partition_by` value when given) sync to fresh clients; older rows
+      # arrive on demand via InstantRecord.fetch_history and the browser
+      # evicts beyond the window at boot. Models without a declaration keep
+      # full sync.
+      def sync_window(limit:, partition_by: nil)
+        @instant_record_sync_window = InstantRecord::SyncWindow.new(self, limit: limit, partition_by: partition_by)
+      end
+
+      def instant_record_sync_window
+        @instant_record_sync_window
+      end
+
+      # Observe a value from the server that last-write-wins threw away. The
+      # block runs with the losing attribute hash at the moment it is dropped,
+      # which is the only moment it exists in this runtime — the gem assigns
+      # nothing, fires no callback, and keeps no copy.
+      def on_discarded_change(&block)
+        @instant_record_discarded_change_handler = block
+      end
+
+      def instant_record_discarded_change_handler
+        @instant_record_discarded_change_handler
+      end
+    end
+
+    private
+
+    def instant_record_local_write?
+      InstantRecord.browser? && !InstantRecord::Client.applying_remote?
+    end
+
+    def instant_record_server_write?
+      !InstantRecord.browser? && !InstantRecord.applying_client_mutation?
+    end
+
+    def assign_instant_record_uuid
+      self.id ||= SecureRandom.uuid
+    end
+
+    def record_outbox_mutation(operation)
+      changes_payload =
+        case operation
+        when "create"  then InstantRecord.wire_attributes(attributes)
+        when "update"  then InstantRecord.wire_attributes(saved_changes.transform_values(&:last))
+        when "destroy" then {}
+        end
+
+      InstantRecord::OutboxMutation.create!(
+        record_type: self.class.name,
+        record_id: id,
+        operation: operation,
+        changes_payload: changes_payload,
+        base_version: self[:server_version] || 0
+      )
+    end
+
+    # Mirrors MutationApplier's log_change/log_destroy payload shapes.
+    def record_server_change(operation)
+      InstantRecord::Change.create!(
+        record_type: self.class.name,
+        record_id: id,
+        operation: operation,
+        version: operation == "destroy" ? 0 : self[:server_version],
+        attributes_payload: operation == "destroy" ? {} : InstantRecord.wire_attributes(attributes)
+      )
+    end
+  end
+end

data/lib/instant_record/version.rb

@@ -0,0 +1,3 @@
+module InstantRecord
+  VERSION = "0.1.0"
+end