async-bus 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bcce5759c8ff0eab16a54c2cf8dd48c054dac88bec2705124cc70589563b9fbb
-  data.tar.gz: 63b96c8cc50edf9f357df6ea992cb4f6ec63aa89f5349c9e0d8ff85c97dafc91
+  metadata.gz: df5f9eee987b7c64e94b521cfdcee2e83bba9657f5155084fb105b02adc9d84d
+  data.tar.gz: 76a6ac9c261fd91a3a8f9cc3f20dffe5ee7036a6b1b4a07a64d66170004e39f7
 SHA512:
-  metadata.gz: a87a86e44c67ca9e4ca76234e0f844c2bb92d14eaffd52f16104f1b14038d266e3725abc584fe779088256c2cdf34e0bfeb4e29aecddeaa71f2d2835f2ed692a
-  data.tar.gz: c28eb52cc46f0ae4d3dcbd1c3e823174e273dde9e9dd1678d672b2f0d3ba5704fe495c511c07355be0a1215d0ade1e0824ca36e8f27d20a11f42f00711b65290
+  metadata.gz: 985a0ac762db79cf5feb87fa3c50aad32bdf627b26f86e015b60d553d146c843023ea7287617834151a8074e23ca87dcc8877f3b323db89994dc04dec7b54ef0
+  data.tar.gz: 1f1e8ebda1dd9036a9452a95c410c1232316041600dd51e8b4f820ea99e67f8e3b7dc245f9cf3870ea62d7253cfd85ee1fb7e42ccbaf25248fce4b38086850e0

data/lib/async/bus/client.rb

@@ -8,7 +8,11 @@ require "async/queue"
 
 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
@@ -59,14 +63,17 @@ module Async
 			# 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(parent: Task.current)
-				parent.async(annotation: "Bus Client", transient: true) do |task|
+			# @yields {|connection| ...} If a block is given, it will be called with the connection.
+			# @returns [Async::Task] The task that runs the client.
+			def run(&block)
+				Async(transient: true) do |task|
 					loop do
 						connection = connect!
 						
 						connected_task = task.async do
 							connected!(connection)
+							
+							yield(connection) if block_given?
 						end
 						
 						connection.run

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

@@ -13,20 +13,38 @@ 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")
 				::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 @@ module Async
 				# @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,16 +87,26 @@ module Async
 					@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
@@ -82,6 +114,7 @@ module Async
 					return id
 				end
 				
+				# @attribute [Hash] Active transactions.
 				attr :transactions
 				
 				Explicit = Struct.new(:object) do
@@ -96,59 +129,112 @@ module Async
 					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 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)
 					
