instant_record 0.1.0

data/app/models/instant_record/mutation_applier.rb

@@ -0,0 +1,133 @@
+module InstantRecord
+  # Applies one client mutation authoritatively: record write, version bump,
+  # change-log row, and idempotency-ledger row, in one transaction. This is
+  # the server half of the sync protocol; the HTTP layer above it is thin.
+  class MutationApplier
+    def self.apply(mutation)
+      new(mutation).apply
+    end
+
+    def initialize(mutation)
+      @mutation = mutation
+      @changes = (mutation[:changes] || {}).to_h
+    end
+
+    # Replayed mutation ids return their original result without re-applying.
+    def apply
+      if (existing = AppliedMutation.find_by(mutation_id: @mutation[:id]))
+        return existing.result_payload.symbolize_keys
+      end
+
+      model = InstantRecord.synced_model(@mutation[:record_type])
+      return record_result(status: "rejected", reason: "unknown record type") unless model
+
+      result = ActiveRecord::Base.transaction do
+        InstantRecord.applying_client_mutation { perform(model) }
+      end
+      record_result(**result)
+    rescue ActiveRecord::RecordInvalid => e
+      record_result(status: "rejected", reason: e.record.errors.full_messages.to_sentence,
+        server_attributes: server_attributes_for(model))
+    rescue ActiveRecord::RecordNotUnique
+      # A create whose id already exists (e.g. a client replaying rows the
+      # server already has). Rejecting lets the client roll back its local
+      # copy instead of retrying the poisoned mutation forever; the server's
+      # row comes back down through the change stream.
+      record_result(status: "rejected", reason: "id already exists",
+        server_attributes: server_attributes_for(model))
+    rescue ActiveModel::UnknownAttributeError => e
+      # Schema skew: this client is a migration ahead of this server and sent a
+      # column that does not exist here. Rejecting is the only outcome that
+      # cannot jam the queue. Raising 500s the entire batch, and because the
+      # client keeps the row on a transport error it would retry the same
+      # poisoned mutation forever, blocking every write queued behind it.
+      # Slicing the unknown column off instead would answer "applied" for a
+      # write the server only partly stored — silent data loss the client has no
+      # way to notice. A surfaced rejection loses the same write loudly, rolls
+      # the local record back to what the server actually holds, and leaves the
+      # queue draining. Deploy order (server first) remains the real defence.
+      record_result(status: "rejected", reason: e.message,
+        server_attributes: server_attributes_for(model))
+    end
+
+    private
+
+    def perform(model)
+      case @mutation[:operation]
+      when "create"
+        record = model.new(@changes.merge("id" => @mutation[:record_id]))
+        record.server_version = 1
+        record.sync_state = "synced"
+        record.save!
+        log_change(record, "create")
+        { status: "applied", version: record.server_version }
+      when "update"
+        record = model.find_by(id: @mutation[:record_id])
+        return { status: "rejected", reason: "record not found" } unless record
+
+        if stale?(record)
+          # Last-write-wins: an older concurrent write is acknowledged (there is
+          # nothing to retry) but skipped. The row that won travels back with the
+          # result, because a client told only "applied" badges the write it just
+          # lost as synced. See Client#apply_results.
+          { status: "applied", version: record.server_version, skipped: true,
+            server_attributes: InstantRecord.wire_attributes(record.attributes) }
+        else
+          record.assign_attributes(@changes.except("id", "server_version"))
+          record.server_version += 1
+          record.sync_state = "synced"
+          record.save!
+          log_change(record, "update")
+          { status: "applied", version: record.server_version }
+        end
+      when "destroy"
+        record = model.find_by(id: @mutation[:record_id])
+        record&.destroy!
+        log_destroy(model)
+        { status: "applied" }
+      else
+        { status: "rejected", reason: "unknown operation" }
+      end
+    end
+
+    def stale?(record)
+      incoming = @changes["updated_at"]
+      incoming.present? && record.updated_at.present? && Time.zone.parse(incoming.to_s) < record.updated_at
+    end
+
+    def log_change(record, operation)
+      Change.create!(
+        record_type: record.class.name,
+        record_id: record.id,
+        operation: operation,
+        version: record.server_version,
+        attributes_payload: InstantRecord.wire_attributes(record.attributes)
+      )
+    end
+
+    def log_destroy(model)
+      Change.create!(
+        record_type: model.name,
+        record_id: @mutation[:record_id],
+        operation: "destroy",
+        version: 0,
+        attributes_payload: {}
+      )
+    end
+
+    def server_attributes_for(model)
+      record = model&.find_by(id: @mutation[:record_id])
+      InstantRecord.wire_attributes(record.attributes) if record
+    end
+
+    # create_or_find_by leans on the unique index: a concurrent duplicate
+    # returns the already-recorded result instead of applying twice.
+    def record_result(**result)
+      payload = result.merge(mutation_id: @mutation[:id])
+      record = AppliedMutation.create_or_find_by(mutation_id: @mutation[:id]) do |applied|
+        applied.result_payload = payload
+      end
+      record.result_payload.symbolize_keys
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,7 @@
+InstantRecord::Engine.routes.draw do
+  post "mutations", to: "mutations#create"
+  match "mutations", to: "mutations#preflight", via: :options
+  get "events", to: "events#index"
+  get "bootstrap", to: "bootstraps#show"
+  get "records", to: "records#index"
+end

