orbitcast 0.3.1-x86_64-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d5dfa18b582b4d44a1dc95a967e3fd29e68e09b89e845e568df3eaf02b601e5d
+  data.tar.gz: bf2e31580db19b5992ec216f5cd8216e2d6603b755fc7c8283757bb2033e06b9
+SHA512:
+  metadata.gz: bfde23c0354765cfca4a77b8cffe85e47ef0e90f48fb8525f427aebb55fc6e2978c3bf7c934076953c3527ab6fe918f367204fb7e8f248db12829305d4b56692
+  data.tar.gz: 35d284179b69ba6b0e58f06fe940a108e209badcdb3a2c7b8390fb7c5919c087decd7ba3026a708b3f7391ca352f6234f407a683bed062afb9ef6839181916de

data/LICENSE.txt

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Abdelkader Boudih
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,100 @@
+# orbitcast (Ruby gem)
+
+Rails integration for the Orbitcast relay. The gem ships the Ruby side plus one
+native executable per platform; the relay itself is a separately supervised Rust
+process.
+
+Two modes. In `mode: :signed` (default) the relay authorizes subscriptions
+from signed stream names and no application Ruby runs on the socket path.
+In `mode: :dispatch` the relay calls back into Rails over a private HTTP
+endpoint, and `ApplicationCable::Connection#connect`, channel callbacks,
+and `perform` actions run here as ordinary Rails code.
+
+## What is in here
+
+| Path | Role |
+| --- | --- |
+| `exe/orbitcast` | wrapper that execs the vendored binary |
+| `lib/orbitcast/launcher.rb` | argv/env handling, single Rails boot for `serve` |
+| `lib/orbitcast/binary.rb` | vendored binary resolution, `ORBITCAST_BINARY` override |
+| `lib/orbitcast/configuration.rb` | validated settings |
+| `lib/orbitcast/streams.rb` | `Orbitcast.signed_stream_name` |
+| `lib/orbitcast/recovery.rb` | `Orbitcast.recovery_token` (opt-in retained replay) |
+| `lib/orbitcast/publisher/postgres.rb` | pooled `pg_notify` publisher |
+| `lib/orbitcast/publisher/http.rb` | private-ingress publisher (`publish_via: :http`) |
+| `lib/orbitcast/publisher/instrumentation.rb` | `publish.orbitcast` notifications for both publishers |
+| `lib/orbitcast/publisher/control.rb` | control-message publisher (`Orbitcast.disconnect`) |
+| `lib/action_cable/subscription_adapter/orbitcast.rb` | publish-only cable adapter |
+| `lib/orbitcast/connection.rb`, `lib/orbitcast/channel.rb` | dispatch-mode `ApplicationCable` bases |
+| `lib/orbitcast/rails_endpoint.rb` | the private Rack endpoint the relay calls (dispatch mode) |
+| `lib/orbitcast/engine.rb` | `config.orbitcast.*`, `db/orbitcast_migrate` migration path, derived stream key, mounts the RPC endpoint in dispatch mode; never launches the relay |
+| `lib/generators/orbitcast/install/` | `bin/rails generate orbitcast:install` |
+| `db/orbitcast_migrate/` | overflow, presence, and broker migrations |
+
+## Install
+
+```bash
+bin/rails generate orbitcast:install            # or --overflow
+```
+
+The installer applies, idempotently: `config/cable.yml` (`adapter: orbitcast`),
+`config/initializers/orbitcast.rb`, the four cable lines in
+`config/environments/{development,production}.rb` (`mount_path = nil`, `url`,
+`allowed_request_origins`, `config.orbitcast.mode = :signed` — existing values
+kept), `action_cable_meta_tag` in the layout `<head>`, and a `cable:` entry in
+`Procfile.dev`. Importmap pins and Solid Queue/Cache settings are untouched.
+`--overflow` also copies the overflow migration (picked up by `bin/rails
+db:migrate` through the engine) and sets `overflow_enabled: true`.
+
+```yaml
+# config/cable.yml
+production:
+  adapter: orbitcast
+  database_url: <%= ENV.fetch("ORBITCAST_DATABASE_URL") %>
+  namespace: "example_production"
+  publish_via: postgres      # or http (ingress_url + ingress_token)
+  connection: pool           # or active_record: join the app transaction
+```
+
+```text
+# Procfile.dev
+cable: bundle exec orbitcast serve
+```
+
+`bundle exec orbitcast --version` and `--help` run the binary directly, without
+booting Rails. `serve` (also a bare `orbitcast`, flags understood) inside an
+application boots Rails once, exports an allowlisted `ORBITCAST_*` environment
+(secrets as strict base64, never argv; `RAILS_MASTER_KEY`/`SECRET_KEY_BASE`
+never), and replaces the Ruby process with the relay. The listener defaults to
+`127.0.0.1:28080` in development/test and must be configured elsewhere
+(`listen_addr` or `ORBITCAST_LISTEN_ADDR`).
+
+Rails-side keys beyond the basics: `listener_database_url`, `listen_addr`,
+`trusted_proxies`, `outbound_queue_messages/bytes`,
+`streams_previous_secrets`, `turbo_previous_secrets`, `connection`. Without an
+explicit `streams_secret` the stream key is derived from
+`Rails.application.key_generator` under `orbitcast/streams/v1/<namespace>`.
+Every publish emits `publish.orbitcast` through `ActiveSupport::Notifications`
+(`stream:`, `bytes:`, `via:`), failures included.
+
+## Platforms
+
+`arm64-darwin`, `x86_64-darwin`, `x86_64-linux-gnu`, `aarch64-linux-gnu`,
+`x86_64-linux-musl`. On anything else, build the crate and point
+`ORBITCAST_BINARY` at the result; the gem never downloads or compiles a binary.
+An override is checked with `<binary> doctor --json` before `serve` uses it:
+the reported `version` must equal the gem's, `features` must include
+`postgres` when publishing through PostgreSQL, and `envelope_versions` must
+include `1` — otherwise `Orbitcast::BinaryError` says exactly what is wrong.
+
+## Tests
+
+No database and no Rails boot required:
+
+```bash
+ruby -Ilib -Itest test/configuration_test.rb   # etc.
+```
+
+## License
+
+BSD-3-Clause. See `LICENSE.txt`.

