Fix handling of proxies with symbol names.

- 100% documentation coverage.

Author: samuel-williams-shopify

lib/async/bus/client.rb

@@ -8,7 +8,11 @@
 
 module Async
 	module Bus
+		# Represents a client that can connect to a server.
 		class Client
+			# 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
 				@options = options

lib/async/bus/protocol/connection.rb

@@ -13,20 +13,38 @@
 
 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")
 				::IO::Endpoint.unix(path)
 			end
 
+			# Represents a connection between client and server for message passing.
 			class Connection
+				# 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
 
+				# 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
 
+				# 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
@@ -47,16 +65,20 @@ def initialize(peer, id, wrapper: Wrapper, timeout: nil)
 				# @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
@@ -65,23 +87,34 @@ def close
 					@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
 
 					return id
 				end
 
+				# @attribute [Hash] Active transactions.
 				attr :transactions
 
 				Explicit = Struct.new(:object) do
@@ -96,8 +129,47 @@ def temporary?
 					end
 				end
 
-				# Bind a local object to a name, such that it could be accessed remotely.
+				# 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 will not return objects bound locally, only proxies for remotely bound objects.**
+				#
+				# @parameter name [String] The name of the bound object.
+				# @returns [Object | Proxy] The object or proxy instance for the bound object.
+				def [](name)
+					unless proxy = @proxies[name]
+						proxy = Proxy.new(self, name)
+						@proxies[name] = proxy
+						
+						::ObjectSpace.define_finalizer(proxy, finalize(name))
+					end
+					
+					return proxy
+				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):
@@ -107,8 +179,13 @@ def bind(name, object)
 					return self[name]
 				end
 
-				# Generate a proxy name for an object and bind it.
+				# 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 = "<#{object.class}@#{next_id.to_s(16)}>".freeze
@@ -120,9 +197,13 @@ def proxy(object)
 					return self[name]
 				end
 
-				# Generate a proxy name for an object and bind it, returning just the name.
-				# Used for serialization when you need the name string, not a Proxy instance.
+				# 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.class}@#{next_id.to_s(16)}>".freeze
@@ -134,38 +215,28 @@ def proxy_name(object)
 					return name
 				end
 
-				def object(name)
-					@objects[name]&.object
-				end
-				
 				private def finalize(name)
 					proc do
 						@finalized.push(name) rescue nil
 					end
 				end
 
-				def []=(name, object)
-					@objects[name] = Explicit.new(object)
-				end
-				
-				def [](name)
-					unless proxy = @proxies[name]
-						proxy = Proxy.new(self, name)
-						@proxies[name] = proxy
-						
-						::ObjectSpace.define_finalizer(proxy, finalize(name))
-					end
-					
-					return proxy
-				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!
 
@@ -174,10 +245,14 @@ def invoke(name, arguments, options = {}, &block)
 					transaction&.close
 				end
 
+				# 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

lib/async/bus/protocol/invoke.rb

@@ -11,6 +11,12 @@ 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
@@ -19,12 +25,23 @@ def initialize(id, name, arguments, options, block_given)
 					@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)
@@ -43,6 +60,9 @@ def pack(packer)
 					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

lib/async/bus/protocol/proxy.rb

@@ -19,36 +19,61 @@ def initialize(connection, name)
 					@name = name
 				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
 
+				# 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
 
+				# Check if the remote object responds to a missing 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_missing?(name, include_all = false)
 					@connection.invoke(@name, [:respond_to?, name, include_all])
 				end
 
+				# Return a string representation of the proxy.
+				# @returns [String] A string describing the proxy.
 				def inspect
-					"#<proxy #{@name}: #{@connection.invoke(@name, [:inspect])}>"
+					"#<proxy #{@name}>"
 				end
 			end
 		end

lib/async/bus/protocol/release.rb

@@ -8,16 +8,24 @@ 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