async-bus 0.1.1 → 0.3.0

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "msgpack"
+require_relative "proxy"
+
+module Async
+	module Bus
+		module Protocol
+			# Represents a method invocation.
+			class Invoke
+				# Initialize a new invocation message.
+				# @parameter id [Integer] The transaction ID.
+				# @parameter name [Symbol] The method name to invoke.
+				# @parameter arguments [Array] The positional arguments.
+				# @parameter options [Hash] The keyword arguments.
+				# @parameter block_given [Boolean] Whether a block was provided.
+				def initialize(id, name, arguments, options, block_given)
+					@id = id
+					@name = name
+					@arguments = arguments
+					@options = options
+					@block_given = block_given
+				end
+				
+				# @attribute [Integer] The transaction ID.
+				attr :id
+				
+				# @attribute [Symbol] The method name.
+				attr :name
+				
+				# @attribute [Array] The positional arguments.
+				attr :arguments
+				
+				# @attribute [Hash] The keyword arguments.
+				attr :options
+				
+				# @attribute [Boolean] Whether a block was provided.
+				attr :block_given
+				
+				# Pack the invocation into a MessagePack packer.
+				# @parameter packer [MessagePack::Packer] The packer to write to.
+				def pack(packer)
+					packer.write(@id)
+					packer.write(@name)
+					
+					packer.write(@arguments.size)
+					@arguments.each do |argument|
+						packer.write(argument)
+					end
+					
+					packer.write(@options.size)
+					@options.each do |key, value|
+						packer.write(key)
+						packer.write(value)
+					end
+					
+					packer.write(@block_given)
+				end
+				
+				# Unpack an invocation from a MessagePack unpacker.
+				# @parameter unpacker [MessagePack::Unpacker] The unpacker to read from.
+				# @returns [Invoke] A new invocation instance.
+				def self.unpack(unpacker)
+					id = unpacker.read
+					name = unpacker.read
+					arguments = Array.new(unpacker.read){unpacker.read}
+					options = Array.new(unpacker.read){[unpacker.read, unpacker.read]}.to_h
+					block_given = unpacker.read
+					
+					return self.new(id, name, arguments, options, block_given)
+				end
+			end
+		end
+	end
+end

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

@@ -1,74 +1,77 @@
-# Copyright, 2018, 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.
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2021-2025, by Samuel Williams.
 
 module Async
 	module Bus
 		module Protocol
+			# A proxy object that forwards method calls to a remote object.
+			#
+			# We must be extremely careful not to invoke any methods on the proxy object that would recursively call the proxy object.
 			class Proxy < BasicObject
+				# Create a new proxy object.
+				#
+				# @parameter connection [Connection] The connection to the remote object.
+				# @parameter name [Symbol] The name (address) of the remote object.
 				def initialize(connection, name)
 					@connection = connection
 					@name = name
 				end
 				
+				# Get the connection to the remote object.
+				# @returns [Connection] The connection to the remote object.
+				def __connection__
+					@connection
+				end
+				
+				# Get the name of the remote object.
+				# @returns [Symbol] The name of the remote object.
+				def __name__
+					@name
+				end
+				
+				# Logical negation operator.
+				# @returns [Object] The result of the negation.
 				def !
 					@connection.invoke(@name, [:!])
 				end
 				
+				# Equality operator.
+				# @parameter object [Object] The object to compare with.
+				# @returns [Boolean] True if equal.
 				def == object
 					@connection.invoke(@name, [:==, object])
 				end
 				
+				# Inequality operator.
+				# @parameter object [Object] The object to compare with.
+				# @returns [Boolean] True if not equal.
 				def != object
 					@connection.invoke(@name, [:!=, object])
 				end
 				
-				def eql?(other)
-					self.equal?(other)
-				end
-				
-				def methods(all = true)
-					@connection.invoke(@name, [:methods, all]) | super
-				end
-				
-				def protected_methods(all = true)
-					@connection.invoke(@name, [:protected_methods, all]) | super
-				end
-				
-				def public_methods(all = true)
-					@connection.invoke(@name, [:public_methods, all]) | super
-				end
-				
-				def inspect
-					"[Proxy (#{@name}) #{method_missing(:inspect)}]"
-				end
-				
+				# Forward method calls to the remote object.
+				# @parameter arguments [Array] The method arguments.
+				# @parameter options [Hash] The keyword arguments.
+				# @yields {|*args| ...} Optional block to pass to the method.
+				# @returns [Object] The result of the method call.
 				def method_missing(*arguments, **options, &block)
 					@connection.invoke(@name, arguments, options, &block)
 				end
 				