data/app/assets/javascripts/orbitcast/recovery.js

@@ -0,0 +1,196 @@
+// Orbitcast recovery helper.
+//
+// A plain ES module, importmap-ready: no build step, no bundler, no transpile.
+// It uses only public `@rails/actioncable` APIs and is *never* injected into
+// ordinary Turbo or ActionCable subscriptions - importing this file is the
+// entire opt-in.
+//
+//   import { createRecovery } from "orbitcast/recovery"
+//
+//   const recovery = createRecovery(consumer, {
+//     token: document.querySelector("meta[name=orbitcast-recovery]").content,
+//     onMessage: ({ stream, payload, publicationId }) => render(stream, payload),
+//     onGap: ({ stream, reason }) => location.reload()
+//   })
+//
+// What it does:
+//   1. subscribes to `Orbitcast::RecoveryChannel` with a Rails-minted token,
+//   2. sends `resume` with the cursors it holds, on connect and on every
+//      reconnect,
+//   3. tracks the cursor of every delivery it receives,
+//   4. acknowledges receipt periodically (best effort),
+//   5. reports gaps so the application can resynchronize.
+//
+// Delivery semantics - read this before relying on it:
+//
+//   * **At-least-once, within retention.** The same publication can arrive
+//     twice across a replay-to-live handoff. Deduplicate on `publicationId`;
+//     this helper already drops repeats inside a bounded window, but an
+//     application that must be exactly-once needs its own idempotency.
+//   * **An ack is a receipt, not proof of effect.** It says bytes arrived, not
+//     that the UI applied them. It never gates delivery.
+//   * **A gap is real.** `onGap` means history the server cannot reconstruct:
+//     it expired, it was trimmed, the stream's generation was wiped, another
+//     tab won the fencing race, or live traffic outran the replay buffer. The
+//     only correct response is an application-level resync (refetch the page,
+//     the list, the document), never "ignore it".
+//   * **Cursors are opaque.** Store and echo them; never parse or compare them.
+//   * **Subscribe first, recover last.** The relay replays a stream only while
+//     this connection holds a confirmed subscription to it (the token alone is
+//     never enough), and it checks on every `resume`. Create the application
+//     subscriptions before calling `createRecovery`; ActionCable confirms
+//     subscriptions in creation order, on connect and on every reconnect, so
+//     the order you create them in is the order the relay sees. A stream the
+//     connection is not subscribed to arrives as an `unauthorized` gap.
+//   * **No cursors means "where I left off".** A `resume` sent without any
+//     cursors (a fresh page load that did not persist them) continues from the
+//     last position this session acknowledged, as long as the relay still has
+//     the session; otherwise it starts live. Persist `cursors()` to be exact.
+
+const CHANNEL = "Orbitcast::RecoveryChannel";
+const ACTION = "orbitcast_recovery";
+const DELIVERY_TYPE = "orbitcast_delivery";
+const CONTROL_TYPE = "orbitcast_recovery";
+const DEFAULT_ACK_INTERVAL_MS = 5000;
+const DEDUP_WINDOW = 2000;
+
+/**
+ * Subscribe to Orbitcast recovery on an existing ActionCable consumer.
+ *
+ * @param {object} consumer - a `@rails/actioncable` consumer
+ * @param {object} options
+ * @param {string} options.token - the Rails-minted recovery token
+ * @param {function} [options.onMessage] - ({stream, payload, publicationId, cursor})
+ * @param {function} [options.onGap] - ({stream, reason})
+ * @param {function} [options.onReplayStart] - ({streams})
+ * @param {function} [options.onReplayDone] - ({cursors})
+ * @param {object} [options.cursors] - previously persisted {stream: cursor}
+ * @param {number} [options.ackIntervalMs] - acknowledgement cadence
+ * @returns {{subscription: object, cursors: function, unsubscribe: function}}
+ */
+export function createRecovery(consumer, options = {}) {
+  const { token, cursors: initialCursors = {}, ackIntervalMs = DEFAULT_ACK_INTERVAL_MS } = options;
+  if (!token) throw new Error("orbitcast/recovery: a recovery token is required");
+
+  const cursors = { ...initialCursors };
+  const seen = new Set();
+  const order = [];
+  let ackTimer = null;
+  let acked = null;
+
+  const call = (name, argument) => {
+    const handler = options[name];
+    if (typeof handler === "function") handler(argument);
+  };
+
+  // Bounded deduplication: the same publication may legitimately be delivered
+  // twice across a replay-to-live handoff.
+  const isNew = (publicationId) => {
+    if (!publicationId) return true;
+    if (seen.has(publicationId)) return false;
+    seen.add(publicationId);
+    order.push(publicationId);
+    if (order.length > DEDUP_WINDOW) seen.delete(order.shift());
+    return true;
+  };
+
+  const subscription = consumer.subscriptions.create({ channel: CHANNEL, token }, {
+    // Called on connect *and* on every reconnect: resuming is what turns a
+    // reconnect into "continue from my cursor" instead of "start from now".
+    connected() {
+      send("resume");
+      if (ackIntervalMs > 0 && ackTimer === null) {
+        ackTimer = setInterval(() => acknowledge(), ackIntervalMs);
+      }
+    },
+
+    disconnected() {
+      if (ackTimer !== null) {
+        clearInterval(ackTimer);
+        ackTimer = null;
+      }
+    },
+
+    received(message) {
+      if (!message || typeof message !== "object") return;
+
+      if (message.type === DELIVERY_TYPE) {
+        // The cursor is opaque: store it, never parse it.
+        cursors[message.stream] = message.cursor;
+        if (!isNew(message.publication_id)) return;
+
+        let payload = null;
+        try {
+          // The payload travels as exact JSON *text*, so float and unicode
+          // escaping survive the whole path unchanged.
+          payload = JSON.parse(message.json_payload);
+        } catch (error) {
+          call("onGap", { stream: message.stream, reason: "undecodable_payload" });
+          return;
+        }
+
+        call("onMessage", {
+          stream: message.stream,
+          payload,
+          publicationId: message.publication_id,
+          sequence: message.sequence, // a decimal string: JS numbers are too small
+          generation: message.generation,
+          cursor: message.cursor
+        });
+        return;
+      }
+
+      if (message.type !== CONTROL_TYPE) return;
+
+      switch (message.event) {
+        case "replay_start":
+          call("onReplayStart", { streams: message.streams || [] });
+          break;
+        case "replay_done":
+          call("onReplayDone", { cursors: { ...cursors } });
+          break;
+        case "gap":
+          // History the server cannot reconstruct. Resynchronize; the cursor
+          // is kept so live delivery continues from the current edge.
+          call("onGap", { stream: message.stream, reason: message.reason });
+          break;
+        default:
+          break; // An unknown event is never treated as success.
+      }
+    }
+  });
+
+  // Receipt only. Sent on a timer, skipped when nothing moved, and never
+  // awaited: an unrecorded ack costs a longer replay, never a delivery.
+  function acknowledge() {
+    const encoded = JSON.stringify(cursors);
+    if (encoded === acked) return;
+    acked = encoded;
+    send("ack");
+  }
+
+  // `subscription.perform(action, data)` is ActionCable's client API, and it
+  // writes `data.action = action` before sending — so a call shaped
+  // `perform("message", { action: ACTION, ... })` reaches the server as
+  // `{"action":"message", ...}` and the relay never sees `orbitcast_recovery`.
+  // The action name must therefore be the first argument; the remaining
+  // fields are the v1 recovery command (`version`, `op`, `cursors`).
+  function send(op) {
+    subscription.perform(ACTION, { version: 1, op, cursors: { ...cursors } });
+  }
+
+  return {
+    subscription,
+    /** The cursors held right now; persist them to resume across page loads. */
+    cursors: () => ({ ...cursors }),
+    /** Force an acknowledgement (for example before unload). */
+    acknowledge,
+    unsubscribe() {
+      if (ackTimer !== null) clearInterval(ackTimer);
+      ackTimer = null;
+      subscription.unsubscribe();
+    }
+  };
+}
+
+export default createRecovery;

