async-cable 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9aa3fe6a825d58f713ffd71b32b26bd034de7f3175ee6b9505e4f53433f6999
-  data.tar.gz: 5bea7df4792f6f0bf2ed0847437ac13f23972de50b443854f597b4f9b8b6defa
+  metadata.gz: 64b5004bfcc84dfe1543ece45d15e55d3ac076d0df64f92b14da2f2ebcc0fd15
+  data.tar.gz: 0e7dc74beaeee2474d7f9bbe4105c27635428e0a10ce1e3cd4780f0fc7ddbf14
 SHA512:
-  metadata.gz: 2291b430d4dbfd1072d8dadb1643857e71e84ef749dd08f6bb97168cdb842af6edf6da703d41acc370d9899e0130fffd068ac568a0d5bf269306746e3aeefe11
-  data.tar.gz: aa8346b8289d1dbe14e606631506ee5a2801cef846a67b13cb0e092806f0da1c6cdf980358b43163c3b2a614fea71bd5f8363383051f741ff39a03794a0e5ff7
+  metadata.gz: 87dca6eb0c213a4cc5ee212b302849c90343d8b5f391ec9b01e992320186d2663de721e7e448e0e536d63b7f68b19ea941c23a94cd75933bc2371c8587baa1dc
+  data.tar.gz: 25d1d6593eba5a4feb0af33355fda19510abde0f9dddcd0f8833d49c1ae7097af9c938011fac1dbbb4fbf0e77670b7c13ac9238be709c46d203bc6f1a51842cd

data/lib/async/cable/middleware.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require "async/websocket/adapters/rack"
 require "action_cable"
@@ -10,7 +10,12 @@ require_relative "socket"
 
 module Async
 	module Cable
+		# Rack middleware that intercepts WebSocket upgrade requests and dispatches them to ActionCable, passing all other requests to the next app in the middleware stack.
 		class Middleware
+			# Create a new middleware instance.
+			# @parameter app [#call] The next Rack application in the middleware stack.
+			# @parameter path [String] The URL path that the cable endpoint is mounted at.
+			# @parameter server [ActionCable::Server::Base] The ActionCable server to use.
 			def initialize(app, path: "/cable", server: ActionCable.server)
 				@app = app
 				@path = path
@@ -21,10 +26,16 @@ module Async
 			
 			attr :server
 			
+			# Check whether the request path matches the configured cable path.
+			# @parameter env [Hash] The Rack environment.
+			# @returns [Boolean] Whether the request is for the cable endpoint.
 			def valid_path?(env)
 				env["PATH_INFO"] == @path
 			end
 			
+			# Handle an incoming Rack request. WebSocket upgrade requests on the configured path are handed off to ActionCable; all other requests are forwarded to the next app in the middleware stack.
+			# @parameter env [Hash] The Rack environment.
+			# @returns [Array] A Rack response triple.
 			def call(env)
 				if valid_path?(env) and Async::WebSocket::Adapters::Rack.websocket?(env) and allow_request_origin?(env)
 					Async::WebSocket::Adapters::Rack.open(env, protocols: @protocols) do |websocket|

data/lib/async/cable/railtie.rb

@@ -7,6 +7,7 @@ require_relative "middleware"
 
 module Async
 	module Cable
+		# Rails integration that automatically inserts {Middleware} into the application middleware stack during initialization.
 		class Railtie < Rails::Railtie
 			initializer "async.cable.configure_rails_initialization" do |app|
 				app.middleware.use Async::Cable::Middleware

data/lib/async/cable/socket.rb

@@ -1,66 +1,84 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
-module Async::Cable
-	class Socket
-		def initialize(env, websocket, server, coder: ActiveSupport::JSON)
-			@env = env
-			@websocket = websocket
-			@server = server
-			@coder = coder
-			
-			@output = ::Thread::Queue.new
-		end
-		
-		attr :env
-		
-		def logger
-			@server.logger
-		end
-		
-		def request
-			# Copied from ActionCable::Server::Socket#request
-			@request ||= begin
-				if defined?(Rails.application) && Rails.application
-					environment = Rails.application.env_config.merge(@env)
-				end
+module Async
+	module Cable
+		# Wraps a WebSocket connection to provide the interface expected by ActionCable connections. Buffers outbound messages in a queue and drains them asynchronously so that transmission never blocks the event loop.
+		class Socket
+			# Create a new socket wrapper.
+			# @parameter env [Hash] The Rack environment for the originating request.
+			# @parameter websocket [Async::WebSocket::Connection] The underlying WebSocket connection.
+			# @parameter server [ActionCable::Server::Base] The ActionCable server instance.
+			# @parameter coder [#encode, #decode] Coder used to serialise messages (defaults to `ActiveSupport::JSON`).
+			def initialize(env, websocket, server, coder: ActiveSupport::JSON)
+				@env = env
+				@websocket = websocket
+				@server = server
+				@coder = coder
 				
