orbitcast 0.3.1-x86_64-linux-gnu

data/lib/orbitcast/recovery.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+
+require_relative "error"
+
+module Orbitcast
+  # Recovery tokens: the capability that lets one browser session replay
+  # retained history on `Orbitcast::RecoveryChannel`.
+  #
+  #   base64(JSON(claims)) + "--" + hex(HMAC-SHA256(recovery_secret, base64_part))
+  #
+  # Same wire shape as `Orbitcast::Streams`, and deliberately **not** the same
+  # key or the same purpose:
+  #
+  # * the key is `config.recovery_secret`, exported to the relay as
+  #   `ORBITCAST_RECOVERY_SECRET_BASE64`. There is no fallback to
+  #   `streams_secret`, in either direction.
+  # * the purpose is `"recover"`, so a subscribe token can never be presented as
+  #   a recovery capability (and vice versa).
+  # * the claims name the exact streams that may be replayed, so a recovery
+  #   token never widens access. Mint it from the same authorization decision
+  #   that produced the subscription, and keep the lifetime short.
+  #
+  # Recovery is opt-in on both sides: nothing here is used unless the
+  # application asks for a token *and* the relay runs with `broker_enabled`.
+  # An unchanged ActionCable or Turbo client never sees any of it.
+  #
+  # Two things the token does **not** do:
+  #
+  # * It does not make history exist. Only publications that pass through the
+  #   relay are retained, which means `config.publish_via = :http`. The
+  #   default `:postgres` path emits `pg_notify` from this process and never
+  #   reaches the broker, so nothing broadcast that way can be replayed - the
+  #   relay has no Ruby-side switch for this, and this module cannot detect
+  #   it; it is a deployment decision.
+  # * It does not authorize by itself. The relay re-checks on every resume
+  #   that the connection is identified, that the token is still valid, and
+  #   that the connection holds a confirmed subscription to each stream it
+  #   replays: `streams` must be the logical names the channels `stream_from`,
+  #   and the browser must subscribe to those channels before it creates the
+  #   recovery subscription.
+  module Recovery
+    CLAIMS_VERSION = 1
+    PURPOSE = "recover"
+    SEPARATOR = "--"
+    DIGEST = "SHA256"
+
+    # Same bound the server enforces (`MAX_RECOVERY_STREAMS`).
+    MAX_STREAMS = 64
+
+    # Default token lifetime, in seconds. Deliberately short: a recovery token
+    # is used at reconnect time, not held for a session's lifetime.
+    DEFAULT_EXPIRES_IN = 900
+
+    class << self
+      # Issue a recovery capability.
+      #
+      # @param session_id [String] an identity *reference* the application
+      #   recognizes. Never a cookie, never sensitive connection state: it is
+      #   stored in the relay's session row.
+      # @param streams [Array<String>] the logical streams this token may
+      #   replay. Exactly the streams the caller already authorized.
+      # @param expires_in [Integer, nil] seconds; defaults to
+      #   {DEFAULT_EXPIRES_IN}
+      # @return [String] the token for a
+      #   `{"channel":"Orbitcast::RecoveryChannel","token":"..."}` identifier
+      def recovery_token(session_id:, streams:, expires_in: nil, config: Orbitcast.config)
+        payload = claims(session_id: session_id, streams: streams,
+                         expires_in: expires_in, config: config)
+        encoded = Base64.strict_encode64(JSON.generate(payload))
+
+        "#{encoded}#{SEPARATOR}#{signature(encoded, config.recovery_secret!)}"
+      end
+
+      # The claim set, in the fixed key order the server's fixtures pin:
+      # version, namespace, session_id, streams, purpose, expires_at.
+      def claims(session_id:, streams:, expires_in: nil, config: Orbitcast.config, now: Time.now)
+        ttl = expires_in.nil? ? DEFAULT_EXPIRES_IN : Integer(expires_in)
+        raise ConfigurationError, "expires_in must be greater than zero" unless ttl.positive?
+
+        namespace = config.namespace
+        raise ConfigurationError, "namespace is required to sign recovery tokens" if namespace.nil?
+
+        {
+          version: CLAIMS_VERSION,
+          namespace: namespace,
+          session_id: validated_session_id(session_id),
+          streams: validated_streams(streams),
+          purpose: PURPOSE,
+          expires_at: now.to_i + ttl
+        }
+      end
+
+      # Exposed for tests and for `orbitcast doctor`; the server owns the
+      # authoritative verifier.
+      def signature(encoded, key)
+        OpenSSL::HMAC.hexdigest(DIGEST, key, encoded)
+      end
+
+      private
+
+      def validated_session_id(session_id)
+        unless session_id.is_a?(String)
+          raise ArgumentError, "session_id must be a String, got #{session_id.class}"
+        end
+        raise ArgumentError, "session_id must not be empty" if session_id.empty?
+
+        session_id
+      end
+
+      # A token grants exactly what it names, so an empty list is refused here
+      # rather than minted into a token the server would reject anyway.
+      def validated_streams(streams)
+        unless streams.is_a?(Array)
+          raise ArgumentError, "streams must be an Array of stream names, got #{streams.class}"
+        end
+        raise ArgumentError, "streams must not be empty" if streams.empty?
+
+        if streams.length > MAX_STREAMS
+          raise ArgumentError, "streams must name at most #{MAX_STREAMS} streams"
+        end
+
+        streams.map do |stream|
+          unless stream.is_a?(String)
+            raise ArgumentError, "stream must be a String, got #{stream.class}"
+          end
+          raise ArgumentError, "stream must not be empty" if stream.empty?
+
+          stream
+        end
+      end
+    end
+  end
+
+  # The dedicated recovery key.
+  #
+  # Added here rather than in `Configuration`'s attribute allowlist so that
+  # recovery stays a separate, opt-in concern: set it explicitly
+  # (`Orbitcast.config.recovery_secret = ...`), and export it to the relay as
+  # `ORBITCAST_RECOVERY_SECRET_BASE64`.
+  class Configuration
+    # `recovery_secret` reader/writer live in configuration.rb with the other
+    # secrets (shared normalizer); only the bang helper is recovery-specific.
+    def recovery_secret!
+      return recovery_secret if recovery_secret
+
+      raise ConfigurationError,
+            "recovery_secret is not configured; set config.orbitcast.recovery_secret " \
+            "(exported to the relay as ORBITCAST_RECOVERY_SECRET_BASE64) before signing " \
+            "recovery tokens"
+    end
+  end
+
+  class << self
+    # Issue a recovery capability for `streams`. The result goes into an
+    # ordinary ActionCable identifier:
+    # {"channel":"Orbitcast::RecoveryChannel","token":"..."}.
+    def recovery_token(session_id:, streams:, expires_in: nil)
+      Recovery.recovery_token(session_id: session_id, streams: streams,
+                              expires_in: expires_in, config: config)
+    end
+  end
+end