data/db/orbitcast_migrate/001_create_orbitcast_payloads.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Overflow relay table for publications too large for a PostgreSQL NOTIFY
+# payload (8000 bytes, envelope and escaping included).
+#
+# Contract shared with the Rust server (`src/pubsub/postgres.rs`); the column
+# names and types below are wire contract, not an implementation detail:
+#
+#   orbitcast_payloads(id uuid primary key, namespace text not null,
+#                      stream text not null, json_payload text not null,
+#                      expires_at timestamptz not null)
+#
+# The publisher inserts one row and emits its `kind: "overflow"` reference in
+# the *same transaction*, so no node can observe a reference to a row it cannot
+# read. Every listening node fetches the row from the same primary with a fresh
+# READ COMMITTED snapshot; nobody deletes it after their own delivery. Expiry
+# cleanup belongs to the Rust server, which is why `expires_at` is indexed.
+#
+# This is a relay, not durable history: it is not replay, not offline delivery,
+# and not a guarantee of delivery during a listener outage. Install it in the
+# cable database (which may be separate from the primary application database).
+class CreateOrbitcastPayloads < ActiveRecord::Migration[8.1]
+  def change
+    create_table :orbitcast_payloads, id: false do |t|
+      # `default: nil`: the id is always the publication UUID supplied by the
+      # publisher, so no gen_random_uuid()/pgcrypto default is needed.
+      t.primary_key :id, :uuid, default: nil
+      t.text :namespace, null: false
+      t.text :stream, null: false
+      t.text :json_payload, null: false
+      # Explicitly timestamptz rather than `t.datetime`: expiry is compared
+      # against the database clock (`now()`), never an application clock, and
+      # must not depend on the app's `datetime_type` default.
+      t.column :expires_at, :timestamptz, null: false
+    end
+
+    add_index :orbitcast_payloads, :expires_at
+  end
+end