-				ActionDispatch::Request.new(environment || @env)
+				@output = ::Thread::Queue.new
 			end
-		end
-		
-		def run(parent: Async::Task.current)
-			parent.async do
-				while buffer = @output.pop
-					# Console.debug(self, "Sending cable data:", buffer, flush: @output.empty?)
-					@websocket.send_text(buffer)
-					@websocket.flush if @output.empty?
+			
+			attr :env
+			
+			# The ActionCable server logger.
+			# @returns [Logger]
+			def logger
+				@server.logger
+			end
+			
+			# Build an `ActionDispatch::Request` from the Rack environment, merging Rails application config when available.
+			# @returns [ActionDispatch::Request]
+			def request
+				# Copied from `ActionCable::Server::Socket#request`:
+				@request ||= begin
+					if defined?(Rails.application) && Rails.application
+						environment = Rails.application.env_config.merge(@env)
+					end
+					
+					ActionDispatch::Request.new(environment || @env)
 				end
-			rescue => error
-				Console.error(self, "Error while sending cable data:", error)
-			ensure
-				unless @websocket.closed?
-					@websocket.close_write(error)
+			end
+			
+			# Start an async task that drains the outbound message queue and writes each message to the WebSocket. The task stops when the queue is closed.
+			# @parameter parent [Async::Task] The parent task to spawn under.
+			# @returns [Async::Task]
+			def run(parent: Async::Task.current)
+				parent.async do
+					while buffer = @output.pop
+						# Console.debug(self, "Sending cable data:", buffer, flush: @output.empty?)
+						@websocket.send_text(buffer)
+						@websocket.flush if @output.empty?
+					end
+				rescue => error
+					Console.error(self, "Error while sending cable data:", error)
+				ensure
+					unless @websocket.closed?
+						@websocket.close_write(error)
+					end
 				end
 			end
-		end
-		
-		def transmit(data)
-			# Console.info(self, "Transmitting data:", data, task: Async::Task.current?)
-			@output.push(@coder.encode(data))
-		end
-		
-		def close
-			# Console.info(self, "Closing socket.", task: Async::Task.current?)
-			@output.close
-		end
-		
-		# This can be called from the work pool, off the event loop.
-		def perform_work(receiver, ...)
-			# Console.info(self, "Performing work:", receiver)
-			receiver.send(...)
+			
+			# Encode and enqueue a message for asynchronous delivery to the client.
+			# @parameter data [Object] The data to transmit, which will be encoded by the coder.
+			def transmit(data)
+				# Console.info(self, "Transmitting data:", data, task: Async::Task.current?)
+				@output.push(@coder.encode(data))
+			end
+			
+			# Close the outbound queue, causing the drain task to terminate once all pending messages have been sent.
+			def close
+				# Console.info(self, "Closing socket.", task: Async::Task.current?)
+				@output.close
+			end
+			
+			# This can be called from the work pool, off the event loop.
+			def perform_work(receiver, ...)
+				# Console.info(self, "Performing work:", receiver)
+				receiver.send(...)
+			end
 		end
 	end
 end

data/lib/async/cable/version.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2024, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
+# @namespace
 module Async
+	# @namespace
 	module Cable
-		VERSION = "0.3.0"
+		VERSION = "0.3.1"
 	end
 end

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2023-2024, by Samuel Williams.  
+Copyright, 2023-2026, by Samuel Williams.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -36,6 +36,22 @@ We welcome contributions to this project.
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
 
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
 ### Developer Certificate of Origin
 
 In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-cable
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -104,14 +104,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.10
 specification_version: 4
 summary: An asynchronous adapter for ActionCable.
 test_files: []