data/lib/orbitcast/state_codec.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "error"
+require_relative "protocol"
+
+module Orbitcast
+  # Declared state serialization.
+  #
+  # Rails-dispatch requests are stateless: the relay holds the declared
+  # connection and channel state between calls and hands it back on the next
+  # one. That only works if what crosses the wire is *data*, so this codec
+  # supports exactly two things:
+  #
+  #   * JSON primitives (and arrays/objects of them), and
+  #   * records, tagged explicitly as `{"_gid": "gid://app/User/7"}`.
+  #
+  # There is no Marshal, no YAML, no arbitrary instance variables, and no
+  # implicit capture of anything: state is declared with `orbitcast_state`, or
+  # it does not survive the request. Ordinary memoization stays per-call.
+  #
+  #   class ApplicationCable::Connection < Orbitcast::Connection
+  #     identified_by :current_user
+  #     orbitcast_state :locale, :cart
+  #   end
+  #
+  # A `_gid` whose record was deleted between two requests restores as **nil**,
+  # not an exception: the relay cannot retry a callback that has already run,
+  # and a channel that requires the record must check for it. The same goes for
+  # a reference the application is no longer allowed to locate — `GlobalID`
+  # locators raise, and a raised locator is a missing record here.
+  module StateCodec
+    # The tag that makes a record reference explicit. A plain Hash carrying this
+    # key cannot be encoded, because it would be indistinguishable from one.
+    GID_KEY = "_gid"
+
+    class << self
+      # @return [Object] a JSON-ready value
+      # @raise [ProtocolError] for anything that is not declared-state material
+      def dump(value)
+        case value
+        when nil, true, false, String, Integer then value
+        when Float
+          unless value.finite?
+            raise Orbitcast::ProtocolError.new("declared state cannot hold #{value}", field: "state")
+          end
+
+          value
+        when Symbol then value.to_s
+        when Array then value.map { |entry| dump(entry) }
+        when Hash then dump_hash(value)
+        else
+          dump_record(value)
+        end
+      end
+
+      # @return [Object] the restored value; a missing record restores as nil
+      def load(value)
+        case value
+        when Array then value.map { |entry| load(entry) }
+        when Hash
+          gid = value[GID_KEY]
+          gid.is_a?(String) && value.size == 1 ? locate(gid) : value.transform_values { |entry| load(entry) }
+        else
+          value
+        end
+      end
+
+      # Dump a whole declared-state map, validating it against the wire limits
+      # before it can reach a reply.
+      def dump_map(hash)
+        map = hash.each_with_object({}) { |(key, value), out| out[key.to_s] = dump(value) }
+        Protocol::V1.validate_state_map!("state", map)
+      end
+
+      def load_map(hash)
+        return {} unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) { |(key, value), out| out[key.to_s] = load(value) }
+      end
+
+      private
+
+      def dump_hash(hash)
+        hash.each_with_object({}) do |(key, value), out|
+          key = key.to_s
+          if key == GID_KEY
+            raise Orbitcast::ProtocolError.new(
+              "declared state cannot hold a raw #{GID_KEY.inspect} key; it is reserved for " \
+              "record references", field: "state"
+            )
+          end
+
+          out[key] = dump(value)
+        end
+      end
+
+      def dump_record(value)
+        unless value.respond_to?(:to_global_id)
+          raise Orbitcast::ProtocolError.new(
+            "declared state holds #{value.class}, which is neither a JSON value nor a " \
+            "GlobalID-identified record. Declared state is serialized, not captured: store an " \
+            "id, or include GlobalID::Identification in the model.", field: "state"
+          )
+        end
+
+        { GID_KEY => value.to_global_id.to_s }
+      end
+
+      # A deleted (or no longer locatable) record is nil, by design.
+      def locate(gid)
+        return nil unless defined?(::GlobalID)
+
+        ::GlobalID::Locator.locate(gid)
+      rescue StandardError
+        nil
+      end
+    end
+
+    # `orbitcast_state :cursor, :user` on a Connection or a Channel.
+    #
+    # Declaring a key defines an accessor for it and nothing else: the value is
+    # dumped after every operation and restored before the next one.
+    #
+    # The accessors are **private**. `cursor` and `self.cursor = value` work
+    # from inside the channel, exactly as an attribute should; what cannot
+    # happen is a client performing `{"action":"cursor=","..."}` and writing
+    # declared state directly — ActionCable's action allowlist is every public
+    # method a channel adds.
+    module Declaration
+      def orbitcast_state(*names)
+        names = names.flatten.map(&:to_sym)
+        names.each do |name|
+          send(:attr_accessor, name)
+          send(:private, name, :"#{name}=")
+        end
+
+        @orbitcast_declared_state_keys = (declared_state_keys + names).uniq.freeze
+      end
+
+      # Declarations inherit: a base class may declare state every channel
+      # keeps, and a subclass adds its own.
+      def orbitcast_state_keys
+        inherited =
+          superclass.respond_to?(:orbitcast_state_keys) ? superclass.orbitcast_state_keys : []
+
+        (inherited + declared_state_keys).uniq.freeze
+      end
+
+      private
+
+      def declared_state_keys
+        @orbitcast_declared_state_keys ||= [].freeze
+      end
+    end
+
+    # The per-instance half of the declaration.
+    module Instance
+      # @return [Hash] the declared state, JSON-ready. Keys whose accessor was
+      #   never written are omitted rather than emitted as null.
+      def orbitcast_dump_state
+        self.class.orbitcast_state_keys.each_with_object({}) do |name, out|
+          ivar = :"@#{name}"
+          next unless instance_variable_defined?(ivar)
+
+          out[name.to_s] = StateCodec.dump(instance_variable_get(ivar))
+        end
+      end
+
+      # @param map [Hash] the state the relay held for this session
+      def orbitcast_restore_state(map)
+        return self unless map.is_a?(Hash)
+
+        self.class.orbitcast_state_keys.each do |name|
+          key = name.to_s
+          next unless map.key?(key)
+
+          instance_variable_set(:"@#{name}", StateCodec.load(map[key]))
+        end
+
+        self
+      end
+    end
+  end
+end

