durable_streams-rails 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c2dc408918802eb41264671f804a2bcee440341b56b53ef2f1e58fa77b84708
-  data.tar.gz: '0496a9b62af4f8ed219f0f6d31df0da2e7f6c6b9ee871de91b11acc1cce8d707'
+  metadata.gz: 9fca76d28cee5e469a38766c7bec549acc60f5a6eddf5b840950ce96329dc31e
+  data.tar.gz: 95b45e16b2a3d40024a71c7281b5f17da3009163145b54148dceb493db919b09
 SHA512:
-  metadata.gz: b4c1e809fdf66dd7b648156d5574c61f8d5ca47c365c60fd2eb4c5366fc7f87ec46bdbae0c32f848c7ef1f60863c9b96f2b5a706c9baff05f2dee082284a3e24
-  data.tar.gz: e41d5c76287f2ccbcf8a3224bb654b40087468d84796bc5c69ed9f37f7425b49a36450bf9e4bf0daec522aaeb9bff3152adc65fb531526b748296e4ea16f2a22
+  metadata.gz: fc8227f3d31a0bbc46028c32f23c3cbdd29e5b09aa7a3ad378b69972fb25a1ed8b5e08b84020918dbdcb071a41329dc7f052ce6cc590f7cc112e7355156d9e39
+  data.tar.gz: f8cd42dc4ec64c26415e9793646d84786e104adcfcfb292c82d5662b181a280668ea13408033742649453049e94453351fbe42a9436224ebad5262943380a9f6

data/README.md