data/db/migrate/20260721000002_create_instant_record_outbox.rb

@@ -0,0 +1,12 @@
+class CreateInstantRecordOutbox < ActiveRecord::Migration[8.1]
+  def change
+    create_table :instant_record_outbox, id: :string do |t|
+      t.string :record_type, null: false
+      t.string :record_id, null: false
+      t.string :operation, null: false
+      t.text :changes_payload
+      t.integer :base_version, null: false, default: 0
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260721000003_create_instant_record_sync_metadata.rb

@@ -0,0 +1,9 @@
+class CreateInstantRecordSyncMetadata < ActiveRecord::Migration[8.1]
+  def change
+    create_table :instant_record_sync_metadata, id: false do |t|
+      t.string :key, null: false, primary_key: true
+      t.string :value
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260721000101_create_instant_record_changes.rb

@@ -0,0 +1,13 @@
+class CreateInstantRecordChanges < ActiveRecord::Migration[8.1]
+  def change
+    create_table :instant_record_changes do |t|
+      t.string :record_type, null: false
+      t.string :record_id, null: false
+      t.string :operation, null: false
+      t.integer :version, null: false, default: 0
+      t.text :attributes_payload
+      t.datetime :created_at, null: false
+    end
+    add_index :instant_record_changes, [:record_type, :record_id]
+  end
+end

data/db/migrate/20260721000102_create_instant_record_applied_mutations.rb

@@ -0,0 +1,10 @@
+class CreateInstantRecordAppliedMutations < ActiveRecord::Migration[8.1]
+  def change
+    create_table :instant_record_applied_mutations do |t|
+      t.string :mutation_id, null: false
+      t.text :result_payload
+      t.datetime :created_at, null: false
+    end
+    add_index :instant_record_applied_mutations, :mutation_id, unique: true
+  end
+end

data/lib/generators/instant_record/install/install_generator.rb

@@ -0,0 +1,53 @@
+require "rails/generators"
+
+module InstantRecord
+  module Generators
+    # Prepares a Rails app for InstantRecord's browser runtime:
+    # wasmify environment, PGlite database config, and a PWA shell
+    # wired with the InstantRecord sync driver.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def run_wasmify_install
+        rake "wasmify:install"
+      end
+
+      def generate_pwa_shell
+        rake "wasmify:pwa"
+      end
+
+      def configure_pglite_database
+        gsub_file "config/database.yml", '{ "nulldb" }', '{ "pglite" }'
+        inject_into_file "config/database.yml", "  js_interface: pglite4rails\n",
+          after: /^wasm:\n  adapter: .*\n/
+      end
+
+      def install_sync_driver
+        copy_file "rails.sw.js", "pwa/rails.sw.js", force: true
+        copy_file "database.js", "pwa/database.js", force: true
+        # Auto-booting splash: registers the worker and reloads into the app.
+        # (wasmify's boot.html stays available as a debug page.)
+        copy_file "index.html", "pwa/index.html", force: true
+      end
+
+      def use_pglite_in_pwa
+        gsub_file "pwa/package.json", /"wasmify-rails": "\^[\d.]+"/, '"wasmify-rails": "^0.2.3"'
+        gsub_file "pwa/package.json", %r{"@sqlite\.org/sqlite-wasm": "[^"]+"}, '"@electric-sql/pglite": "^0.3.0"'
+        gsub_file "pwa/vite.config.js", %r{exclude: \["@sqlite\.org/sqlite-wasm"\]}, 'exclude: ["@electric-sql/pglite"]'
+      end
+
+      def show_next_steps
+        say <<~MSG
+
+          InstantRecord is set up. Next:
+
+            1. Mark the gems your app needs in the browser with `group: [:default, :wasm]` in the Gemfile
+            2. bin/rails db:migrate                # engine tables (outbox, change log, ...)
+            3. bin/rails instant_record:build      # compile + pack the browser bundle
+            4. cd pwa && yarn install && yarn dev  # boot it
+
+        MSG
+      end
+    end
+  end
+end

