orbitcast 0.3.1-x86_64-linux-gnu

data/lib/orbitcast/protocol/v1.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../error"
+
+module Orbitcast
+  module Protocol
+    # Version 1 envelopes: limits, tagged values, and the shared semantic
+    # checks.
+    #
+    # Every constant here mirrors one in `src/protocol/v1/`. Rust is the strict
+    # validator of what crosses the wire; Ruby validates its own output before
+    # emitting it, so an envelope Rust would reject never leaves this process.
+    #
+    # Tolerant reading, exactly as documented:
+    #
+    #   | wire condition        | result                |
+    #   | --------------------- | --------------------- |
+    #   | unknown field         | ignored               |
+    #   | absent `version`      | reads as 1            |
+    #   | unknown tagged value  | hard error            |
+    #   | absent `state`/`null` | unchanged             |
+    #   | `state: {}`           | clear                 |
+    module V1
+      VERSION = 1
+
+      # --- operations (also the last path segment of the HTTP binding) -------
+
+      OPERATION_DESCRIBE = "describe"
+      OPERATION_IDENTIFY = "identify"
+      OPERATION_OPEN_CHANNEL = "open_channel"
+      OPERATION_CLOSE_CHANNEL = "close_channel"
+      OPERATION_RUN_ACTION = "run_action"
+      OPERATION_RELEASE_CONNECTION = "release_connection"
+
+      OPERATIONS = [
+        OPERATION_DESCRIBE,
+        OPERATION_IDENTIFY,
+        OPERATION_OPEN_CHANNEL,
+        OPERATION_CLOSE_CHANNEL,
+        OPERATION_RUN_ACTION,
+        OPERATION_RELEASE_CONNECTION
+      ].freeze
+
+      # `describe` is a node-level handshake: no session, no revision.
+      STATEFUL_OPERATIONS = (OPERATIONS - [OPERATION_DESCRIBE]).freeze
+
+      # Operations that run *after* the thing they describe is already gone.
+      # Their effects would address a subscription the relay has tombstoned.
+      TEARDOWN_OPERATIONS = [OPERATION_CLOSE_CHANNEL, OPERATION_RELEASE_CONNECTION].freeze
+
+      # --- outcomes ---------------------------------------------------------
+
+      OUTCOME_ACCEPTED = "accepted"
+      OUTCOME_DENIED = "denied"
+      OUTCOME_FAULT = "fault"
+      OUTCOMES = [OUTCOME_ACCEPTED, OUTCOME_DENIED, OUTCOME_FAULT].freeze
+
+      # --- effects ----------------------------------------------------------
+
+      EFFECT_ADD_STREAM = "add_stream"
+      EFFECT_REMOVE_STREAM = "remove_stream"
+      EFFECT_REMOVE_ALL_STREAMS = "remove_all_streams"
+      EFFECT_TRANSMIT = "transmit"
+      EFFECT_CLOSE = "close"
+      EFFECT_PRESENCE_GRANT = "presence_grant"
+      EFFECT_PRESENCE_REVOKE = "presence_revoke"
+
+      EFFECT_KINDS = [
+        EFFECT_ADD_STREAM, EFFECT_REMOVE_STREAM, EFFECT_REMOVE_ALL_STREAMS,
+        EFFECT_TRANSMIT, EFFECT_CLOSE, EFFECT_PRESENCE_GRANT, EFFECT_PRESENCE_REVOKE
+      ].freeze
+
+      # --- presence (src/protocol/v1/presence.rs) ---------------------------
+      #
+      # Presence needs no transport extension: a client operation rides the
+      # `data` of an ordinary `message`/`perform` command under the reserved
+      # action below, and a server answer rides an ordinary addressed message.
+      #
+      # `PRESENCE_OPERATIONS` is one spelling used in two places: the
+      # `operations` allowlist of a `presence_grant` effect, and the `op` a
+      # client may ask for. The server-to-client `event` values are the same
+      # three words.
+
+      PRESENCE_ACTION = "orbitcast_presence"
+      PRESENCE_MESSAGE_TYPE = "presence"
+
+      PRESENCE_OP_JOIN = "join"
+      PRESENCE_OP_LEAVE = "leave"
+      PRESENCE_OP_SNAPSHOT = "snapshot"
+
+      PRESENCE_OPERATIONS = [
+        PRESENCE_OP_JOIN, PRESENCE_OP_LEAVE, PRESENCE_OP_SNAPSHOT
+      ].freeze
+
+      # Snapshot page window, as the server clamps it.
+      DEFAULT_PRESENCE_PAGE_SIZE = 50
+      MAX_PRESENCE_PAGE_SIZE = 100
+      # Deep paging over a roster is a scan; the ceiling keeps one client from
+      # walking an unbounded OFFSET across the table.
+      MAX_PRESENCE_PAGE_OFFSET = 100_000
+
+      # --- close reasons ----------------------------------------------------
+      #
+      # Rails does not get to invent wire-visible close reasons: the browser
+      # facing `disconnect` frame is framed by Rust and the ActionCable client
+      # only understands these four.
+
+      CLOSE_REASON_UNAUTHORIZED = "unauthorized"
+      CLOSE_REASON_INVALID_REQUEST = "invalid_request"
+      CLOSE_REASON_SERVER_RESTART = "server_restart"
+      CLOSE_REASON_REMOTE = "remote"
+
+      CLOSE_REASONS = [
+        CLOSE_REASON_UNAUTHORIZED, CLOSE_REASON_INVALID_REQUEST,
+        CLOSE_REASON_SERVER_RESTART, CLOSE_REASON_REMOTE
+      ].freeze
+
+      # --- control ----------------------------------------------------------
+
+      CONTROL_KIND_DISCONNECT = "disconnect"
+      CONTROL_KINDS = [CONTROL_KIND_DISCONNECT].freeze
+
+      # --- limits (src/protocol/v1/rpc.rs) ----------------------------------
+
+      MAX_EFFECTS = 64
+      MAX_IDENTIFIER_LEN = 4096
+      MAX_NODE_ID_LEN = 128
+      MAX_NAMESPACE_LEN = 128
+      MAX_STREAM_LEN = 1024
+      MAX_URL_LEN = 8192
+      MAX_ADDRESS_LEN = 256
+      MAX_HEADERS = 32
+      MAX_HEADER_NAME_LEN = 128
+      MAX_HEADER_VALUE_LEN = 8192
+      MAX_STATE_ENTRIES = 64
+      MAX_STATE_KEY_LEN = 128
+      MAX_STATE_LEN = 64 * 1024
+      MAX_PAYLOAD_LEN = 1024 * 1024
+      MAX_TRANSMIT_LEN = MAX_PAYLOAD_LEN
+      MAX_SUBSCRIPTION_STREAMS = 64
+      MAX_RELEASE_SUBSCRIPTIONS = 256
+      MAX_REASON_LEN = 256
+      MAX_SUBJECT_ID_LEN = 256
+      MAX_PRESENCE_METADATA_LEN = 4096
+      MAX_PRESENCE_OPERATIONS = 16
+      MAX_DEADLINE_MS = 60_000
+      MAX_CAPABILITIES = 64
+      MAX_LABEL_LEN = 128
+      MAX_IDENTITY_KEY_LEN = 512
+
+      # Headers that are never forwarded, whatever the allowlist says: they
+      # describe the relay's own hop and reconstructing them here would be a
+      # request-smuggling hazard.
+      HOP_BY_HOP_HEADERS = %w[
+        connection content-length host keep-alive proxy-authenticate
+        proxy-authorization te trailer transfer-encoding upgrade
+      ].freeze
+
+      UUID_PATTERN = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+
+      class << self
+        # An absent version reads as 1; serializers always emit it.
+        def version_of(hash)
+          value = hash["version"]
+          return VERSION if value.nil?
+
+          value
+        end
+
+        def validate_version!(version, field: "version")
+          return VERSION if version == VERSION
+
+          raise ProtocolError.new("unsupported envelope version #{version.inspect}", field: field)
+        end
+
+        def validate_bounded!(field, value, max)
+          unless value.is_a?(String)
+            raise ProtocolError.new("#{field} must be a String, got #{value.class}", field: field)
+          end
+          raise ProtocolError.new("#{field} must not be empty", field: field) if value.empty?
+
+          if value.bytesize > max
+            raise ProtocolError.new(
+              "#{field} is #{value.bytesize} bytes; the maximum is #{max}", field: field
+            )
+          end
+
+          value
+        end
+
+        def validate_namespace!(namespace)
+          validate_bounded!("namespace", namespace, MAX_NAMESPACE_LEN)
+        end
+
+        def validate_stream!(stream)
+          validate_bounded!("stream", stream, MAX_STREAM_LEN)
+        end
+
+        def validate_identifier!(identifier)
+          validate_bounded!("identifier", identifier, MAX_IDENTIFIER_LEN)
+        end
+
+        def validate_uuid!(field, value)
+          validate_bounded!(field, value, 64)
+          return value if value.match?(UUID_PATTERN)
+
+          raise ProtocolError.new("#{field} #{value.inspect} is not a UUID", field: field)
+        end
+
+        def validate_close_reason!(reason)
+          raise ProtocolError.new("reason must not be empty", field: "reason") if reason.to_s.empty?
+          return reason if CLOSE_REASONS.include?(reason)
+
+          raise ProtocolError.new(
+            "reason #{reason.inspect} is not one of #{CLOSE_REASONS.join(", ")}", field: "reason"
+          )
+        end
+
+        # Bounds the entry count, each key, and the *encoded* size: one huge
+        # value is as expensive as many small ones.
+        def validate_state_map!(field, map)
+          unless map.is_a?(Hash)
+            raise ProtocolError.new("#{field} must be an object, got #{map.class}", field: field)
+          end
+
+          if map.size > MAX_STATE_ENTRIES
+            raise ProtocolError.new(
+              "#{field} has #{map.size} entries; the maximum is #{MAX_STATE_ENTRIES}", field: field
+            )
+          end
+
+          map.each_key do |key|
+            unless key.is_a?(String)
+              raise ProtocolError.new("#{field} keys must be Strings, got #{key.class}", field: field)
+            end
+
+            validate_bounded!("state_key", key, MAX_STATE_KEY_LEN)
+          end
+
+          encoded = JSON.generate(map)
+          if encoded.bytesize > MAX_STATE_LEN
+            raise ProtocolError.new(
+              "#{field} encodes to #{encoded.bytesize} bytes; the maximum is #{MAX_STATE_LEN}",
+              field: field
+            )
+          end
+
+          map
+        end
+
+        # Check that an embedded application payload is valid JSON *without*
+        # keeping the decoded value: the exact encoded text is what travels.
+        def validate_json_text!(field, text)
+          unless text.is_a?(String)
+            raise ProtocolError.new("#{field} must be a String, got #{text.class}", field: field)
+          end
+          raise ProtocolError.new("#{field} must not be empty", field: field) if text.empty?
+
+          if text.bytesize > MAX_PAYLOAD_LEN
+            raise ProtocolError.new(
+              "#{field} is #{text.bytesize} bytes; the maximum is #{MAX_PAYLOAD_LEN}", field: field
+            )
+          end
+
+          begin
+            JSON.parse(text)
+          rescue JSON::ParserError => e
+            raise ProtocolError.new("#{field} is not valid JSON: #{e.message}", field: field)
+          end
+
+          text
+        end
+
+        def stateful?(operation)
+          STATEFUL_OPERATIONS.include?(operation)
+        end
+
+        def teardown?(operation)
+          TEARDOWN_OPERATIONS.include?(operation)
+        end
+      end
+    end
+  end
+end
+
+require_relative "v1/effects"
+require_relative "v1/request"
+require_relative "v1/reply"
+require_relative "v1/control_message"