+				# Check if the remote object responds to a method.
+				# @parameter name [Symbol] The method name to check.
+				# @parameter include_all [Boolean] Whether to include private methods.
+				# @returns [Boolean] True if the method exists.
 				def respond_to?(name, include_all = false)
 					@connection.invoke(@name, [:respond_to?, name, include_all])
 				end
 				
-				def respond_to_missing?(name, include_all = false)
-					@connection.invoke(@name, [:respond_to?, name, include_all]) || super
+				# Return a string representation of the proxy.
+				# @returns [String] A string describing the proxy.
+				def inspect
+					"#<proxy #{@name}>"
 				end
 			end
 		end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Async
+	module Bus
+		module Protocol
+			# Represents a named object that has been released (no longer available).
+			class Release
+				# Initialize a new release message.
+				# @parameter name [Symbol] The name of the released object.
+				def initialize(name)
+					@name = name
+				end
+				
+				# @attribute [Symbol] The name of the released object.
+				attr :name
+				
+				# Pack the release into a MessagePack packer.
+				# @parameter packer [MessagePack::Packer] The packer to write to.
+				def pack(packer)
+					packer.write(@name)
+				end
+				
+				# Unpack a release from a MessagePack unpacker.
+				# @parameter unpacker [MessagePack::Unpacker] The unpacker to read from.
+				# @returns [Release] A new release instance.
+				def self.unpack(unpacker)
+					name = unpacker.read
+					
+					return self.new(name)
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Async
+	module Bus
+		module Protocol
+			# Represents a response message from a remote procedure call.
+			class Response
+				# Initialize a new response message.
+				# @parameter id [Integer] The transaction ID.
+				# @parameter result [Object] The result value.
+				def initialize(id, result)
+					@id = id
+					@result = result
+				end
+				
+				# @attribute [Integer] The transaction ID.
+				attr :id
+				
+				# @attribute [Object] The result value.
+				attr :result
+				
+				# Pack the response into a MessagePack packer.
+				# @parameter packer [MessagePack::Packer] The packer to write to.
+				def pack(packer)
+					packer.write(@id)
+					packer.write(@result)
+				end
+				
+				# Unpack a response from a MessagePack unpacker.
+				# @parameter unpacker [MessagePack::Unpacker] The unpacker to read from.
+				# @returns [Response] A new response instance.
+				def self.unpack(unpacker)
+					id = unpacker.read
+					result = unpacker.read
+					
+					return self.new(id, result)
+				end
+			end
+			
+			Return = Class.new(Response)
+			Yield = Class.new(Response)
+			Error = Class.new(Response)
+			Next = Class.new(Response)
+			Throw = Class.new(Response)
+			Close = Class.new(Response)
+		end
+	end
+end

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

@@ -1,121 +1,151 @@
 # 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/queue'
+require "async/queue"
 
 module Async
 	module Bus
 		module Protocol
+			# Represents a transaction for a remote procedure call.
 			class Transaction
-				def initialize(connection, id)
+				# Initialize a new transaction.
+				# @parameter connection [Connection] The connection for this transaction.
+				# @parameter id [Integer] The transaction ID.
+				# @parameter timeout [Float] The timeout for the transaction.
+				def initialize(connection, id, timeout: nil)
 					@connection = connection
 					@id = id
 					
-					@received = Async::Queue.new
+					@timeout = timeout
+					
+					@received = Thread::Queue.new
 					@accept = nil
 				end
 				
+				# @attribute [Connection] The connection for this transaction.
+				attr :connection
+				
+				# @attribute [Integer] The transaction ID.
 				attr :id
+				
+				# @attribute [Float] The timeout for the transaction.
+				attr_accessor :timeout
+				
+				# @attribute [Thread::Queue] The queue of received messages.
 				attr :received
 				