data/db/orbitcast_migrate/002_create_orbitcast_presence.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Presence leases for authorized, distributed presence.
+#
+# Contract shared with the Rust server (`src/presence/postgres.rs`); the column
+# names and types below are wire contract, not an implementation detail:
+#
+#   orbitcast_presence(namespace text not null, stream text not null,
+#                      subject_id text not null, session_id text not null,
+#                      node_id text not null, metadata text not null,
+#                      expires_at timestamptz not null,
+#                      primary key (namespace, stream, subject_id, session_id))
+#
+# One row is one *session's* lease: a subject with three tabs holds three rows,
+# so one tab's refresh can never preserve another tab's lease. Clients see the
+# aggregate - the first live lease announces a join, the last one to go
+# announces a leave - and that decision is serialized per (namespace, stream,
+# subject_id) with a PostgreSQL advisory transaction lock.
+#
+# `metadata` is text, not jsonb: it holds the exact JSON the Rails
+# `presence_grant` effect produced, byte for byte, and is never queried into.
+# The identity in `subject_id` and everything in `metadata` are *public to the
+# stream's granted subscribers* - never put a session token, an email, or any
+# other sensitive connection attribute there.
+#
+# Rows are removed by whichever node sweeps first; `expires_at` is compared
+# against the database clock (`now()`), never an application clock, which is
+# what bounds staleness when a node dies without releasing its leases. Presence
+# is eventually consistent and is not an authorization database.
+#
+# Install it in the cable database (which may be separate from the primary
+# application database). Only needed for Rails-dispatch deployments that grant
+# presence; a signed-only deployment never writes here.
+class CreateOrbitcastPresence < ActiveRecord::Migration[8.1]
+  def change
+    create_table :orbitcast_presence, id: false, primary_key: %i[namespace stream subject_id session_id] do |t|
+      t.text :namespace, null: false
+      t.text :stream, null: false
+      t.text :subject_id, null: false
+      t.text :session_id, null: false
+      t.text :node_id, null: false
+      t.text :metadata, null: false
+      # Explicitly timestamptz rather than `t.datetime`: expiry is compared
+      # against the database clock and must not depend on the app's
+      # `datetime_type` default.
+      t.column :expires_at, :timestamptz, null: false
+    end
+
+    # The sweeper's scan: expired rows first, bounded per statement.
+    add_index :orbitcast_presence, :expires_at
+    # Roster reads: snapshots and the per-subject counts a transition takes.
+    add_index :orbitcast_presence, %i[namespace stream]
+  end
+end

