async-bus 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0862030bd7ad9cf8ffe84a3e35e4ec52e3c3f3cc81b8192c5d59cc0bc435e3c
-  data.tar.gz: d2f9a0398f4aa94a35fc3d2dc8aa1d4097777e9f85eeab2ca19405e30d902aa5
+  metadata.gz: f14db24c29a1d9ed24379631bcde98474533dd61397d6cf273bdeea5feabdb42
+  data.tar.gz: 2a1cf6b2528af9626010b95bfde0a4decf985518707c4469dd69f102ad000582
 SHA512:
-  metadata.gz: f4f6d79a2da0ecd4cba25ad79a2be878728701c01113c6f65aa6f9980a863a721f8863841bcfb1c0206f21e25bd0d1b4747a97102b3fbc2b5658dd045c1bf58d
-  data.tar.gz: ecc5632d806ceebbf5b61aebc85ae1b47118303cf9f03320ecc243b403ca7edb00cf60ee966a55cc7c247bd4969897ef10588a97940c55518603fd34afb7c6fc
+  metadata.gz: 23697b989abd95dc326f2ad370ca68c42488a5eb4ddc01efd87e6fd3b102d7221ff5dc872a13c8f400efcf39d7477d8d63980f9eb097a0a6e0456de28106ab18
+  data.tar.gz: bbf61748ccd9685a6708eacf24e32d48b76d9baef531c95a70975427b40afa0552ee05b4a3600900025342bd4ac98c39d1baec4db47482795134b64f55ab3bfc

data/lib/async/bus/client.rb

@@ -1,54 +1,92 @@
 # frozen_string_literal: true
 
-# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# Released under the MIT License.
+# Copyright, 2021-2025, by Samuel Williams.
 
-require_relative 'protocol/connection'
-require 'async/queue'
+require_relative "protocol/connection"
+require "async/queue"
 
 module Async
 	module Bus
+		# Represents a client that can connect to a server.
 		class Client
-			def initialize(endpoint = nil)
+			# Initialize a new client.
+			# @parameter endpoint [IO::Endpoint] The endpoint to connect to.
+			# @parameter options [Hash] Additional options for the connection.
+			def initialize(endpoint = nil, **options)
 				@endpoint = endpoint || Protocol.local_endpoint
-				@queue = Async::Queue.new
+				@options = options
 			end
 			
-			def connect
-				@endpoint.connect do |peer|
-					connection = Protocol::Connection.client(peer)
-					
-					connection_task = Async do
-						connection.run
-					end
-					
-					return yield(connection)
+			# Create a new connection to the server.
+			#
+			# @returns [Protocol::Connection] The new connection.
+			protected def connect!
+				peer = @endpoint.connect
+				return Protocol::Connection.client(peer, **@options)
+			end
+			
+			# Called when a connection is established.
+			# Override this method to perform setup when a connection is established.
+			#
+			# @parameter connection [Protocol::Connection] The established connection.
+			protected def connected!(connection)
+				# Do nothing by default.
+			end
+			
+			# Connect to the server.
+			#
+			# @parameter persist [Boolean] Whether to keep the connection open indefiniely.
+			# @yields {|connection| ...} If a block is given, it will be called with the connection, and the connection will be closed afterwards.
+			# @returns [Protocol::Connection] The connection if no block is given.
+			def connect(parent: Task.current)
+				connection = connect!
+				
+				connection_task = parent.async do
+					connection.run
+				end
+				
+				connected!(connection)
+				
+				return connection unless block_given?
+				
+				begin
+					yield(connection, connection_task)
 				ensure
 					connection_task&.stop
+					connection&.close
 				end
 			end
 			
-			protected
-			
-			def handle(connection, message)
-				# No default implementation.
+			# Run the client in a loop, reconnecting if necessary.
+			#
+			# Automatically reconnects when the connection fails, with random backoff.
+			# This is useful for long-running clients that need to maintain a persistent connection.
+			#
+			# @parameter parent [Async::Task] The parent task to run under.
+			def run
+				Sync do |task|
+					loop do
+						connection = connect!
+						
+						connected_task = task.async do
+							connected!(connection)
+							
+							yield(connection) if block_given?
+						end
+						
+						connection.run
+					rescue => error
+						Console.error(self, "Connection failed:", exception: error)
+						sleep(rand)
+					ensure
+						# Ensure any tasks that were created during connection are stopped:
+						connected_task&.stop
+						
+						# Close the connection itself:
+						connection&.close
+					end
+				end
 			end
 		end
 	end