-					# Return the proxy instance for the bound object:
-					return self[name]
+					# Always return a proxy for passing by reference, even for locally bound objects:
+					return proxy_for(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
+					name = object.__id__
 					
 					# Bind the object into the local object store (temporary):
-					@objects[name] = Implicit.new(object)
+					@objects[name] ||= Implicit.new(object)
 					
-					# This constructs the Proxy instance:
-					return self[name]
+					# Always return a proxy for passing by reference:
+					return proxy_for(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
+					name = object.__id__
 					
 					# Bind the object into the local object store (temporary):
-					@objects[name] = Implicit.new(object)
+					@objects[name] ||= Implicit.new(object)
 					
 					# Return the name:
 					return name
 				end
 				
-				def object(name)
-					@objects[name]&.object
-				end
-				
-				private def finalize(name)
-					proc do
-						@finalized.push(name) rescue nil
+				# 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, object)
-					@objects[name] = Explicit.new(object)
-				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
@@ -159,6 +245,15 @@ module Async
 					return proxy
 				end
 				
+				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
@@ -166,6 +261,12 @@ module Async
 					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 +275,14 @@ module Async
 					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

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

@@ -11,6 +11,12 @@ module Async
 		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 @@ module Async
 					@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 @@ module Async
 					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

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

@@ -19,36 +19,59 @@ module Async
 					@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
 				
+				# 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])
-				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

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

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

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

@@ -6,20 +6,32 @@
 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

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

@@ -8,7 +8,12 @@ require "async/queue"
 module Async
 	module Bus
 		module Protocol
+			# Represents a transaction for a remote procedure call.
 			class Transaction
+				# 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
@@ -19,14 +24,23 @@ module Async
 					@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.flush
@@ -35,6 +49,9 @@ module Async
 					@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)
@@ -45,12 +62,14 @@ module Async
 				
 				# 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 = nil
@@ -61,6 +80,11 @@ module Async
 				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.debug(self){[name, arguments, options, block]}
 					
@@ -79,11 +103,20 @@ module Async
 							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
 				end
 				
-				# Accept a remote procedure invokation.
+				# 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|
@@ -106,7 +139,9 @@ module Async
 					
 					self.write(Return.new(@id, result))
 				rescue UncaughtThrowError => error
-					self.write(Throw.new(@id, 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.new(@id, error))
 				end

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

@@ -15,66 +15,114 @@ require_relative "../controller"
 module Async
 	module Bus
 		module Protocol
+			# Represents a MessagePack factory wrapper for async-bus serialization.
 			class Wrapper < MessagePack::Factory
-				def initialize(bus, reference_types: [Controller])
+				# Initialize a new wrapper.
+				# @parameter connection [Connection] The connection for proxy resolution.
+				# @parameter reference_types [Array(Class)] Types to serialize as proxies.
+				def initialize(connection, reference_types: [Controller])
 					super()
 					
-					@bus = bus
+					@connection = connection
 					@reference_types = reference_types
 					
+					# Store the peer connection for forwarding proxies:
+					# When a proxy is forwarded (local=false), it should point back to the sender
+					# (the peer connection), not the receiver (this connection).
+					@peer_connection = nil
+					
 					# The order here matters.
 					
 					self.register_type(0x00, Invoke, recursive: true,
-						packer: ->(invoke, packer){invoke.pack(packer)},
-						unpacker: ->(unpacker){Invoke.unpack(unpacker)},
-					)
+							packer: ->(invoke, packer){invoke.pack(packer)},
+							unpacker: ->(unpacker){Invoke.unpack(unpacker)},
+						)
 					
 					[Return, Yield, Error, Next, Throw, Close].each_with_index do |klass, index|
 						self.register_type(0x01 + index, klass, recursive: true,
-							packer: ->(value, packer){value.pack(packer)},
-							unpacker: ->(unpacker){klass.unpack(unpacker)},
-						)
+								packer: ->(value, packer){value.pack(packer)},
+								unpacker: ->(unpacker){klass.unpack(unpacker)},
+							)
 					end
 					
 					# Reverse serialize proxies back into proxies:
-					# When a Proxy is received, create a proxy pointing back
-					self.register_type(0x10, Proxy,
-						packer: ->(proxy){proxy.__name__},
-						unpacker: @bus.method(:[]),
-					)
+					# When a Proxy is received, use proxy_object to handle reverse lookup
+					self.register_type(0x10, Proxy, recursive: true,
+							packer: self.method(:pack_proxy),
+							unpacker: self.method(:unpack_proxy),
+						)
 					
 					self.register_type(0x11, Release, recursive: true,
-						packer: ->(release, packer){release.pack(packer)},
-						unpacker: ->(unpacker){Release.unpack(unpacker)},
-					)
+							packer: ->(release, packer){release.pack(packer)},
+							unpacker: ->(unpacker){Release.unpack(unpacker)},
+						)
 					
 					self.register_type(0x20, Symbol)
-					self.register_type(0x21, Exception,
-						packer: self.method(:pack_exception),
-						unpacker: self.method(:unpack_exception),
-						recursive: true,
-					)
+					self.register_type(0x21, Exception, recursive: true,
+							packer: self.method(:pack_exception),
+							unpacker: self.method(:unpack_exception),
+						)
 					
 					self.register_type(0x22, Class,
-						packer: ->(klass){klass.name},
-						unpacker: ->(name){Object.const_get(name)},
-					)
+							packer: ->(klass){klass.name},
+							unpacker: ->(name){Object.const_get(name)},
+						)
+					
+					reference_packer = self.method(:pack_reference)
+					reference_unpacker = self.method(:unpack_reference)
 					
 					# Serialize objects into proxies:
 					reference_types&.each_with_index do |klass, index|