data/db/orbitcast_migrate/003_create_orbitcast_broker.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+# Retained publications, per-stream ordering, and recovery sessions.
+#
+# Contract shared with the Rust server (`src/broker/postgres.rs`); the column
+# names and types below are wire contract, not an implementation detail:
+#
+#   orbitcast_messages(namespace text, stream text, generation bigint,
+#                      seq bigint, publication_id uuid, json_payload text,
+#                      created_at timestamptz, expires_at timestamptz,
+#                      primary key (namespace, stream, generation, seq))
+#   orbitcast_stream_positions(namespace text, stream text, generation bigint,
+#                              next_seq bigint, updated_at timestamptz,
+#                              primary key (namespace, stream))
+#   orbitcast_sessions(namespace text, session_token_hash text, snapshot text,
+#                      fencing_generation bigint, expires_at timestamptz,
+#                      primary key (namespace, session_token_hash))
+#
+# Ordering. `seq` is assigned inside the transaction that inserts the message,
+# while holding `SELECT ... FOR UPDATE` on that stream's
+# `orbitcast_stream_positions` row. The lock is held until commit, so sequence
+# order *is* commit order and a reader can treat "seq > last_delivered" as
+# "everything I have not seen". A global BIGSERIAL cannot do this: two
+# transactions can take values in one order and commit in the other, which
+# would let a reader skip history permanently. There is deliberately no
+# sequence, no serial column, and no ordering by `created_at`.
+#
+# Generations. `generation` is bumped when retention wipes a stream's history,
+# so an old delivery cursor is recognizably stale instead of silently matching
+# sequence numbers from a new era.
+#
+# Deduplication. The unique index on (namespace, stream, publication_id) makes a
+# repeat publication id a no-op within the retention window: first write wins,
+# and the conflict is counted and warned by the server. After expiry the id is
+# forgotten and may be stored again.
+#
+# Sessions. `session_token_hash` is the SHA-256 hex digest of the recovery
+# token - never the token itself - so a database leak cannot be replayed as a
+# capability. `snapshot` is versioned JSON holding delivery cursors and an
+# identity *reference*: never browser cookies, never Ruby Marshal data, never
+# sensitive connection attributes. `fencing_generation` is bumped atomically by
+# every resume, so two nodes can never restore one session at once.
+#
+# Retention is bounded by time (`expires_at`, swept in batches), by message
+# count per stream (enforced in the publish transaction), and by bytes per
+# stream (swept). Expiry cleanup belongs to the Rust server, which is why both
+# `expires_at` columns are indexed. Install in the cable database (which may be
+# separate from the primary application database); only needed when
+# `broker_enabled` is set on the server.
+class CreateOrbitcastBroker < ActiveRecord::Migration[8.1]
+  def change
+    create_table :orbitcast_messages, id: false,
+                                      primary_key: %i[namespace stream generation seq] do |t|
+      t.text :namespace, null: false
+      t.text :stream, null: false
+      # The history era this sequence belongs to; bumped on a retention wipe.
+      t.bigint :generation, null: false
+      # Per-stream commit order, assigned under the stream's position lock.
+      t.bigint :seq, null: false
+      # The publisher-supplied publication UUID, which is also the client's
+      # deduplication key across a replay-to-live handoff.
+      t.column :publication_id, :uuid, null: false
+      t.text :json_payload, null: false
+      # Explicitly timestamptz rather than `t.datetime`: expiry and retention
+      # are compared against the database clock (`now()`), never an application
+      # clock, and must not depend on the app's `datetime_type` default.
+      t.column :created_at, :timestamptz, null: false, default: -> { "now()" }
+      t.column :expires_at, :timestamptz, null: false
+    end
+
+    # Deduplication within the retention window.
+    add_index :orbitcast_messages, %i[namespace stream publication_id],
+              unique: true, name: "index_orbitcast_messages_on_publication"
+    # The sweeper's scan: expired rows first, bounded per statement.
+    add_index :orbitcast_messages, :expires_at
+
+    create_table :orbitcast_stream_positions, id: false, primary_key: %i[namespace stream] do |t|
+      t.text :namespace, null: false
+      t.text :stream, null: false
+      t.bigint :generation, null: false, default: 1
+      # The sequence the *next* publication will take. The row is locked
+      # FOR UPDATE for the whole publish transaction; that lock is the ordering
+      # mechanism, so this table is never written outside it.
+      t.bigint :next_seq, null: false, default: 1
+      t.column :updated_at, :timestamptz, null: false, default: -> { "now()" }
+    end
+
+    create_table :orbitcast_sessions, id: false,
+                                      primary_key: %i[namespace session_token_hash] do |t|
+      t.text :namespace, null: false
+      # SHA-256 hex of the recovery token. The token itself is never stored.
+      t.text :session_token_hash, null: false
+      # Versioned JSON: {"version":1,"session_id":"...","cursors":{...}}.
+      t.text :snapshot, null: false
+      # Bumped atomically by every resume; the highest holder owns the session.
+      t.bigint :fencing_generation, null: false, default: 0
+      t.column :expires_at, :timestamptz, null: false
+    end
+
+    add_index :orbitcast_sessions, :expires_at
+  end
+end