data/lib/async/bus/controller.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Async
+	module Bus
+		# Base class for controller objects designed to be proxied over Async::Bus.
+		#
+		# Controllers provide an explicit API for remote operations, avoiding the
+		# confusion that comes from proxying generic objects like Array or Hash.
+		#
+		# @example Array Controller
+		#   class ArrayController < Async::Bus::Controller
+		#     def initialize(array)
+		#       @array = array
+		#     end
+		#
+		#     def append(*values)
+		#       @array.concat(values)
+		#       self  # Return self for chaining
+		#     end
+		#
+		#     def get(index)
+		#       @array[index]  # Returns value
+		#     end
+		#
+		#     def size
+		#       @array.size
+		#     end
+		#   end
+		#
+		# @example Server Setup
+		#   server.accept do |connection|
+		#     array = []
+		#     controller = ArrayController.new(array)
+		#     connection.bind(:items, controller)
+		#   end
+		#
+		# @example Client Usage
+		#   client.connect do |connection|
+		#     items = connection[:items]  # Returns proxy to controller
+		#     items.append(1, 2, 3)       # Remote call
+		#     expect(items.size).to be == 3
+		#   end
+		#
+		# Controllers are automatically proxied when serialized if registered
+		# as a reference type in the Wrapper:
+		#
+		#   Wrapper.new(connection, reference_types: [Async::Bus::Controller])
+		#
+		# This allows controller methods to return other controllers and have
+		# them automatically proxied.
+		class Controller
+		end
+	end
+end
+

data/lib/async/bus/protocol/connection.rb

@@ -1,69 +1,112 @@
 # frozen_string_literal: true
 
-# Copyright, 2021, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# Released under the MIT License.
+# Copyright, 2021-2025, by Samuel Williams.
 
-require 'async'
-require 'async/io/unix_endpoint'
+require "async"
+require "io/endpoint/unix_endpoint"
 
-require_relative 'wrapper'
-require_relative 'transaction'
-require_relative 'proxy'
+require_relative "wrapper"
+require_relative "transaction"
+require_relative "proxy"
+require_relative "response"
 
 module Async
 	module Bus
+		# @namespace
 		module Protocol
+			# Create a local Unix domain socket endpoint.
+			# @parameter path [String] The path to the socket file.
+			# @returns [IO::Endpoint::Unix] The Unix endpoint.
 			def self.local_endpoint(path = "bus.ipc")
-				Async::IO::Endpoint.unix(path)
+				::IO::Endpoint.unix(path)
 			end
 			
+			# Represents a connection between client and server for message passing.
 			class Connection
-				def self.client(peer)
-					self.new(peer, 1)
+				# Create a client-side connection.
+				# @parameter peer [IO] The peer connection.
+				# @parameter options [Hash] Additional options for the connection.
+				# @returns [Connection] A new client connection.
+				def self.client(peer, **options)
+					self.new(peer, 1, **options)
 				end
 				
-				def self.server(peer)
-					self.new(peer, 2)
+				# Create a server-side connection.
+				# @parameter peer [IO] The peer connection.
+				# @parameter options [Hash] Additional options for the connection.
+				# @returns [Connection] A new server connection.
+				def self.server(peer, **options)
+					self.new(peer, 2, **options)
 				end
 				
-				def initialize(peer, id)
+				# Initialize a new connection.
+				# @parameter peer [IO] The peer connection.
+				# @parameter id [Integer] The initial transaction ID.
+				# @parameter wrapper [Class] The wrapper class for serialization.
+				# @parameter timeout [Float] The timeout for transactions.
+				def initialize(peer, id, wrapper: Wrapper, timeout: nil)
 					@peer = peer
+					@id = id
 					
-					@wrapper = Wrapper.new(self)
+					@wrapper = wrapper.new(self)
 					@unpacker = @wrapper.unpacker(peer)
 					@packer = @wrapper.packer(peer)
 					
+					@timeout = timeout
+					
 					@transactions = {}
-					@id = id
 					
 					@objects = {}
 					@proxies = ::ObjectSpace::WeakMap.new
-					@finalized = Thread::Queue.new
+					@finalized = ::Thread::Queue.new
+				end
+				
+				# @attribute [Float] The timeout for transactions.
+				attr_accessor :timeout
+				
+				# Flush the packer buffer.
+				def flush
+					@packer.flush
+				end
+				
+				# Write a message to the connection.
+				# @parameter message [Object] The message to write.
+				def write(message)
+					# $stderr.puts "Writing: #{message.inspect}"
+					@packer.write(message)
+					@packer.flush
+				end
+				
+				# Close the connection and clean up resources.
+				def close
+					@transactions.each do |id, transaction|
+						transaction.close
+					end
+					
+					@peer.close
+				end
+				
+				# Return a string representation of the connection.
+				# @returns [String] A string describing the connection.
+				def inspect
+					"#<#{self.class} #{@objects.size} objects>"
 				end
 				
