async-bus 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0862030bd7ad9cf8ffe84a3e35e4ec52e3c3f3cc81b8192c5d59cc0bc435e3c
-  data.tar.gz: d2f9a0398f4aa94a35fc3d2dc8aa1d4097777e9f85eeab2ca19405e30d902aa5
+  metadata.gz: bcce5759c8ff0eab16a54c2cf8dd48c054dac88bec2705124cc70589563b9fbb
+  data.tar.gz: 63b96c8cc50edf9f357df6ea992cb4f6ec63aa89f5349c9e0d8ff85c97dafc91
 SHA512:
-  metadata.gz: f4f6d79a2da0ecd4cba25ad79a2be878728701c01113c6f65aa6f9980a863a721f8863841bcfb1c0206f21e25bd0d1b4747a97102b3fbc2b5658dd045c1bf58d
-  data.tar.gz: ecc5632d806ceebbf5b61aebc85ae1b47118303cf9f03320ecc243b403ca7edb00cf60ee966a55cc7c247bd4969897ef10588a97940c55518603fd34afb7c6fc
+  metadata.gz: a87a86e44c67ca9e4ca76234e0f844c2bb92d14eaffd52f16104f1b14038d266e3725abc584fe779088256c2cdf34e0bfeb4e29aecddeaa71f2d2835f2ed692a
+  data.tar.gz: c28eb52cc46f0ae4d3dcbd1c3e823174e273dde9e9dd1678d672b2f0d3ba5704fe495c511c07355be0a1215d0ade1e0824ca36e8f27d20a11f42f00711b65290

data/lib/async/bus/client.rb

@@ -1,54 +1,86 @@
 # 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
 		class Client
-			def initialize(endpoint = nil)
+			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(parent: Task.current)
+				parent.async(annotation: "Bus Client", transient: true) do |task|
+					loop do
+						connection = connect!
+						
+						connected_task = task.async do
+							connected!(connection)
+						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,61 +1,72 @@
 # 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
 		module Protocol
 			def self.local_endpoint(path = "bus.ipc")
-				Async::IO::Endpoint.unix(path)
+				::IO::Endpoint.unix(path)
 			end
 			
 			class Connection
-				def self.client(peer)
-					self.new(peer, 1)
+				def self.client(peer, **options)
+					self.new(peer, 1, **options)
 				end
 				
-				def self.server(peer)
-					self.new(peer, 2)
+				def self.server(peer, **options)
+					self.new(peer, 2, **options)
 				end
 				
-				def initialize(peer, id)
+				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
+				
+				def flush
+					@packer.flush
+				end
+				
+				def write(message)
+					# $stderr.puts "Writing: #{message.inspect}"
+					@packer.write(message)
+					@packer.flush
+				end
+				
+				def close
+					@transactions.each do |id, transaction|
+						transaction.close
+					end
+					
+					@peer.close
+				end
+				
+				def inspect
+					"#<#{self.class} #{@objects.size} objects>"
 				end
 				
 				attr :objects
@@ -73,20 +84,68 @@ module Async
 				
 				attr :transactions
 				
+				Explicit = Struct.new(:object) do
+					def temporary?
+						false
+					end
+				end
+				
+				Implicit = Struct.new(:object) do
+					def temporary?
+						true
+					end
+				end
+				
+				# Bind a local object to a name, such that it could be accessed remotely.
+				#
+				# @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]
+				end
+				
+				# Generate a proxy name for an object and bind it.
+				#
+				# @returns [Proxy] A proxy instance for the bound object.
 				def proxy(object)
-					name = next_id.to_s(16).freeze
+					name = "<#{object.class}@#{next_id.to_s(16)}>".freeze
 					
-					bind(name, object)
+					# Bind the object into the local object store (temporary):
+					@objects[name] = Implicit.new(object)
 					
+					# This constructs the Proxy instance:
+					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.
+				#
+				# @returns [String] The name of the bound object.
+				def proxy_name(object)
+					name = "<#{object.class}@#{next_id.to_s(16)}>".freeze
+					
+					# Bind the object into the local object store (temporary):
+					@objects[name] = Implicit.new(object)
+					
+					# Return the name:
 					return name
 				end
 				
-				def bind(name, object)
-					@objects[name] = object
+				def object(name)
+					@objects[name]&.object
 				end
 				
 				private def finalize(name)
-					proc{@finalized << name}
+					proc do
+						@finalized.push(name) rescue nil
+					end
+				end
+				
+				def []=(name, object)
+					@objects[name] = Explicit.new(object)
 				end
 				
 				def [](name)
@@ -94,57 +153,74 @@ module Async
 						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)
+				def transaction!(id = self.next_id)
+					transaction = Transaction.new(self, id, timeout: @timeout)
 					@transactions[id] = transaction
 					
+					return transaction
+				end
+				
+				def invoke(name, arguments, options = {}, &block)
+					transaction = self.transaction!
+					
 					transaction.invoke(name, arguments, options, &block)
+				ensure
+					transaction&.close
+				end
+				
+				def send_release(name)
+					self.write(Release.new(name))
 				end
 				
-				def run
-					finalizer_task = Async do
+				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 +229,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

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

@@ -0,0 +1,58 @@
+# 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
+				def initialize(id, name, arguments, options, block_given)
+					@id = id
+					@name = name
+					@arguments = arguments
+					@options = options
+					@block_given = block_given
+				end
+				
+				attr :id
+				attr :name
+				attr :arguments
+				attr :options
+				attr :block_given
+				
+				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
+				
+				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,32 +1,28 @@
-# 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
 				
+				def __name__
+					@name
+				end
+				
 				def !
 					@connection.invoke(@name, [:!])
 				end
@@ -39,26 +35,6 @@ module Async
 					@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
-				
 				def method_missing(*arguments, **options, &block)
 					@connection.invoke(@name, arguments, options, &block)
 				end
@@ -68,7 +44,11 @@ module Async
 				end
 				
 				def respond_to_missing?(name, include_all = false)
-					@connection.invoke(@name, [:respond_to?, name, include_all]) || super
+					@connection.invoke(@name, [:respond_to?, name, include_all])
+				end
+				
+				def inspect
+					"#<proxy #{@name}: #{@connection.invoke(@name, [:inspect])}>"
 				end
 			end
 		end

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

@@ -0,0 +1,29 @@
+# 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
+				def initialize(name)
+					@name = name
+				end
+				
+				attr :name
+				
+				def pack(packer)
+					packer.write(@name)
+				end
+				
+				def self.unpack(unpacker)
+					name = unpacker.read
+					
+					return self.new(name)
+				end
+			end
+		end
+	end
+end