durable_streams-rails 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2c0d0059aa29108589948688eb889b80621a9f84886c8a339169025c2e5903e
-  data.tar.gz: 7fc0276d64d016a17309c9b4bfe477efe7f39cc9e7cc956fd1f9c37ab43eee83
+  metadata.gz: 3f4756bb48c61889c0f2ed552d9dfb96d37e15566a7b2c67d38ee3e48a3d2048
+  data.tar.gz: 12c21fd8ff0842f3d121898fe6fe52da2914aa45b25dd1feb9752e232e40f3ca
 SHA512:
-  metadata.gz: befeb7bfcc22eafa2957233250d66e6e242ca59458a64280254fb853c166b973c08d29a1f460028aa0d6d2973fe83149a1462e6bc0f58dc0b5673de932e6042b
-  data.tar.gz: fa48d010d4ced30e4ed5aee82ed8f0305df08fdc368627b6a344d5362e709f0b88804d96d1a471ce5f1d15fa32797a4fcdf636716a59d564fdaef20cf9359354
+  metadata.gz: be4dfd3ea33bfc0a1f641d05ce0a05a725e6d2f57a1f88da6145d4dbb2632b874128da7a4aeb682ad422ad1869bff3d984ae6707d6f68e05d52f5778fe770ff6
+  data.tar.gz: 06a91cc06ff3b1d00314632e6f64e7db4ffbe505844ae31c12c75c644f142f703dbe833fec559279f4f6e05a286c4fbe2476121706320b7d55fc88920113e976

data/lib/durable_streams/rails/broadcasts.rb

@@ -67,6 +67,11 @@ module DurableStreams::Rails::Broadcasts
   private
     # Single transport point for all broadcasts. Testing intercepts here.
     #
+    # ==== Network cost
+    #
+    # PUT via <tt>ensure_stream_exists</tt> (cached after first call per stream per
+    # process — see <tt>StreamProvisioner</tt>), then one POST to append the message.
+    #
     # 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

data/lib/durable_streams/rails/feeds.rb

@@ -0,0 +1,18 @@
+# Provides the read actions for the <tt>DurableStreams</tt> module — the counterpart to
+# <tt>DurableStreams::Rails::Broadcasts</tt> (write path).
+#
+# Broadcasts push data out to streams. Feeds pull data in from streams. Currently
+# limited to stream metadata (offsets via HEAD); future additions may include event
+# replay and catch-up reads.
+module DurableStreams::Rails::Feeds
+  private
+    # Single read point for stream offsets. Testing intercepts here.
+    #
+    # Returns the tail offset from a HEAD request, or <tt>"0"</tt> during testing.
+    def feed_head_offset(stream_name)
+      return "0" if DurableStreams::Rails::Testing.recording?
+
+      DurableStreams::Stream.new(stream_name, context: DurableStreams.default_context)
+        .head.next_offset
+    end
+end

data/lib/durable_streams/rails/version.rb

@@ -1,5 +1,5 @@
 module DurableStreams
   module Rails
-    VERSION = "0.6.2"
+    VERSION = "0.7.0"
   end
 end

data/lib/durable_streams-rails.rb

@@ -3,6 +3,7 @@ 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/feeds"
 require "durable_streams/rails/testing"
 require "active_support/core_ext/module/attribute_accessors_per_thread"
 
@@ -11,6 +12,7 @@ module DurableStreams
   extend DurableStreams::Rails::StreamName
   extend DurableStreams::Rails::StreamProvisioner
   extend DurableStreams::Rails::Broadcasts
+  extend DurableStreams::Rails::Feeds
 
   mattr_accessor :client_url
   mattr_accessor :server_url
@@ -32,6 +34,17 @@ module DurableStreams
       @server_api_key or raise ArgumentError, "DurableStreams requires a server_api_key"
     end
 
+    # Generates a signed URL that grants a client read (or read/write) access to a
+    # Durable Stream identified by the given +streamables+. The URL embeds a signed
+    # token with the stream name, permissions, and expiry.
+    #
+    # Calls <tt>ensure_stream_exists</tt> to guarantee the stream has been created on
+    # the server (PUT, cached after the first call per stream per process — see
+    # <tt>StreamProvisioner</tt>). No other network requests.
+    #
+    #     DurableStreams.signed_stream_url(room, :messages)
+    #     # => "http://localhost:4437/v1/streams/gid://app/Room/1/messages?token=..."
+    #
     def signed_stream_url(*streamables, permissions: [ :read ], expires_in: DurableStreams.signed_stream_url_expires_in)
       path = stream_name_from(streamables)
       ensure_stream_exists(path)
@@ -42,6 +55,31 @@ module DurableStreams
       "#{client_url}/#{path}?token=#{token}"
     end
 
+    # Returns the current tail offset of the stream as an opaque string. The tail offset
+    # is the position where the next append will land — a client that connects from this
+    # offset will receive every event appended after it.
+    #
+    # Uses the same +*streamables+ argument convention as <tt>signed_stream_url</tt>.
+    #
+    # ==== Network cost
+    #
+    # Calls <tt>ensure_stream_exists</tt> (PUT, cached after first call per stream per
+    # process — see <tt>StreamProvisioner</tt>), then one HEAD request per call. HEAD is
+    # the cheapest HTTP request (no body, headers only). On the internal network between
+    # Rails and the stream server, this is sub-millisecond.
+    #
+    # The offset must be fresh — caching would risk serving a stale position that skips
+    # events. This is the correct price for knowing "where is the stream right now."
+    #
+    #     DurableStreams.stream_offset(room, :messages)
+    #     # => "0000000001-0000000000"
+    #
+    def stream_offset(*streamables)
+      path = stream_name_from(streamables)
+      ensure_stream_exists(path)
+      feed_head_offset(path)
+    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.
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: durable_streams-rails
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - tokimonki
@@ -56,6 +56,7 @@ files:
 - lib/durable_streams/rails/broadcastable/test_helper.rb
 - lib/durable_streams/rails/broadcasts.rb
 - lib/durable_streams/rails/engine.rb
+- lib/durable_streams/rails/feeds.rb
 - lib/durable_streams/rails/server_config.rb
 - lib/durable_streams/rails/stream_name.rb
 - lib/durable_streams/rails/stream_provisioner.rb
@@ -86,7 +87,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.9
 specification_version: 4
 summary: Durable Streams integration for Rails
 test_files: []