data/exe/orbitcast

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Thin wrapper around the vendored Orbitcast executable.
+#
+# Only the launcher is loaded here. `require "orbitcast"` would mark the gem as
+# loaded before `Bundler.require` runs inside a Rails boot, which would skip
+# `Orbitcast::Engine` registration entirely.
+require "orbitcast/launcher"
+
+Orbitcast::Launcher.call(ARGV)

data/lib/action_cable/subscription_adapter/orbitcast.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "action_cable/subscription_adapter/base"
+require "orbitcast"
+
+module ActionCable
+  module SubscriptionAdapter
+    # Publish-only ActionCable adapter.
+    #
+    #   # config/cable.yml
+    #   production:
+    #     adapter: orbitcast
+    #     database_url: <%= ENV.fetch("ORBITCAST_DATABASE_URL") %>
+    #     namespace: "example_production"
+    #     publish_via: postgres
+    #
+    # `ActionCable.server.broadcast` and the Turbo broadcast helpers go through
+    # `broadcast`, to `Orbitcast::Publisher::Postgres` (`publish_via: postgres`,
+    # the default) or `Orbitcast::Publisher::Http` (`publish_via: http`).
+    # `shutdown` releases whichever publisher was built, fork-safely.
+    # Subscribing is the Rust relay's job: in signed mode the Ruby
+    # WebSocket endpoint is disabled (`config.action_cable.mount_path = nil`), so
+    # a local `subscribe` call is a configuration bug, not something to satisfy
+    # by starting a second listener.
+    #
+    # Note the `::` prefixes below: inside this class, a bare `Orbitcast`
+    # resolves to the adapter itself, not to the gem's top-level module.
+    class Orbitcast < Base
+      def initialize(server)
+        super
+        @publisher = nil
+        @mutex = Mutex.new
+      end
+
+      # @param channel [String] logical stream name
+      # @param payload [String] JSON text ActionCable already encoded; it is
+      #   embedded verbatim rather than encoded a second time
+      def broadcast(channel, payload)
+        publisher.publish(channel, payload)
+      end
+
+      def subscribe(channel, message_callback, success_callback = nil)
+        raise NotImplementedError, unsupported_message("subscribe", channel)
+      end
+
+      def unsubscribe(channel, message_callback)
+        raise NotImplementedError, unsupported_message("unsubscribe", channel)
+      end
+
+      def shutdown
+        publisher = @mutex.synchronize do
+          current = @publisher
+          @publisher = nil
+          current
+        end
+
+        publisher&.shutdown
+        nil
+      end
+
+      # The publisher, built from `cable.yml` merged over `Orbitcast.config`.
+      def publisher
+        @publisher || @mutex.synchronize { @publisher ||= build_publisher }
+      end
+
+      private
+
+      def build_publisher
+        config = ::Orbitcast.config
+        config.assign(cable_options)
+
+        case config.publish_via
+        when :postgres
+          ::Orbitcast::Publisher::Postgres.new(config)
+        when :http
+          # Loaded here, not at require time: a PostgreSQL deployment never
+          # needs net/http in the adapter's path.
+          require "orbitcast/publisher/http"
+          ::Orbitcast::Publisher::Http.new(config)
+        else
+          # Configuration#publish_via= already rejects anything else; this is the
+          # fail-closed backstop if a new value is added there first.
+          raise ::Orbitcast::ConfigurationError,
+                "publish_via #{config.publish_via.inspect} has no publisher implementation"
+        end
+      end
+
+      # `cable[:id]` is ActionCable's own connection tag and `adapter` selects
+      # us; neither is an Orbitcast setting.
+      def cable_options
+        server.config.cable.to_h.transform_keys(&:to_sym).except(:adapter, :id)
+      end
+
+      def unsupported_message(operation, channel)
+        "Orbitcast does not #{operation} in this process (stream #{channel.inspect}). " \
+          "The Rust relay owns WebSocket connections and PostgreSQL LISTEN; the Rails cable " \
+          "endpoint is disabled in signed mode. Check that config.action_cable.mount_path is nil " \
+          "and that nothing mounts ActionCable::Server in this application."
+      end
+    end
+  end
+end