-						self.register_type(0x30 + index, klass,
-							packer: @bus.method(:proxy_name),
-							unpacker: @bus.method(:[]),
-						)
+						self.register_type(0x30 + index, klass, recursive: true,
+								packer: reference_packer,
+								unpacker: reference_unpacker,
+							)
 					end
 				end
 				
+				# Pack a proxy into a MessagePack packer.
+				#
+				# Validates that the proxy is for this connection and serializes the proxy name.
+				# Multi-hop proxy forwarding is not supported, so proxies can only be serialized
+				# from the same connection they were created for (round-trip scenarios).
+				#
+				# @parameter proxy [Proxy] The proxy to serialize.
+				# @parameter packer [MessagePack::Packer] The packer to write to.
+				# @raises [ArgumentError] If the proxy is from a different connection (multi-hop forwarding not supported).
+				def pack_proxy(proxy, packer)
+					# Check if the proxy is for this connection:
+					if proxy.__connection__ != @connection
+						proxy = @connection.proxy(proxy)
+					end
+					
+					packer.write(proxy.__name__)
+				end
+				
+				# Unpack a proxy from a MessagePack unpacker.
+				#
+				# When deserializing a proxy:
+				# - If the object is bound locally, return the actual object (round-trip scenario)
+				# - If the object is not found locally, create a proxy pointing to this connection
+				#   (the proxy was forwarded from another connection and should point back to the sender)
+				#
+				# @parameter unpacker [MessagePack::Unpacker] The unpacker to read from.
+				# @returns [Object | Proxy] The actual object if bound locally, or a proxy pointing to this connection.
+				def unpack_proxy(unpacker)
+					@connection.proxy_object(unpacker.read)
+				end
+				
+				# Pack an exception into a MessagePack packer.
+				# @parameter exception [Exception] The exception to pack.
+				# @parameter packer [MessagePack::Packer] The packer to write to.
 				def pack_exception(exception, packer)
 					packer.write(exception.class.name)
 					packer.write(exception.message)
 					packer.write(exception.backtrace)
 				end
 				
+				# Unpack an exception from a MessagePack unpacker.
+				# @parameter unpacker [MessagePack::Unpacker] The unpacker to read from.
+				# @returns [Exception] A reconstructed exception.
 				def unpack_exception(unpacker)
 					klass = unpacker.read
 					message = unpacker.read
@@ -87,6 +135,28 @@ module Async
 					
 					return exception
 				end
+				
+				# Pack a reference type object (e.g., Controller) into a MessagePack packer.
+				#
+				# Serializes the object as a proxy by generating a temporary name and writing it to the packer.
+				# The object is implicitly bound to the connection with a temporary name.
+				#
+				# @parameter object [Object] The reference type object to serialize.
+				# @parameter packer [MessagePack::Packer] The packer to write to.
+				def pack_reference(object, packer)
+					packer.write(@connection.proxy_name(object))
+				end
+				
+				# Unpack a reference type object from a MessagePack unpacker.
+				#
+				# Reads a proxy name and returns the corresponding object or proxy.
+				# If the object is bound locally, returns the actual object; otherwise returns a proxy.
+				#
+				# @parameter unpacker [MessagePack::Unpacker] The unpacker to read from.
+				# @returns [Object | Proxy] The actual object if bound locally, or a proxy otherwise.
+				def unpack_reference(unpacker)
+					@connection.proxy_object(unpacker.read)
+				end
 			end
 		end
 	end

data/lib/async/bus/server.rb

@@ -6,19 +6,37 @@
 require_relative "protocol/connection"
 require "set"
 
+# @namespace
 module Async
+	# @namespace
 	module Bus
