durable_streams-rails 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fca76d28cee5e469a38766c7bec549acc60f5a6eddf5b840950ce96329dc31e
-  data.tar.gz: 95b45e16b2a3d40024a71c7281b5f17da3009163145b54148dceb493db919b09
+  metadata.gz: bf65130284ea6d82ba8c5a96a6140d8d90b2a85644150d95e4cccc254e166da4
+  data.tar.gz: a9351da1b24a5a717ad3717eed8faa19f6079c99ef3e9d8300214a1e31558e19
 SHA512:
-  metadata.gz: fc8227f3d31a0bbc46028c32f23c3cbdd29e5b09aa7a3ad378b69972fb25a1ed8b5e08b84020918dbdcb071a41329dc7f052ce6cc590f7cc112e7355156d9e39
-  data.tar.gz: f8cd42dc4ec64c26415e9793646d84786e104adcfcfb292c82d5662b181a280668ea13408033742649453049e94453351fbe42a9436224ebad5262943380a9f6
+  metadata.gz: 48dce7b23beb7d4a5a8c7e37350d5790c25865f20cfebcd31bd80fad574c7179896fae4471289524556ea61836f739936c2e18fcc404fb7b810a4eee55a9f1c5
+  data.tar.gz: e1518c09eeaeaf28a6a92279bac1bc06b962aee73d89b8ead82b7651c7a6910f1a5eb9faa7210d3a4e3f97e2bf030c97df4c736a230e46d9dcf554c8ffc18375

data/README.md

@@ -1,7 +1,7 @@
 # Durable Streams Rails
 
 Durable Streams integration for Rails. Stream State Protocol events from your models to clients
-over SSE with the same developer experience as Turbo Broadcasts — but with offset-based
+over HTTP with the same developer experience as Turbo Broadcasts — but with offset-based
 resumability, persistent event logs, and no WebSocket infrastructure.
 
 ```ruby
@@ -31,7 +31,7 @@ bin/rails generate durable_streams:install
 
 This creates:
 
-- `config/initializers/durable_streams.rb` — sets the stream server URL
+- `config/initializers/durable_streams.rb` — sets `client_url` and `server_url`
 - `config/durable_streams.yml` — server configuration (per environment)
 - `bin/durable-streams` — binstub that auto-downloads and runs the server binary
 - Updates `Procfile.dev` with a `streams:` entry
@@ -188,7 +188,7 @@ DurableStreams.broadcast_to(room, :presence,
 
 ### Signed stream URLs
 
-Generate signed, expirable URLs for client SSE connections:
+Generate signed, expirable URLs for client streaming connections:
 
 ```ruby
 url = DurableStreams.signed_stream_url(room, :messages)
@@ -258,7 +258,7 @@ This gem mirrors `turbo-rails` 1:1 in structure and design:
 | `Turbo::Broadcastable::TestHelper` | `DurableStreams::Rails::Broadcastable::TestHelper` | Test assertions |
 
 The key architectural difference: Turbo broadcasts HTML fragments over WebSockets (Action Cable).
-This gem broadcasts JSON State Protocol events over HTTP/SSE (Durable Streams).
+This gem broadcasts JSON State Protocol events over HTTP (Durable Streams).
 
 ## Dependencies
 
@@ -324,6 +324,50 @@ requirement from application code:
 Whichever path touches a stream first provisions it. The application developer never thinks
 about stream creation.
 
+## Security
+
+### Two URLs, two authentication channels
+
+The gem separates client-facing and server-to-server communication:
+
+```ruby
+# config/initializers/durable_streams.rb
+
+# Client-facing — used by signed_stream_url to build URLs browsers connect to.
+DurableStreams.client_url = ENV.fetch("DURABLE_STREAMS_CLIENT_URL", "http://localhost:4437/v1/streams")
+
+# Server-to-server — used by Rails to POST broadcasts and PUT stream creation.
+# Paired with server_api_key for authentication.
+DurableStreams.server_url = ENV.fetch("DURABLE_STREAMS_SERVER_URL", "http://localhost:4437/v1/streams")
+```
+
+In single-server deployments both point to the same address. In multi-server deployments
+they diverge: `client_url` is the public domain (behind a CDN), `server_url` is the internal
+network address.
+
+`server_url` is never exposed to clients. `client_url` is never used for server-to-server
+communication.
+
+### Client authentication — signed URLs
+
+Browsers receive signed, expiring URLs via Inertia props (or any server-rendered response).
+The token is generated by `MessageVerifier` and encodes the stream name, permissions
+(`read`/`write`), and an expiration timestamp.
+
+When a client connects, the Durable Streams server's `forward_auth` sends the request to
+`AuthController#verify`, which validates the token's signature and expiration.
+
+**The token is domain-agnostic.** It validates *what* (stream name + permissions + expiry),
+not *where* (which host the request is hitting). Network-level controls (firewall/NSG rules)
+must prevent clients from reaching `server_url` directly.
+
+### Server authentication — API key
+
+Rails authenticates to the Durable Streams server with a Bearer token (`server_api_key`)
+sent in the `Authorization` header. The key is auto-derived from
+`Rails.application.key_generator` — consistent across all instances of the same app
+without manual configuration.
+
 ## Future
 
 Brewing secretly — an async-backed durable streams server inside Rails.