data/lib/orbitcast/streams.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+
+require_relative "error"
+
+module Orbitcast
+  # Orbitcast signed-stream profile.
+  #
+  #   base64(JSON(claims)) + "--" + hex(HMAC-SHA256(key, base64_part))
+  #
+  # The HMAC covers the *encoded* bytes, so a verifier can authenticate the
+  # token before it parses anything. Claims always carry every
+  # authorization-bearing field; a verifier that finds one missing must fail
+  # closed rather than widen access.
+  #
+  # A signed name is a *read* capability. Whisper (client-originated fanout
+  # on the stream) is granted only by the optional `whisper: true` claim,
+  # emitted only when asked for so plain tokens keep their exact bytes; the
+  # relay never grants it to Turbo, CableReady, or public streams
+  #
+  # This is not Turbo's profile. `Turbo::StreamsChannel.signed_stream_name`
+  # signs a bare stream string with Turbo's own verifier key and is parsed
+  # separately by the server.
+  module Streams
+    CLAIMS_VERSION = 1
+    PURPOSE = "subscribe"
+    SEPARATOR = "--"
+    DIGEST = "SHA256"
+
+    # The relay refuses a stream longer than this (UTF-8 bytes) on every path:
+    # signed-name claims, Turbo payloads, publications. Mirrored here so the
+    # producer fails before signing or publishing something undeliverable.
+    MAX_STREAM_BYTES = 1024
+
+    class << self
+      # @param stream [String] logical stream name
+      # @param expires_in [Integer, nil] seconds; defaults to
+      #   `config.stream_expires_in`
+      # @param whisper [Boolean] also grant whisper on the stream
+      # @return [String] signed stream name for a channel identifier
+      def signed_stream_name(stream, expires_in: nil, whisper: false, config: Orbitcast.config)
+        claims = claims(stream, expires_in: expires_in, whisper: whisper, config: config)
+        encoded = Base64.strict_encode64(JSON.generate(claims))
+
+        "#{encoded}#{SEPARATOR}#{signature(encoded, config.streams_secret!)}"
+      end
+
+      # The claims, in the fixed key order the fixtures pin: version,
+      # namespace, stream, purpose, expires_at, then `whisper` only when true.
+      def claims(stream, expires_in: nil, whisper: false, config: Orbitcast.config, now: Time.now)
+        stream = validated_stream(stream)
+        ttl = expires_in.nil? ? config.stream_expires_in : Integer(expires_in)
+        raise ConfigurationError, "expires_in must be greater than zero" unless ttl.positive?
+
+        namespace = config.namespace
+        raise ConfigurationError, "namespace is required to sign stream names" if namespace.nil?
+
+        unless [true, false].include?(whisper)
+          raise ArgumentError, "whisper must be true or false, got #{whisper.inspect}"
+        end
+
+        claims = {
+          version: CLAIMS_VERSION,
+          namespace: namespace,
+          stream: stream,
+          purpose: PURPOSE,
+          expires_at: now.to_i + ttl
+        }
+        claims[:whisper] = true if whisper
+        claims
+      end
+
+      # Exposed for tests and for `orbitcast doctor`; the server owns the
+      # authoritative verifier.
+      def signature(encoded, key)
+        OpenSSL::HMAC.hexdigest(DIGEST, key, encoded)
+      end
+
+      # The one stream-name guard, shared with the publisher
+      # (`Orbitcast::Publisher::Postgres`): a stream name is the routing key of
+      # both a signed token and a notice envelope, so the two paths must reject
+      # exactly the same values.
+      #
+      # @param stream [String] logical stream name
+      # @return [String] the validated name
+      # @raise [ArgumentError] when it is not a String, is empty, is not valid
+      #   UTF-8, or exceeds {MAX_STREAM_BYTES}
+      def validated_stream(stream)
+        unless stream.is_a?(String)
+          raise ArgumentError, "stream must be a String, got #{stream.class}"
+        end
+
+        stream = stream.to_s
+        raise ArgumentError, "stream must not be empty" if stream.empty?
+
+        unless stream.valid_encoding?
+          raise ArgumentError, "stream is not valid #{stream.encoding}"
+        end
+
+        unless stream.encoding == Encoding::UTF_8
+          begin
+            stream = stream.encode(Encoding::UTF_8)
+          rescue EncodingError => e
+            raise ArgumentError, "stream must be UTF-8 text (#{e.message})"
+          end
+        end
+        if stream.bytesize > MAX_STREAM_BYTES
+          raise ArgumentError,
+                "stream is #{stream.bytesize} bytes; the maximum is #{MAX_STREAM_BYTES} " \
+                "bytes of UTF-8 (the relay refuses longer streams)"
+        end
+
+        stream
+      end
+    end
+  end
+
+  class << self
+    # Issue a read capability for `stream` (plus whisper when `whisper:
+    # true`). The result goes into an ordinary ActionCable identifier:
+    # {"channel":"Orbitcast::StreamsChannel","signed_stream_name":"..."}.
+    def signed_stream_name(stream, expires_in: nil, whisper: false)
+      Streams.signed_stream_name(stream, expires_in: expires_in, whisper: whisper, config: config)
+    end
+  end
+end