+				# @attribute [Object] The accept handler.
+				attr :accept
+				
+				# Read a message from the transaction queue.
+				# @returns [Object] The next message.
 				def read
 					if @received.empty?
-						@connection.packer.flush
+						@connection.flush
 					end
 					
-					@received.dequeue
+					@received.pop(timeout: @timeout)
+				end
+				
+				# Write a message to the connection.
+				# @parameter message [Object] The message to write.
+				# @raises [RuntimeError] If the transaction is closed.
+				def write(message)
+					if @connection
+						@connection.write(message)
+					else
+						raise RuntimeError, "Transaction is closed!"
+					end
 				end
 				
-				def write(*arguments)
-					@connection.packer.write([id, *arguments])
-					@connection.packer.flush
+				# Push a message to the transaction's received queue.
+				# Silently ignores messages if the queue is already closed.
+				# @parameter message [Object] The message to push.
+				def push(message)
+					@received.push(message)
+				rescue ClosedQueueError
+					# Queue is closed (transaction already finished/closed) - ignore silently.
 				end
 				
+				# Close the transaction and clean up resources.
 				def close
-					if @connection
-						connection = @connection
+					if connection = @connection
 						@connection = nil
+						@received.close
 						
 						connection.transactions.delete(@id)
 					end
 				end
 				
 				# Invoke a remote procedure.
+				# @parameter name [Symbol] The name of the remote object.
+				# @parameter arguments [Array] The positional arguments.
+				# @parameter options [Hash] The keyword arguments.
+				# @yields {|*args| ...} Optional block for yielding operations.
+				# @returns [Object] The result of the invocation.
 				def invoke(name, arguments, options, &block)
-					Console.logger.debug(self) {[name, arguments, options, block]}
+					Console.debug(self){[name, arguments, options, block]}
 					
-					self.write(:invoke, name, arguments, options, block_given?)
+					self.write(Invoke.new(@id, name, arguments, options, block_given?))
 					
 					while response = self.read
-						what, result = response
-						
-						case what
-						when :error
-							raise(result)
-						when :return
-							return(result)
-						when :yield
+						case response
+						when Return
+							return response.result
+						when Yield
 							begin
-								result = yield(*result)
-								self.write(:next, result)
+								result = yield(*response.result)
+								self.write(Next.new(@id, result))
 							rescue => error
-								self.write(:error, error)
+								self.write(Error.new(@id, error))
 							end
+						when Error
+							raise(response.result)
+						when Throw
+							# Re-throw the tag and value that was thrown on the server side
+							# Throw.result contains [tag, value] array
+							tag, value = response.result
+							throw(tag, value)
 						end
 					end
-					
-				# ensure
-				# 	self.write(:close)
 				end
 				
-				# Accept a remote procedure invokation.
-				def accept(object, arguments, options, block)
-					if block
+				# Accept a remote procedure invocation.
+				# @parameter object [Object] The object to invoke the method on.
+				# @parameter arguments [Array] The positional arguments.
+				# @parameter options [Hash] The keyword arguments.
+				# @parameter block_given [Boolean] Whether a block was provided.
+				def accept(object, arguments, options, block_given)
+					if block_given
 						result = object.public_send(*arguments, **options) do |*yield_arguments|
-							self.write(:yield, yield_arguments)
-							what, result = self.read
+							self.write(Yield.new(@id, yield_arguments))
+							
+							response = self.read
 							
-							case what
-							when :next
-								result
-							when :close
-								return
-							when :error
-								raise(result)
+							case response
+							when Next
+								response.result
+							when Error
+								raise(response.result)
+							when Close
+								break
 							end
 						end
 					else
 						result = object.public_send(*arguments, **options)
 					end
 					
-					self.write(:return, result)
+					self.write(Return.new(@id, result))
 				rescue UncaughtThrowError => error
-					self.write(:throw, error.tag)
+					# UncaughtThrowError has both tag and value attributes
+					# Store both in the Throw message: result is tag, we'll add value handling
+					self.write(Throw.new(@id, [error.tag, error.value]))
 				rescue => error
-					self.write(:error, error)
-				# ensure
-				# 	self.write(:close)
+					self.write(Error.new(@id, error))
 				end
 			end
 		end
 	end
-end
+end