data/app/models/concerns/durable_streams/rails/broadcastable.rb

@@ -14,7 +14,7 @@
 #   end
 #
 # This broadcasts a State Protocol insert event to the stream derived from the post association.
-# All clients subscribed to that stream will receive the event as an SSE message.
+# All clients subscribed to that stream will receive the event.
 #
 # There are four basic operations you can broadcast: <tt>insert</tt>, <tt>update</tt>, <tt>upsert</tt>,
 # and <tt>delete</tt>. As a rule, you should use the <tt>_later</tt> versions when broadcasting within

data/lib/durable_streams/rails/engine.rb

@@ -48,9 +48,9 @@ module DurableStreams
             config.durable_streams.server_api_key ||
             ::Rails.application.key_generator.generate_key("durable_streams/server_api_key").unpack1("H*")
 
-          if DurableStreams.base_url.present?
+          if DurableStreams.server_url.present?
             DurableStreams.configure do |c|
-              c.base_url = DurableStreams.base_url
+              c.base_url = DurableStreams.server_url
               c.default_headers = { "Authorization" => "Bearer #{DurableStreams.server_api_key}" }
             end
           end

data/lib/durable_streams/rails/version.rb

@@ -1,5 +1,5 @@
 module DurableStreams
   module Rails
-    VERSION = "0.4.0"
+    VERSION = "0.5.0"
   end
 end

data/lib/durable_streams-rails.rb

@@ -12,7 +12,8 @@ module DurableStreams
   extend DurableStreams::Rails::StreamProvisioner
   extend DurableStreams::Rails::Broadcasts
 
-  mattr_accessor :base_url
+  mattr_accessor :client_url
+  mattr_accessor :server_url
   mattr_accessor :draw_routes, default: true
   mattr_accessor :signed_stream_url_expires_in, default: 24.hours
 
@@ -38,7 +39,7 @@ module DurableStreams
         { "stream" => path, "permissions" => permissions.map(&:to_s) },
         expires_in: expires_in
       )
-      "#{base_url}/#{path}?token=#{token}"
+      "#{client_url}/#{path}?token=#{token}"
     end
 
     # Verifies the signed token embedded in a stream URL. Used by the auth controller

data/lib/generators/durable_streams/install/templates/initializer.rb.tt

@@ -1 +1,7 @@
-DurableStreams.base_url = ENV.fetch("DURABLE_STREAMS_URL", "http://localhost:4437/v1/streams")
+# Client-facing URL for signed stream URLs (what browsers connect to).
+DurableStreams.client_url = ENV.fetch("DURABLE_STREAMS_CLIENT_URL", "http://localhost:4437/v1/streams")
+
+# Server-to-server URL for broadcasts and stream provisioning.
+# In single-server setups this matches client_url. In multi-server deployments
+# this should point to the internal address of the Durable Streams server.
+DurableStreams.server_url = ENV.fetch("DURABLE_STREAMS_SERVER_URL", "http://localhost:4437/v1/streams")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: durable_streams-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - tokimonki
@@ -39,7 +39,7 @@ dependencies:
         version: '8.0'
 description: Stream State Protocol events from Active Record models with the same
   DX as Turbo Broadcasts — declarative streaming, automatic callbacks, and async jobs
-  — but with offset-based resumability and persistent event logs over SSE.
+  — but with offset-based resumability and persistent event logs over HTTP.
 email: opensource@tokimonki.com
 executables: []
 extensions: []