data/lib/generators/instant_record/install/templates/database.js

@@ -0,0 +1,32 @@
+import { PGlite, types } from "@electric-sql/pglite";
+
+// Timestamps come back as raw Postgres strings rather than JavaScript Dates.
+//
+// Two things go wrong otherwise. Rails stores UTC wall-clock in a `timestamp
+// without time zone` column, and the default parser builds a Date from that
+// naive value as if it were *local* time — so reading it back shifts every
+// timestamp by the machine's UTC offset. And a Date stringifies without
+// sub-second precision, which silently truncates microseconds.
+//
+// Microseconds matter beyond display: a windowed model's history pages are
+// keyset-paginated on (created_at, id), so a truncated cursor cannot be
+// round-tripped into a query and scroll-up stalls. Handing Ruby the string lets
+// ActiveRecord's own DateTime cast do the work, which reads it as UTC and keeps
+// full precision.
+const RAW_TIMESTAMPS = {
+  [types.DATE]: (value) => value,
+  [types.TIMESTAMP]: (value) => value,
+  [types.TIMESTAMPTZ]: (value) => value,
+};
+
+export const setupPGliteDatabase = async () => {
+  // IndexedDB persistence: survives reloads and service worker restarts.
+  // relaxedDurability returns query results before the IndexedDB flush completes.
+  const db = await PGlite.create("idb://instant_record", {
+    relaxedDurability: true,
+    parsers: RAW_TIMESTAMPS,
+  });
+
+  console.log("Running PGlite (Postgres in Wasm)");
+  return db;
+};

data/lib/generators/instant_record/install/templates/index.html

@@ -0,0 +1,69 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>InstantRecord</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, sans-serif;
+      display: flex; flex-direction: column; align-items: center; justify-content: center;
+      min-height: 100vh; margin: 0; background: #fafafa; color: #333;
+    }
+    .pulse {
+      width: 14px; height: 14px; border-radius: 50%; background: #34c759;
+      animation: pulse 1.2s ease-in-out infinite; margin-bottom: 1.25rem;
+    }
+    @keyframes pulse { 0%, 100% { transform: scale(1); opacity: 1; } 50% { transform: scale(1.6); opacity: 0.4; } }
+    h1 { font-size: 1.1rem; font-weight: 600; margin: 0 0 0.5rem; }
+    #status { font-size: 0.85rem; color: #888; min-height: 1.2em; max-width: 32rem; text-align: center; }
+    .hint { font-size: 0.75rem; color: #bbb; margin-top: 2rem; }
+  </style>
+</head>
+<body>
+  <div class="pulse"></div>
+  <h1>InstantRecord</h1>
+  <p id="status">Starting the local runtime&hellip;</p>
+  <p class="hint">First visit compiles Ruby for your browser (~60MB, cached afterwards)</p>
+
+  <!-- Classic (non-module) script on purpose: served verbatim by both the
+       static server and the Vite build, no bundling required. -->
+  <script>
+    (async () => {
+      const status = document.getElementById("status");
+
+      if (!("serviceWorker" in navigator)) {
+        status.textContent = "This browser does not support service workers.";
+        return;
+      }
+
+      // If a previous visit already installed the app, the service worker
+      // will take over this URL on reload.
+      if (navigator.serviceWorker.controller) {
+        location.reload();
+        return;
+      }
+
+      navigator.serviceWorker.addEventListener("message", (event) => {
+        if (event.data && event.data.type === "progress" && event.data.step) {
+          status.textContent = event.data.step;
+        }
+      });
+
+      try {
+        await navigator.serviceWorker.register("/rails.sw.js", { scope: "/", type: "module" });
+      } catch (error) {
+        status.textContent = "Could not start: " + error.message;
+        return;
+      }
+
+      // `ready` resolves once install finishes — and install boots the whole
+      // Rails VM, so this is "the app is actually usable".
+      await navigator.serviceWorker.ready;
+
+      status.textContent = "Ready — opening the app";
+      location.reload(); // now served by Rails running in this browser
+    })();
+  </script>
+</body>
+</html>