@@ -265,6 +265,65 @@ This gem broadcasts JSON State Protocol events over HTTP/SSE (Durable Streams).
 - [`durable_streams`](https://github.com/tokimonki/durable_streams) — Ruby client for the Durable Streams protocol (resolved automatically via RubyGems)
 - `railties` >= 8.0
 
+## Protocol Coverage
+
+The [Durable Streams protocol](https://github.com/durable-streams/durable-streams/blob/main/PROTOCOL.md)
+defines 8 operations on streams. This gem handles the **server side** — broadcasting events,
+provisioning streams, and authorizing client access via signed URLs. Client-side reads and
+writes are handled by the official
+[`@durable-streams/client`](https://github.com/durable-streams/durable-streams) JavaScript
+package, not this gem.
+
+### Operations
+
+| # | Operation | HTTP | This gem's role |
+|---|---|---|---|
+| 1 | Create | PUT | `StreamProvisioner` — automatic on first use |
+| 2 | Append | POST | `Broadcasts` — `broadcast_event_to`, `broadcast_to` |
+| 3 | Read (catch-up) | GET | Authorization only — `signed_stream_url` |
+| 4 | Read (long-poll) | GET + `live=long-poll` | Authorization only — `signed_stream_url` |
+| 5 | Read (SSE) | GET + `live=sse` | Authorization only — `signed_stream_url` |
+| 6 | Close | POST + `Stream-Closed` | Not yet implemented |
+| 7 | Delete | DELETE | Not yet implemented |
+| 8 | Metadata | HEAD | Not yet implemented |
+
+`signed_stream_url` generates a signed, expiring URL and provisions the stream. The client
+uses this URL with `@durable-streams/client` and chooses the read mode via query parameters —
+the gem doesn't need to know which mode the client will use.
+
+### Access control
+
+Only the server may create streams. The server authenticates with the Durable Streams server
+via API key; clients authenticate via signed, expiring tokens generated by this gem.
+
+| | Create | Append | Read | Close | Delete | Metadata |
+|---|---|---|---|---|---|---|
+| **Server** (this gem) | Yes | Yes | Planned | Planned | Planned | Planned |
+| **Client** (JS package) | No | Planned | Yes | No | No | Planned |
+
+**Yes** = this gem provides the implementation or authorization today.
+**Planned** = permitted by design, not yet implemented.
+**No** = not permitted (security decision).
+
+Client append (planned) enables use cases like live cursors and typing indicators where
+the write payload goes directly to the stream server rather than through a Rails controller.
+The Durable Streams server still performs forward_auth to Rails on every write to verify
+the signed token, but this is lightweight — pure HMAC verification with no database or
+session loading. For reads (SSE), forward_auth happens once at connection time.
+
+### Stream provisioning
+
+The Durable Streams protocol requires explicit stream creation (PUT) before any read or write —
+unlike Action Cable which auto-creates channels on subscribe. `StreamProvisioner` hides this
+requirement from application code:
+
+- `signed_stream_url` calls `ensure_stream_exists` before generating the URL
+- `append_to_stream` calls `ensure_stream_exists` before appending
+- A `Concurrent::Set` cache ensures the PUT only fires once per stream name per process
+
+Whichever path touches a stream first provisions it. The application developer never thinks
+about stream creation.
+
 ## Future
 
 Brewing secretly — an async-backed durable streams server inside Rails.

data/Rakefile

@@ -13,7 +13,7 @@ end
 
 task :test_prereq do
   puts "Preparing test database"
-  `cd test/dummy && RAILS_ENV=test bin/rails db:migrate`
+  system("bin/rails", "db:migrate", chdir: "test/dummy", exception: true)
 end
 
 task default: [ :test_prereq, :test ]

data/app/controllers/durable_streams/rails/auth_controller.rb

@@ -2,8 +2,8 @@ module DurableStreams
   module Rails
     class AuthController < ActionController::API
       def verify
-        if request.headers["X-Forwarded-Uri"]
-          stream_name ? head(:ok) : head(:unauthorized)
+        if request.headers["X-Forwarded-Uri"] && authorized_by_token?
+          head :ok
         elsif valid_server_api_key?
           head :ok
         else
@@ -12,8 +12,23 @@ module DurableStreams
       end
 
       private
-        def stream_name
-          DurableStreams.verify_signed_url(request.headers["X-Forwarded-Uri"])
+        def authorized_by_token?
+          if payload = DurableStreams.verify_signed_url(request.headers["X-Forwarded-Uri"])
+            permissions = Array(payload["permissions"]) & DurableStreams::Rails::StreamName::PERMISSIONS
+            permitted_method?(permissions)
+          end
+        end
+
+        # Only GET and POST reach token auth. PUT and DELETE are server-only
+        # operations authenticated via API key (valid_server_api_key?), not tokens.
+        # See README.md "Access control" for the full matrix.
+        def permitted_method?(permissions)
+          case request.headers["X-Forwarded-Method"]&.upcase
+          when "POST"
+            permissions.include?("write")
+          else
+            permissions.include?("read")
+          end
         end
 
         def valid_server_api_key?

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

@@ -196,7 +196,23 @@ module DurableStreams::Rails::Broadcastable
   end
 
   private
-    def stream_event_attributes(operation:, value: as_json)
+    def stream_event_attributes(operation:, value: to_stream_value)
       { type: model_name.singular, key: id.to_s, value: value, operation: operation }
     end
+
+    # Returns the value used in State Protocol broadcast events. Override this in your model
+    # to customize the serialized payload — for example, to use an Alba resource or any other
+    # serializer instead of the default +as_json+.
+    #
+    #   class Message < ApplicationRecord
+    #     streams_to :room
+    #
+    #     private
+    #       def to_stream_value
+    #         MessageResource.new(self).to_h
+    #       end
+    #   end
+    def to_stream_value
+      as_json
+    end
 end

data/lib/durable_streams/rails/broadcasts.rb

@@ -2,9 +2,29 @@
 # See <tt>DurableStreams::Rails::Broadcastable</tt> for the user-facing API that invokes these methods with most of the
 # paperwork filled out already.
 #
-# Can be used directly using something like <tt>DurableStreams.broadcast_event_to :room, type: "message", key: "5",
-# value: { content: "Hello" }, operation: :insert</tt>.
+# All broadcasts produce JSON. Two flavors are supported:
+#
+# ==== State Protocol events
+#
+# <tt>broadcast_event_to</tt> and <tt>broadcast_event_later_to</tt> produce State Protocol events —
+# the keyed insert/update/delete format consumed by <tt>@durable-streams/state</tt> and <tt>@tanstack/db</tt>
+# for reactive collections on the client:
+#
+#     DurableStreams.broadcast_event_to :room, type: "message", key: "5",
+#       value: { content: "Hello" }, operation: :insert
+#
+# ==== Arbitrary JSON
+#
+# <tt>broadcast_to</tt> sends free-form JSON with no State Protocol structure:
+#
+#     DurableStreams.broadcast_to :room, event: "typing", user_id: 5
+#
+# Although the underlying Durable Streams server supports any content type (bytes, text, etc.),
+# this gem only creates <tt>application/json</tt> streams. Non-JSON broadcasts would require
+# extending <tt>append_to_stream</tt> to accept a configurable content type.
 module DurableStreams::Rails::Broadcasts
+  # Broadcast a State Protocol event to one or more streamables. Returns the generated +txid+
+  # for optimistic update confirmation on the client, or +nil+ if streamables are blank.
   def broadcast_event_to(*streamables, type:, key:, value:, operation:)
     streamables.flatten!
     streamables.compact_blank!
@@ -45,11 +65,19 @@ module DurableStreams::Rails::Broadcasts
   end
 
   private
+    # Single transport point for all broadcasts. Testing intercepts here.
+    #
+    # Content type is hardcoded to <tt>application/json</tt> because every public method in this
+    # module produces JSON (State Protocol events via +broadcast_event_to+, free-form JSON via
+    # +broadcast_to+). This ensures the POST body is correctly wrapped in a JSON array for the
+    # Durable Streams server. If non-JSON broadcast support is needed in the future, this method
+    # should accept a content type parameter.
     def append_to_stream(stream_name, message)
       if DurableStreams::Rails::Testing.recording?
         DurableStreams::Rails::Testing.record(stream_name, message)
       else
-        stream(stream_name).append(message)
+        ensure_stream_exists(stream_name)
+        DurableStreams::Stream.new(stream_name, context: DurableStreams.default_context, content_type: "application/json").append(message)
       end
     end
 end

data/lib/durable_streams/rails/server_config.rb

@@ -13,6 +13,12 @@ module DurableStreams
         }
 
         <%= address %> {
+        	log {
+        		output stderr
+        		format <%= log_format %>
+        		level <%= log_level %>
+        	}
+
         	route <%= route_path %> {
         		forward_auth <%= auth["url"] %> {
         			uri <%= auth["path"] %>
@@ -54,6 +60,14 @@ module DurableStreams
           auth.fetch("copy_headers", [ "Cookie" ])
         end
 
+        def log_format
+          @config.fetch("log_format", "console")
+        end
+
+        def log_level
+          @config.fetch("log_level", "INFO")
+        end
+
         def storage_block
           if dir = @config.dig("storage", "data_dir")
             " {\n\t\t\tdata_dir #{dir}\n\t\t}"

data/lib/durable_streams/rails/stream_name.rb

@@ -2,15 +2,31 @@
 # are exposed directly to the client via signed URL tokens, we need to ensure that the name isn't
 # tampered with, so the names are signed upon generation and verified upon receipt. All verification
 # happens through the <tt>DurableStreams.signed_stream_verifier</tt>.
+#
+# Tokens embed a permissions array (<tt>["read"]</tt>, <tt>["write"]</tt>, or
+# <tt>["read", "write"]</tt>) that determines what operations the client can perform.
+# The auth controller checks the permissions against the HTTP method of the incoming request.
 module DurableStreams::Rails::StreamName
-  # Used by the stream auth endpoint to verify a signed stream name.
+  PERMISSIONS = %w[ read write ].freeze
+
+  # Verifies a signed token and returns the payload hash.
+  # Returns +nil+ if the token is invalid or expired.
+  #
+  #     DurableStreams.verified_stream_name(token)
+  #     # => { "stream" => "gid://app/Room/1/messages", "permissions" => ["read"] }
   def verified_stream_name(signed_stream_name)
     DurableStreams.signed_stream_verifier.verified signed_stream_name
   end
 
-  # Used by <tt>DurableStreams.signed_stream_url</tt> to generate a signed stream name.
-  def signed_stream_name(streamables)
-    DurableStreams.signed_stream_verifier.generate stream_name_from(streamables)
+  # Generates a signed token embedding the stream name and permissions.
+  #
+  # Tokens generated without +expires_in+ never expire. Prefer
+  # <tt>DurableStreams.signed_stream_url</tt> for client-facing URLs.
+  def signed_stream_name(streamables, permissions: [ "read" ], expires_in: nil)
+    DurableStreams.signed_stream_verifier.generate(
+      { "stream" => stream_name_from(streamables), "permissions" => permissions.map(&:to_s) },
+      expires_in: expires_in
+    )
   end
 
   private

data/lib/durable_streams/rails/stream_provisioner.rb

@@ -0,0 +1,31 @@
+require "concurrent/set"
+
+# Ensures streams exist on the Durable Streams server before they are used.
+#
+# The Durable Streams protocol requires explicit stream creation (PUT) before any read (GET/SSE)
+# or write (POST) operation — unlike Action Cable which auto-creates channels on subscribe.
+# This module hides that requirement from application code.
+#
+# Both the signing path (<tt>signed_stream_url</tt>) and the broadcast path
+# (<tt>append_to_stream</tt>) call <tt>ensure_stream_exists</tt>. A thread-safe
+# <tt>Concurrent::Set</tt> cache ensures the PUT only fires once per stream name per process,
+# regardless of which path touches the stream first.
+module DurableStreams::Rails::StreamProvisioner
+  private
+    # Creates the stream on the server if it hasn't been created by this process yet.
+    # Idempotent — a 409 means the stream already exists.
+    def ensure_stream_exists(stream_name)
+      return if DurableStreams::Rails::Testing.recording?
+      return if known_streams.include?(stream_name)
+
+      DurableStreams::Stream.new(stream_name, context: DurableStreams.default_context)
+        .create_stream(content_type: "application/json")
+      known_streams.add(stream_name)
+    rescue DurableStreams::StreamExistsError
+      known_streams.add(stream_name)
+    end
+
+    def known_streams
+      @known_streams ||= Concurrent::Set.new
+    end
+end

data/lib/durable_streams/rails/version.rb

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

data/lib/durable_streams-rails.rb

@@ -1,17 +1,20 @@
 require "durable_streams"
+require "durable_streams/rails/engine"
 require "durable_streams/rails/stream_name"
+require "durable_streams/rails/stream_provisioner"
 require "durable_streams/rails/broadcasts"
 require "durable_streams/rails/testing"
-require "durable_streams/rails/engine"
 require "active_support/core_ext/module/attribute_accessors_per_thread"
 
 module DurableStreams
   extend ActiveSupport::Autoload
   extend DurableStreams::Rails::StreamName
+  extend DurableStreams::Rails::StreamProvisioner
   extend DurableStreams::Rails::Broadcasts
 
   mattr_accessor :base_url
   mattr_accessor :draw_routes, default: true
+  mattr_accessor :signed_stream_url_expires_in, default: 24.hours
 
   class << self
     attr_writer :signed_stream_verifier_key, :server_api_key
@@ -28,15 +31,21 @@ module DurableStreams
       @server_api_key or raise ArgumentError, "DurableStreams requires a server_api_key"
     end
 
-    def signed_stream_url(*streamables, expires_in: 24.hours)
+    def signed_stream_url(*streamables, permissions: [ :read ], expires_in: DurableStreams.signed_stream_url_expires_in)
       path = stream_name_from(streamables)
       ensure_stream_exists(path)
-      token = signed_stream_verifier.generate(path, expires_in: expires_in)
+      token = signed_stream_verifier.generate(
+        { "stream" => path, "permissions" => permissions.map(&:to_s) },
+        expires_in: expires_in
+      )
       "#{base_url}/#{path}?token=#{token}"
     end
 
     # Verifies the signed token embedded in a stream URL. Used by the auth controller
     # to validate forward_auth requests from the Durable Streams server.
+    #
+    # Returns a hash with <tt>"stream"</tt> and <tt>"permissions"</tt> keys, or +nil+
+    # if the token is invalid or expired.
     def verify_signed_url(url)
       if token = extract_token_from_url(url)
         verified_stream_name(token)
@@ -48,18 +57,5 @@ module DurableStreams
         Rack::Utils.parse_query(query)["token"]
       end
     end
-
-    private
-      # Creates the stream on the server if it doesn't already exist. Called automatically
-      # by +signed_stream_url+ so clients can subscribe immediately without hitting a 404.
-      # Idempotent — the server returns 200 when the stream already exists with matching config.
-      # Skipped during tests (no server) and when base_url is not configured.
-      def ensure_stream_exists(stream_name)
-        return if DurableStreams::Rails::Testing.recording?
-
-        stream(stream_name).create_stream(content_type: "application/json")
-      rescue DurableStreams::StreamExistsError
-        # Already exists with different config — still usable
-      end
   end
 end

data/lib/generators/durable_streams/install/templates/bin/durable-streams.tt

@@ -20,8 +20,8 @@ RAILS_ENV="${RAILS_ENV:-development}"
 CONFIG_FILE="${APP_ROOT}/tmp/durable_streams.caddyfile"
 
 mkdir -p "${APP_ROOT}/tmp"
-APP_ROOT="$APP_ROOT" RAILS_ENV="$RAILS_ENV" bundle exec ruby -r durable_streams/server_config \
-  -e "puts DurableStreams::ServerConfig.generate(File.join(ENV['APP_ROOT'], 'config/durable_streams.yml'), ENV['RAILS_ENV'])" \
+APP_ROOT="$APP_ROOT" RAILS_ENV="$RAILS_ENV" bundle exec ruby -r durable_streams/rails/server_config \
+  -e "puts DurableStreams::Rails::ServerConfig.generate(File.join(ENV['APP_ROOT'], 'config/durable_streams.yml'), ENV['RAILS_ENV'])" \
   > "$CONFIG_FILE"
 
 exec "$BIN_PATH" run --config "$CONFIG_FILE" "$@"

data/lib/tasks/durable_streams.rake

@@ -4,6 +4,15 @@ namespace :durable_streams do
     require "net/http"
     require "json"
 
+    resolve_latest_version = lambda do
+      uri = URI("https://api.github.com/repos/durable-streams/durable-streams/releases/latest")
+      response = Net::HTTP.get(uri)
+      tag = JSON.parse(response).fetch("tag_name")
+      tag.delete_prefix("v")
+    rescue => e
+      abort "Failed to resolve latest version: #{e.message}"
+    end
+
     version = ENV.fetch("DURABLE_STREAMS_VERSION", "latest")
     install_dir = Rails.root.join("bin", "dist")
     bin_path = install_dir.join("durable-streams-server")
@@ -29,7 +38,7 @@ namespace :durable_streams do
     }
 
     if version == "latest"
-      version = resolve_latest_version
+      version = resolve_latest_version.call
     end
 
     FileUtils.mkdir_p(install_dir)
@@ -43,12 +52,3 @@ namespace :durable_streams do
     puts "Installed to #{bin_path}"
   end
 end
-
-def resolve_latest_version
-  uri = URI("https://api.github.com/repos/durable-streams/durable-streams/releases/latest")
-  response = Net::HTTP.get(uri)
-  tag = JSON.parse(response).fetch("tag_name")
-  tag.delete_prefix("v")
-rescue => e
-  abort "Failed to resolve latest version: #{e.message}"
-end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: durable_streams-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - tokimonki
@@ -58,6 +58,7 @@ files:
 - lib/durable_streams/rails/engine.rb
 - lib/durable_streams/rails/server_config.rb
 - lib/durable_streams/rails/stream_name.rb
+- lib/durable_streams/rails/stream_provisioner.rb
 - lib/durable_streams/rails/testing.rb
 - lib/durable_streams/rails/version.rb
 - lib/generators/durable_streams/install/USAGE