+				# @attribute [Hash] The bound objects.
 				attr :objects
+				
+				# @attribute [ObjectSpace::WeakMap] The proxy cache.
 				attr :proxies
 				
+				# @attribute [MessagePack::Unpacker] The message unpacker.
 				attr :unpacker
+				
+				# @attribute [MessagePack::Packer] The message packer.
 				attr :packer
 				
+				# Get the next transaction ID.
+				# @returns [Integer] The next transaction ID.
 				def next_id
 					id = @id
 					@id += 2
@@ -71,80 +114,218 @@ module Async
 					return id
 				end
 				
+				# @attribute [Hash] Active transactions.
 				attr :transactions
 				
+				Explicit = Struct.new(:object) do
+					def temporary?
+						false
+					end
+				end
+				
+				Implicit = Struct.new(:object) do
+					def temporary?
+						true
+					end
+				end
+				
+				# Explicitly bind an object to a name, such that it could be accessed remotely.
+				#
+				# This is the same as {bind} but due to the semantics of the `[]=` operator, it does not return a proxy instance.
+				#
+				# Explicitly bound objects are not garbage collected until the connection is closed.
+				#
+				# @parameter name [String] The name to bind the object to.
+				# @parameter object [Object] The object to bind to the given name.
+				def []=(name, object)
+					@objects[name] = Explicit.new(object)
+				end
+				
+				# Generate a proxy for a remotely bound object.
+				#
+				# **This always returns a proxy, even if the object is bound locally.**
+				# The object bus is not shared between client and server, so `[]` always
+				# returns a proxy to the remote instance.
+				#
+				# @parameter name [String] The name of the bound object.
+				# @returns [Proxy] A proxy instance for the bound object.
+				def [](name)
+					return proxy_for(name)
+				end
+				
+				# Explicitly bind an object to a name, such that it could be accessed remotely.
+				#
+				# This method is identical to {[]=} but also returns a {Proxy} instance for the bound object which can be passed by reference.
+				#
+				# Explicitly bound objects are not garbage collected until the connection is closed.
+				#
+				# @example Binding an object to a name and accessing it remotely.
+				# 	array_proxy = connection.bind(:items, [1, 2, 3])
+				# 	connection[:remote].register(array_proxy)
+				#
+				# @parameter name [String] The name to bind the object to.
+				# @parameter object [Object] The object to bind to the given name.
+				# @returns [Proxy] A proxy instance for the bound object.
+				def bind(name, object)
+					# Bind the object into the local object store (explicitly bound, not temporary):
+					@objects[name] = Explicit.new(object)
+					
+					# Always return a proxy for passing by reference, even for locally bound objects:
+					return proxy_for(name)
+				end
+				
+				# Implicitly bind an object with a temporary name, such that it could be accessed remotely.
+				#
+				# Implicitly bound objects are garbage collected when the remote end no longer references them.
+				#
+				# This method is simliar to {bind} but is designed to be used to generate temporary proxies for objects that are not explicitly bound.
+				#
+				# @parameter object [Object] The object to bind to a temporary name.
+				# @returns [Proxy] A proxy instance for the bound object.
 				def proxy(object)
-					name = next_id.to_s(16).freeze
+					name = object.__id__
 					
-					bind(name, object)
+					# Bind the object into the local object store (temporary):
+					@objects[name] ||= Implicit.new(object)
 					
-					return name
+					# Always return a proxy for passing by reference:
+					return proxy_for(name)
 				end
 				
-				def bind(name, object)
-					@objects[name] = object
+				# Implicitly bind an object with a temporary name, such that it could be accessed remotely.
+				#
+				# Implicitly bound objects are garbage collected when the remote end no longer references them.
+				#
+				# This method is similar to {proxy} but is designed to be used to generate temporary names for objects that are not explicitly bound during serialization.
+				#
+				# @parameter object [Object] The object to bind to a temporary name.
+				# @returns [String] The name of the bound object.
+				def proxy_name(object)
+					name = object.__id__
+					
+					# Bind the object into the local object store (temporary):
+					@objects[name] ||= Implicit.new(object)
+					
+					# Return the name:
+					return name
 				end
 				
-				private def finalize(name)
-					proc{@finalized << name}
+				# Get an object or proxy for a bound object, handling reverse lookup.
+				#
+				# If the object is bound locally and the proxy is for this connection, returns the actual object.
+				# If the object is bound remotely, or the proxy is from a different connection, returns a proxy.
+				# This is used when deserializing proxies to handle round-trip scenarios and avoid name collisions.
+				#
+				# @parameter name [String] The name of the bound object.
+				# @parameter local [Boolean] Whether the proxy is for this connection (from serialization). Defaults to true.
+				# @returns [Object | Proxy] The object if bound locally and proxy is for this connection, or a proxy otherwise.
+				def proxy_object(name)
+					# If the proxy is for this connection and the object is bound locally, return the actual object:
+					if entry = @objects[name]
+						# This handles round-trip scenarios correctly.
+						return entry.object
+					end
+					
+					# Otherwise, create a proxy for the remote object:
+					return proxy_for(name)
 				end
 				