data/lib/orbitcast/protocol.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "protocol/v1"
+
+module Orbitcast
+  # Handwritten JSON envelopes for the Orbitcast wire protocol.
+  #
+  # There is no schema compiler and no generated code: `src/protocol/` is the
+  # authority, these classes are the Ruby reading of it, and
+  # `tests/fixtures/**/*.json` is what keeps the two honest. Both suites consume
+  # the same fixtures; neither regenerates them.
+  #
+  # Everything here must load without Rails: the RPC endpoint needs Rails, the
+  # envelopes do not.
+  module Protocol
+    # The only envelope version this release speaks.
+    VERSION = V1::VERSION
+  end
+end

data/lib/orbitcast/publisher/control.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "postgres"
+require_relative "../protocol"
+
+module Orbitcast
+  module Publisher
+    # Publishes Rails-initiated control messages over the same PostgreSQL
+    # transport as ordinary publications.
+    #
+    # A control message is not a publication: it never reaches a browser, it
+    # carries no application payload, and every node consumes it rather than
+    # forwarding it. It does share the transport, so this subclasses the
+    # publisher to reuse its connection pool, fork safety, and channel-name
+    # derivation instead of opening a second pool for one NOTIFY.
+    #
+    # ## Channel derivation
+    #
+    # `orbitcast_` + the first 48 hex characters of SHA-256 over the
+    # length-prefixed `(namespace, CONTROL_STREAM)` tuple — the same function
+    # every other channel name comes from, with a reserved stream name. A
+    # control message for one namespace is therefore invisible to another
+    # deployment's listener, and the reserved name cannot collide with an
+    # application stream unless the application deliberately publishes to
+    # `__orbitcast_control__`.
+    #
+    # Relay side: the listener session holds a permanent `LISTEN` on this
+    # channel (`Backend::spawn_listener` in `src/server.rs`), and the same
+    # messages are also accepted over `POST /v1/control` on the private ingress
+    # (`src/transport/ingress.rs`). The envelope is pinned by
+    # `tests/fixtures/control/*.json` for both languages.
+    class Control < Postgres
+      # Reserved stream name. Never a browser-visible stream.
+      CONTROL_STREAM = "__orbitcast_control__"
+
+      def self.channel_for(namespace)
+        channel_name(namespace, CONTROL_STREAM)
+      end
+
+      # @param message [Orbitcast::Protocol::V1::ControlMessage]
+      # @return [String] the control UUID, for deduplication in logs
+      def publish_control(message)
+        message.validate!
+
+        unless message.namespace == configuration.namespace
+          raise ArgumentError,
+                "control message namespace #{message.namespace.inspect} does not match the " \
+                "configured namespace #{configuration.namespace.inspect}"
+        end
+
+        wire = message.to_json
+        if wire.bytesize >= MAX_NOTIFY_BYTES
+          raise PayloadTooLarge,
+                "control message is #{wire.bytesize} bytes; PostgreSQL NOTIFY payloads must be " \
+                "under #{MAX_NOTIFY_BYTES} bytes"
+        end
+
+        channel = self.class.channel_for(configuration.namespace)
+        # `@pool` is the parent's bounded, fork-safe pool. Reused deliberately:
+        # one process, one set of publisher connections.
+        @pool.with { |connection| connection.exec_params(NOTIFY_SQL, [channel, wire]) }
+
+        message.control_id
+      end
+    end
+  end
+end