data/lib/orbitcast/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Orbitcast
+  # Release version.
+  #
+  # `Cargo.toml` is the release authority; release-please keeps this constant in
+  # lockstep through its extra-file updater. The trailing annotation below is the
+  # updater marker -- do not reformat the line or the bump will silently no-op.
+  VERSION = "0.3.1" # x-release-please-version
+end

data/lib/orbitcast.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "orbitcast/version"
+require_relative "orbitcast/error"
+require_relative "orbitcast/configuration"
+require_relative "orbitcast/protocol"
+require_relative "orbitcast/state_codec"
+require_relative "orbitcast/streams"
+require_relative "orbitcast/recovery"
+
+# Orbitcast: Rails real-time stack backed by the Orbitcast Rust relay.
+#
+# Loading this file must not require Rails, ActionCable, or pg. Rails-touching
+# code is loaded lazily:
+#
+#   * `Orbitcast::Engine` only when `Rails::Engine` is already defined
+#   * `ActionCable::SubscriptionAdapter::Orbitcast` by ActionCable's own adapter
+#     lookup
+#   * `pg` by `Orbitcast::Publisher::Postgres` when it opens a connection
+#
+# Constant and file names follow the Zeitwerk convention so an application can
+# reference `Orbitcast::Publisher::Postgres` without a classic-loader fallback.
+module Orbitcast
+  # Rails-dispatch surface. These need ActionCable, so they load on first
+  # reference rather than at require time: a signed-mode
+  # application, the executable wrapper, and the plain unit suite never touch
+  # them.
+  autoload :Channel, "orbitcast/channel"
+  autoload :ChannelRegistry, "orbitcast/channel_registry"
+  autoload :Connection, "orbitcast/connection"
+  autoload :Dispatcher, "orbitcast/dispatcher"
+  autoload :RailsEndpoint, "orbitcast/rails_endpoint"
+
+  class << self
+    # Global configuration. Applications normally write through the engine
+    # (`config.orbitcast.*`) or `cable.yml`; `configure` is the direct path.
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config if block_given?
+      config
+    end
+
+    # Test/boot helper: drop the memoized configuration.
+    def reset_config!
+      @config = nil
+    end
+
+    def version
+      VERSION
+    end
+  end
+end
+
+require_relative "orbitcast/binary"
+require_relative "orbitcast/publisher/postgres"
+require_relative "orbitcast/control"
+
+# Rails integration, only when a host application already loaded Rails.
+#
+# The Rails-dispatch execution bases (`Orbitcast::Connection`,
+# `Orbitcast::Channel`, `Orbitcast::Dispatcher`, `Orbitcast::RailsEndpoint`)
+# need ActionCable and are NOT loaded here: the Engine requires the endpoint in
+# dispatch mode, and an application's `ApplicationCable` classes require the
+# bases themselves. A signed-mode application loads none of it.
+require_relative "orbitcast/engine" if defined?(::Rails::Engine)

data/vendor/x86_64-linux-gnu/manifest.json

@@ -0,0 +1,14 @@
+{
+  "version": "0.3.1",
+  "target": "x86_64-unknown-linux-gnu",
+  "features": [
+    "postgres"
+  ],
+  "envelope_versions": [
+    1
+  ],
+  "rust_toolchain": "1.99",
+  "commit": "b9d10e789b0530850e7ce4e7788111ce9d012a2f",
+  "glibc_floor": "2.34",
+  "gem_platform": "x86_64-linux-gnu"
+}