-				def [](name)
+				# Get or create a proxy for a named object.
+				#
+				# @parameter name [String] The name of the object.
+				# @returns [Proxy] A proxy instance for the named object.
+				private def proxy_for(name)
 					unless proxy = @proxies[name]
 						proxy = Proxy.new(self, name)
 						@proxies[name] = proxy
 						
-						ObjectSpace.define_finalizer(proxy, finalize(name))
+						::ObjectSpace.define_finalizer(proxy, finalize(name))
 					end
 					
 					return proxy
 				end
 				
-				def invoke(name, arguments, options = {}, &block)
-					
-					id = self.next_id
-					
-					transaction = Transaction.new(self, id)
+				private def finalize(name)
+					proc do
+						@finalized.push(name) rescue nil
+					end
+				end
+				
+				# Create a new transaction.
+				# @parameter id [Integer] The transaction ID.
+				# @returns [Transaction] A new transaction.
+				def transaction!(id = self.next_id)
+					transaction = Transaction.new(self, id, timeout: @timeout)
 					@transactions[id] = transaction
 					
+					return transaction
+				end
+				
+				# Invoke a remote procedure.
+				# @parameter name [Symbol] The name of the remote object.
+				# @parameter arguments [Array] The arguments to pass.
+				# @parameter options [Hash] The keyword arguments to pass.
+				# @yields {|*args| ...} Optional block for yielding operations.
+				# @returns [Object] The result of the invocation.
+				def invoke(name, arguments, options = {}, &block)
+					transaction = self.transaction!
+					
 					transaction.invoke(name, arguments, options, &block)
+				ensure
+					transaction&.close
 				end
 				
-				def run
-					finalizer_task = Async do
+				# Send a release message for a named object.
+				# @parameter name [Symbol] The name of the object to release.
+				def send_release(name)
+					self.write(Release.new(name))
+				end
+				
+				# Run the connection message loop.
+				# @parameter parent [Async::Task] The parent task to run under.
+				def run(parent: Task.current)
+					finalizer_task = parent.async do
 						while name = @finalized.pop
-							@packer.write([:release, name])
+							self.send_release(name)
 						end
 					end
 					
 					@unpacker.each do |message|
-						id = message.shift
-						
-						if id == :release
-							name = message.shift
-							@objects.delete(name) if name.is_a?(String)
-						elsif transaction = @transactions[id]
-							transaction.received.enqueue(message)
-						elsif message.first == :invoke
-							message.shift
-							
-							transaction = Transaction.new(self, id)
-							@transactions[id] = transaction
-							
-							name = message.shift
-							object = @objects[name]
-							
-							Async do
-								transaction.accept(object, *message)
-							ensure
-								transaction.close
+						case message
+						when Invoke
+							# If the object is not found, send an error response and skip the transaction:
+							if object = @objects[message.name]&.object
+								transaction = self.transaction!(message.id)
+								
+								parent.async(annotation: "Invoke #{message.name}") do
+									# $stderr.puts "-> Accepting: #{message.name} #{message.arguments.inspect} #{message.options.inspect}"
+									transaction.accept(object, message.arguments, message.options, message.block_given)
+								ensure
+									# $stderr.puts "<- Accepted: #{message.name}"
+									# This will also delete the transaction from @transactions:
+									transaction.close
+								end
+							else
+								self.write(Error.new(message.id, NameError.new("Object not found: #{message.name}")))
+							end
+						when Response
+							if transaction = @transactions[message.id]
+								transaction.push(message)
+							else
+								# Stale message - transaction already closed (e.g. timeout) or never existed (ignore silently).
+							end
+						when Release
+							name = message.name
+							if @objects[name]&.temporary?
+								# Only delete temporary objects, not explicitly bound ones:
+								@objects.delete(name)
 							end
 						else
-							raise "Out of order message: #{message}"
+							Console.error(self, "Unexpected message:", message)
 						end
 					end
 				ensure
-					finalizer_task.stop
+					finalizer_task&.stop
 					
 					@transactions.each do |id, transaction|
 						transaction.close
@@ -153,15 +334,7 @@ module Async
 					@transactions.clear
 					@proxies = ::ObjectSpace::WeakMap.new
 				end
-				
-				def close
-					@transactions.each do |id, transaction|
-						transaction.close
-					end
-					
-					@peer.close
-				end
 			end
 		end
 	end
-end
+end