+		# Represents a server that accepts async-bus connections.
 		class Server
+			# Initialize a new server.
+			# @parameter endpoint [IO::Endpoint] The endpoint to listen on.
+			# @parameter options [Hash] Additional options for connections.
 			def initialize(endpoint = nil, **options)
 				@endpoint = endpoint || Protocol.local_endpoint
 				@options = options
 			end
 			
-			def accept
+			# 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
+			
+			# Accept incoming connections.
+			# @yields {|connection| ...} Block called with each new connection.
+			def accept(&block)
 				@endpoint.accept do |peer|
 					connection = Protocol::Connection.server(peer, **@options)
 					
-					yield connection
+					connected!(connection, &block)
+					
+					yield connection if block_given?
 					
 					connection.run
 				ensure

data/lib/async/bus/version.rb

@@ -3,8 +3,10 @@
 # Released under the MIT License.
 # Copyright, 2021-2025, by Samuel Williams.
 
+# @namespace
 module Async
+	# @namespace
 	module Bus
-		VERSION = "0.2.0"
+		VERSION = "0.3.1"
 	end
 end

data/readme.md

@@ -1,23 +1,39 @@
 # Async::Bus
 
-Provides a client and server implementation for asynchronous message buses in Ruby.
+When building distributed systems or multi-process applications, you need a way for processes to communicate and invoke methods on objects in other processes. `async-bus` provides a lightweight message-passing system for inter-process communication (IPC) using Unix domain sockets, enabling transparent remote procedure calls (RPC) where remote objects feel like local objects.
 
-[![Development Status](https://github.com/socketry/async-bus/workflows/Test/badge.svg)](https://github.com/socketry/async-bus/actions?workflow=Test)
+Use `async-bus` when you need:
 
-## Features
+  - **Inter-process communication**: Connect multiple Ruby processes running on the same machine.
+  - **Transparent RPC**: Call methods on remote objects as if they were local.
+  - **Type-safe serialization**: Automatically serialize and deserialize Ruby objects using MessagePack.
+  - **Asynchronous operations**: Non-blocking message passing built on the Async framework.
 
-  - Serialization of (rich) Ruby objects using [MessagePack](https://msgpack.org/).
-      - Asynchronous Remote Procedure Calls (RPC) with timeouts.
-  - Automatic client and server reconnection handling.
+[![Development Status](https://github.com/socketry/async-bus/workflows/Test/badge.svg)](https://github.com/socketry/async-bus/actions?workflow=Test)
 
 ## Usage
 
 Please see the [project documentation](https://socketry.github.io/async-bus/) for more details.
 
+  - [Getting Started](https://socketry.github.io/async-bus/guides/getting-started/index) - This guide explains how to get started with `async-bus` to build asynchronous message-passing systems with transparent remote procedure calls in Ruby.
+
+  - [Controllers](https://socketry.github.io/async-bus/guides/controllers/index) - This guide explains how to use controllers in `async-bus` to build explicit remote interfaces with pass-by-reference semantics, enabling bidirectional communication and shared state across connections.
+
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/async-bus/releases/index) for all releases.
 
+### v0.3.1
+
+  - `Client#run` now returns an `Async::Task` (as it did in earlier releases).
+
+### v0.3.0
+
+  - Add support for multi-hop proxying.
+  - Fix proxying of throw/catch value.
+  - `Client#run` now takes a block.
+  - `Server#run` delegates to `Server#connected!`.
+
 ### v0.2.0
 
   - Fix handling of temporary objects.

data/releases.md

@@ -1,5 +1,16 @@
 # Releases
 
+## v0.3.1
+
+  - `Client#run` now returns an `Async::Task` (as it did in earlier releases).
+
+## v0.3.0
+
+  - Add support for multi-hop proxying.
+  - Fix proxying of throw/catch value.
+  - `Client#run` now takes a block.
+  - `Server#run` delegates to `Server#connected!`.
+
 ## v0.2.0
 
   - Fix handling of temporary objects.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-bus
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Samuel Williams