data/lib/orbitcast/publisher/http.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+
+require_relative "postgres"
+require_relative "instrumentation"
+require_relative "../error"
+require_relative "../protocol"
+require_relative "../streams"
+
+module Orbitcast
+  module Publisher
+    # Private HTTP publication ingress: the alternative publication path to
+    # PostgreSQL.
+    #
+    #   config.orbitcast.publish_via  = :http
+    #   config.orbitcast.ingress_url  = "http://127.0.0.1:28081/v1/publications"
+    #   config.orbitcast.ingress_token = Rails.application.credentials.dig(:orbitcast, :ingress_token)
+    #
+    # Chosen when the database credentials must stay on the Rust side, or in a
+    # memory-only build where there is no PostgreSQL to publish through. Rails
+    # publishes through *one* path: never both this and PostgreSQL for the same
+    # broadcast.
+    #
+    # ## Wire contract
+    #
+    #   POST {ingress_url}
+    #   Authorization: Bearer <ingress_token>
+    #   Content-Type: application/json
+    #
+    #   {"version":1,"namespace":"...","id":"<uuid>","stream":"...",
+    #    "json_payload":"<exact ActionCable-encoded JSON text>"}
+    #
+    # which is the v1 `Publication` envelope from `src/protocol/v1/publication.rs`,
+    # byte for byte. A `202` means the backend accepted and committed the
+    # publication, not that a browser saw it.
+    #
+    # Relay side: `POST /v1/publications` on the private ingress listener
+    # (`src/transport/ingress.rs`), which answers `202` with the `IngressAck`
+    # envelope from `src/protocol/v1/publication.rs`. The ack is pinned by
+    # `tests/fixtures/ingress/ack.json` for both languages; this client treats
+    # the status code as the contract and does not require the body.
+    #
+    # ## Failure policy
+    #
+    # No retries. A publication that timed out may or may not have been
+    # accepted, and replaying it would duplicate a browser-visible message;
+    # durable cross-node deduplication belongs to the broker phase.
+    class Http
+      DEFAULT_OPEN_TIMEOUT = 2.0
+      DEFAULT_READ_TIMEOUT = 5.0
+
+      ACCEPTED_STATUSES = %w[200 201 202].freeze
+
+      # @param instrumenter [#instrument] defaults to
+      #   `ActiveSupport::Notifications` when loaded; see
+      #   `Orbitcast::Publisher::Instrumentation`
+      def initialize(configuration = Orbitcast.config, connection_factory: nil, instrumenter: nil)
+        @configuration = configuration.validate!
+        @instrumenter = Instrumentation.resolve(instrumenter)
+        @uri = URI.parse(configuration.ingress_url.to_s)
+        @pool = Postgres::Pool.new(
+          size: configuration.pool_size,
+          timeout: configuration.pool_timeout,
+          &(connection_factory || method(:connect))
+        )
+      end
+
+      attr_reader :configuration
+
+      # @param stream [String] logical stream name
+      # @param payload [String] JSON text already encoded by ActionCable
+      # @return [String] publication UUID
+      def publish(stream, payload)
+        # Both guards run before anything is instrumented or sent: an invalid
+        # stream (empty, over 1024 UTF-8 bytes) or a non-String payload is a
+        # caller error, not a publication that failed.
+        stream = Streams.validated_stream(stream)
+        payload = validated_payload(payload)
+
+        Instrumentation.publish(@instrumenter, stream: stream, bytes: payload.bytesize, via: :http) do
+          if payload.bytesize > configuration.max_publication_size
+            raise PayloadTooLarge,
+                  "publication payload is #{payload.bytesize} bytes; the configured maximum is " \
+                  "#{configuration.max_publication_size} bytes (max_publication_size)"
+          end
+
+          publication_id = SecureRandom.uuid
+          body = JSON.generate(
+            version: Protocol::V1::VERSION,
+            namespace: configuration.namespace,
+            id: publication_id,
+            stream: stream,
+            json_payload: payload
+          )
+
+          # `Pool#with` returns the checkin, not the block: capture the response.
+          response = nil
+          @pool.with { |connection| response = connection.post(@uri, body, bearer) }
+          verify!(response)
+
+          publication_id
+        end
+      end
+
+      def shutdown
+        @pool.shutdown
+      end
+
+      private
+
+      def bearer
+        token = configuration.ingress_token
+        raise ConfigurationError, "ingress_token is required when publish_via is :http" if token.nil?
+
+        "Bearer #{token}"
+      end
+
+      def verify!(response)
+        return if ACCEPTED_STATUSES.include?(response.code.to_s)
+
+        case response.code.to_s
+        when "401", "403"
+          raise IngressError, "publication ingress refused the service credential (#{response.code})"
+        when "413"
+          raise PayloadTooLarge, "publication ingress refused the payload as too large (413)"
+        else
+          raise IngressError, "publication ingress returned HTTP #{response.code}"
+        end
+      end
+
+      def validated_payload(payload)
+        unless payload.is_a?(String)
+          raise ArgumentError,
+                "payload must be the JSON text encoded by ActionCable, got #{payload.class}"
+        end
+        raise ArgumentError, "payload is not valid #{payload.encoding}" unless payload.valid_encoding?
+
+        payload.encoding == Encoding::UTF_8 ? payload : payload.encode(Encoding::UTF_8)
+      end
+
+      def connect
+        Connection.new(@uri, configuration)
+      end
+
+      # One keep-alive HTTP connection, shaped like the pooled objects the
+      # PostgreSQL publisher hands out (`#close`), so both publishers share the
+      # same bounded, fork-safe pool implementation.
+      class Connection
+        def initialize(uri, _configuration)
+          @http = Net::HTTP.new(uri.host, uri.port)
+          @http.use_ssl = uri.scheme == "https"
+          @http.open_timeout = DEFAULT_OPEN_TIMEOUT
+          @http.read_timeout = DEFAULT_READ_TIMEOUT
+          @http.keep_alive_timeout = 30
+        end
+
+        def post(uri, body, authorization)
+          request = Net::HTTP::Post.new(uri.request_uri)
+          request["content-type"] = "application/json"
+          request["accept"] = "application/json"
+          request["authorization"] = authorization
+          request.body = body
+
+          @http.start unless @http.started?
+          @http.request(request)
+        end
+
+        def close
+          @http.finish if @http.started?
+        rescue IOError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/orbitcast/publisher/instrumentation.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Orbitcast
+  module Publisher
+    # `ActiveSupport::Notifications` for publishers, without requiring it.
+    #
+    # Every publish, on every transport, emits one `publish.orbitcast` event
+    # with `stream:`, `bytes:` (the encoded payload size) and `via:`
+    # (`:postgres` or `:http`). A publish that raises still emits the event —
+    # `ActiveSupport::Notifications` adds `:exception` / `:exception_object`
+    # to the payload and the error propagates unchanged — so a subscriber sees
+    # the failure path, never a silent drop:
+    #
+    #   ActiveSupport::Notifications.subscribe("publish.orbitcast") do |event|
+    #     StatsD.timing("orbitcast.publish", event.duration, tags: ["via:#{event.payload[:via]}"])
+    #     Rails.error.report(event.payload[:exception_object]) if event.payload[:exception_object]
+    #   end
+    #
+    # The plain-ruby unit suite has no ActiveSupport; it gets a null
+    # instrumenter (or injects a recording one).
+    module Instrumentation
+      EVENT = "publish.orbitcast"
+
+      # Yields without recording. Same contract as
+      # `ActiveSupport::Notifications.instrument`: the block's value is
+      # returned, an exception propagates.
+      module Null
+        def self.instrument(_name, payload = {})
+          yield payload
+        end
+      end
+
+      class << self
+        def resolve(instrumenter)
+          return instrumenter if instrumenter
+          return ::ActiveSupport::Notifications if defined?(::ActiveSupport::Notifications)
+
+          Null
+        end
+
+        def publish(instrumenter, stream:, bytes:, via:, &block)
+          instrumenter.instrument(EVENT, { stream: stream, bytes: bytes, via: via }, &block)
+        end
+      end
+    end
+  end
+end