io-endpoint 0.15.1 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52e4f0d4b8e0e46f2ad47c655f0b841fd9cbd4b26165139a5260546f5baa5167
-  data.tar.gz: a86e657651e34a15f300d67e1df05b7ef29b6e5624b61c2bc06df57269f005dd
+  metadata.gz: 85b2a321334cd16a75da466ebff7b9f380410788f173936e9bffd5482599e2ad
+  data.tar.gz: f207fe739fe89220f59037ec54b1020795509598d4f0deb7a9caaf2cb36e8ea5
 SHA512:
-  metadata.gz: b33453871ae938df8dc7c21bf5eb2db870a7433ec61015dc3aa0b1f1f572ff36f3bd46c3f447e53ee58891c4570215bcf14c8c06010433d6dcaf1956b7034659
-  data.tar.gz: 8a1143e06da6a04216f6e7a5a9af31530b3867e89771e739e28e67d68987dbb9be7e587bba86cfd934f7e80f85043f4cbfb10119dd11521bac4747d70708e840
+  metadata.gz: 7154bdc644a2e8f2689567b9804d4019c263f07dd28f44ec98084ed4c3459ea1521724dcf0d4b90d2be9928a9eb4bbcb58895e18e10d461109f91dbdc6cb45ea
+  data.tar.gz: d8f01abe1ee5d1c93184505f03c2ec4226b6b4eed20754d413b8dcdfa5d5e339d3169069a420fac31b26eca2e157548ad7479e51f8457a14c8f3db5d1efe9e78

data/context/getting-started.md

@@ -0,0 +1,113 @@
+# Getting Started
+
+This guide explains how to get started with `io-endpoint`, a library that provides a separation of concerns interface for network I/O endpoints.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add io-endpoint
+~~~
+
+## Core Concepts
+
+`io-endpoint` provides a unified interface for working with network endpoints, allowing you to write code that is agnostic to the underlying transport mechanism (TCP, UDP, UNIX sockets, SSL/TLS). This separation of concerns makes it easier to:
+
+- **Write transport-agnostic code**: Your application logic doesn't need to know whether it's using TCP, UDP, or UNIX sockets.
+- **Test with different transports**: Easily swap between transports during testing.
+- **Handle multiple addresses**: Automatically handle IPv4 and IPv6 addresses.
+- **Compose endpoints**: Combine multiple endpoints for failover or load distribution.
+
+The library centers around the {ruby IO::Endpoint::Generic} class, which represents a network endpoint that can be bound (for servers) or connected to (for clients). Different endpoint types handle different scenarios:
+
+- {ruby IO::Endpoint::HostEndpoint} - Resolves hostnames to addresses (e.g., "localhost:8080")
+- {ruby IO::Endpoint::AddressEndpoint} - Works with specific network addresses
+- {ruby IO::Endpoint::UNIXEndpoint} - Handles UNIX domain sockets
+- {ruby IO::Endpoint::SSLEndpoint} - Wraps endpoints with SSL/TLS encryption
+- {ruby IO::Endpoint::CompositeEndpoint} - Combines multiple endpoints
+
+## Usage
+
+### Creating a TCP Server
+
+When you need to create a server that listens on a specific port, you can use {ruby IO::Endpoint.tcp} to create a TCP endpoint:
+
+```ruby
+require "io/endpoint"
+
+# Create a TCP endpoint listening on localhost port 8080:
+endpoint = IO::Endpoint.tcp("localhost", 8080)
+
+# Bind to the endpoint and accept connections:
+endpoint.bind do |server|
+	# The server socket is automatically closed when the block exits
+	server.listen(10)
+	
+	loop do
+		client, address = server.accept
+		# Handle the client connection
+		client.close
+	end
+end
+```
+
+### Creating a TCP Client
+
+To connect to a remote server, use the `connect` method:
+
+```ruby
+require "io/endpoint"
+
+# Create a TCP endpoint for the remote server:
+endpoint = IO::Endpoint.tcp("example.com", 80)
+
+# Connect to the server:
+endpoint.connect do |socket|
+	# The socket is automatically closed when the block exits
+	socket.write("GET / HTTP/1.1\r\nHost: example.com\r\n\r\n")
+	response = socket.read
+	puts response
+end
+```
+
+### Using UNIX Domain Sockets
+
+For inter-process communication on the same machine, UNIX domain sockets provide better performance than TCP:
+
+```ruby
+require "io/endpoint"
+
+# Create a UNIX socket endpoint:
+endpoint = IO::Endpoint.unix("/tmp/myapp.sock")
+
+# Bind to the socket:
+endpoint.bind do |server|
+	server.listen(10)
+	
+	loop do
+		client, address = server.accept
+		# Handle the client connection
+		client.close
+	end
+end
+```
+
+### Using SSL/TLS
+
+To add encryption to your connections, wrap a TCP endpoint with SSL:
+
+```ruby
+require "io/endpoint"
+
+# Create an SSL endpoint:
+endpoint = IO::Endpoint.ssl("example.com", 443, hostname: "example.com")
+
+# Connect with SSL encryption:
+endpoint.connect do |socket|
+	# The socket is automatically encrypted
+	socket.write("GET / HTTP/1.1\r\nHost: example.com\r\n\r\n")
+	response = socket.read
+	puts response
+end
+```

data/context/index.yaml

@@ -0,0 +1,12 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Provides a separation of concerns interface for IO endpoints.
+metadata:
+  documentation_uri: https://socketry.github.io/io-endpoint
+  source_code_uri: https://github.com/socketry/io-endpoint.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to get started with `io-endpoint`, a library
+    that provides a separation of concerns interface for network I/O endpoints.

data/lib/io/endpoint/address_endpoint.rb

@@ -9,13 +9,19 @@ require_relative "generic"
 require_relative "wrapper"
 
 module IO::Endpoint
+	# Represents an endpoint for a specific network address.
 	class AddressEndpoint < Generic
+		# Initialize a new address endpoint.
+		# @parameter address [Address] The network address for this endpoint.
+		# @parameter options [Hash] Additional options to pass to the parent class.
 		def initialize(address, **options)
 			super(**options)
 			
 			@address = address
 		end
 		
+		# Get a string representation of the endpoint.
+		# @returns [String] A string representation of the endpoint address.
 		def to_s
 			case @address.afamily
 			when Socket::AF_INET
@@ -27,22 +33,25 @@ module IO::Endpoint
 			end
 		end
 		
+		# Get a detailed string representation of the endpoint.
+		# @returns [String] A detailed string representation including the address.
 		def inspect
 			"\#<#{self.class} address=#{@address.inspect}>"
 		end
 		
+		# @attribute [Address] The network address for this endpoint.
 		attr :address
 		
 		# Bind a socket to the given address. If a block is given, the socket will be automatically closed when the block exits.
-		# @yield {|socket| ...}	An optional block which will be passed the socket.
-		#   @parameter socket [Socket] The socket which has been bound.
-		# @return [Array(Socket)] the bound socket
+		# @yields {|socket| ...} If a block is given, yields the bound socket.
+		# 	@parameter socket [Socket] The socket which has been bound.
+		# @returns [Array(Socket)] the bound socket
 		def bind(wrapper = self.wrapper, &block)
 			[wrapper.bind(@address, **@options, &block)]
 		end
 		
 		# Connects a socket to the given address. If a block is given, the socket will be automatically closed when the block exits.
-		# @return [Socket] the connected socket
+		# @returns [Socket] the connected socket
 		def connect(wrapper = self.wrapper, &block)
 			wrapper.connect(@address, **@options, &block)
 		end

data/lib/io/endpoint/bound_endpoint.rb

@@ -8,7 +8,13 @@ require_relative "composite_endpoint"
 require_relative "address_endpoint"
 
 module IO::Endpoint
+	# Represents an endpoint that has been bound to one or more sockets.
 	class BoundEndpoint < Generic
+		# Create a bound endpoint from an existing endpoint.
+		# @parameter endpoint [Generic] The endpoint to bind.
+		# @option backlog [Integer] The maximum length of the queue of pending connections.
+		# @option close_on_exec [Boolean] Whether to close sockets on exec.
+		# @returns [BoundEndpoint] A new bound endpoint instance.
 		def self.bound(endpoint, backlog: Socket::SOMAXCONN, close_on_exec: false)
 			sockets = endpoint.bind
 			
@@ -19,6 +25,10 @@ module IO::Endpoint
 			return self.new(endpoint, sockets, **endpoint.options)
 		end
 		
+		# Initialize a new bound endpoint.
+		# @parameter endpoint [Generic] The original endpoint that was bound.
+		# @parameter sockets [Array(Socket)] The sockets that were bound.
+		# @parameter options [Hash] Additional options to pass to the parent class.
 		def initialize(endpoint, sockets, **options)
 			super(**options)
 			
@@ -26,7 +36,9 @@ module IO::Endpoint
 			@sockets = sockets
 		end
 		
+		# @attribute [Generic] The original endpoint that was bound.
 		attr :endpoint
+		# @attribute [Array(Socket)] The sockets that were bound.
 		attr :sockets
 		
 		# A endpoint for the local end of the bound socket.
@@ -49,19 +61,29 @@ module IO::Endpoint
 			return CompositeEndpoint.new(endpoints)
 		end
 		
+		# Close all bound sockets.
 		def close
 			@sockets.each(&:close)
 			@sockets.clear
 		end
 		
+		# Get a string representation of the bound endpoint.
+		# @returns [String] A string representation of the bound endpoint.
 		def to_s
 			"bound:#{@endpoint}"
 		end
 		
+		# Get a detailed string representation of the bound endpoint.
+		# @returns [String] A detailed string representation including socket count.
 		def inspect
 			"\#<#{self.class} #{@sockets.size} bound sockets for #{@endpoint}>"
 		end
 		
+		# Bind the endpoint using the given wrapper.
+		# @parameter wrapper [Wrapper] The wrapper to use for binding.
+		# @yields {|socket| ...} If a block is given, yields each bound socket.
+		# 	@parameter socket [Socket] A bound socket.
+		# @returns [Array(Socket)] An array of bound sockets.
 		def bind(wrapper = self.wrapper, &block)
 			@sockets.map do |server|
 				if block_given?
@@ -76,6 +98,9 @@ module IO::Endpoint
 	end
 	
 	class Generic
+		# Create a bound endpoint from this endpoint.
+		# @parameter options [Hash] Options to pass to {BoundEndpoint.bound}.
+		# @returns [BoundEndpoint] A new bound endpoint instance.
 		def bound(**options)
 			BoundEndpoint.bound(self, **options)
 		end

data/lib/io/endpoint/composite_endpoint.rb

@@ -8,6 +8,9 @@ require_relative "generic"
 module IO::Endpoint
 	# A composite endpoint is a collection of endpoints that are used in order.
 	class CompositeEndpoint < Generic
+		# Initialize a new composite endpoint.
+		# @parameter endpoints [Array(Generic)] The endpoints to compose.
+		# @parameter options [Hash] Additional options to pass to the parent class and propagate to endpoints.
 		def initialize(endpoints, **options)
 			super(**options)
 			
@@ -19,18 +22,26 @@ module IO::Endpoint
 			@endpoints = endpoints
 		end
 		
+		# Get a string representation of the composite endpoint.
+		# @returns [String] A string representation listing all endpoints.
 		def to_s
 			"composite:#{@endpoints.join(",")}"
 		end
 		
+		# Get a detailed string representation of the composite endpoint.
+		# @returns [String] A detailed string representation including all endpoints.
 		def inspect
 			"\#<#{self.class} endpoints=#{@endpoints}>"
 		end
 		
+		# Create a new composite endpoint with merged options.
+		# @parameter options [Hash] Additional options to merge with existing options.
+		# @returns [CompositeEndpoint] A new composite endpoint instance with merged options.
 		def with(**options)
 			self.class.new(endpoints.map{|endpoint| endpoint.with(**options)}, **@options.merge(options))
 		end
 		
+		# @attribute [Array(Generic)] The endpoints in this composite endpoint.
 		attr :endpoints
 		
 		# The number of endpoints in the composite endpoint.
@@ -38,12 +49,21 @@ module IO::Endpoint
 			@endpoints.size
 		end
 		
+		# Enumerate all endpoints in the composite endpoint.
+		# @yields {|endpoint| ...} For each endpoint in the composite, yields it.
+		# 	@parameter endpoint [Generic] An endpoint in the composite.
 		def each(&block)
 			@endpoints.each do |endpoint|
 				endpoint.each(&block)
 			end
 		end
 		
+		# Connect to the first endpoint that succeeds.
+		# @parameter wrapper [Wrapper] The wrapper to use for connecting.
+		# @yields {|socket| ...} If a block is given, yields the connected socket from the first successful endpoint.
+		# 	@parameter socket [Socket] The connected socket.
+		# @returns [Socket] The connected socket.
+		# @raises [Exception] If all endpoints fail to connect, raises the last error encountered.
 		def connect(wrapper = self.wrapper, &block)
 			last_error = nil
 			
@@ -57,6 +77,11 @@ module IO::Endpoint
 			raise last_error
 		end
 		
+		# Bind all endpoints in the composite.
+		# @parameter wrapper [Wrapper] The wrapper to use for binding.
+		# @yields {|socket| ...} For each endpoint that is bound, yields the bound socket.
+		# 	@parameter socket [Socket] A bound socket.
+		# @returns [Array(Socket)] An array of bound sockets if no block is given.
 		def bind(wrapper = self.wrapper, &block)
 			if block_given?
 				@endpoints.each do |endpoint|
@@ -68,6 +93,10 @@ module IO::Endpoint
 		end
 	end
 	
+	# Create a composite endpoint from multiple endpoints.
+	# @parameter endpoints [Array(Generic)] The endpoints to compose.
+	# @parameter options [Hash] Additional options to pass to the composite endpoint.
+	# @returns [CompositeEndpoint] A new composite endpoint instance.
 	def self.composite(*endpoints, **options)
 		CompositeEndpoint.new(endpoints, **options)
 	end

data/lib/io/endpoint/connected_endpoint.rb

@@ -10,7 +10,12 @@ require_relative "socket_endpoint"
 require "openssl"
 
 module IO::Endpoint
+	# Represents an endpoint that has been connected to a socket.
 	class ConnectedEndpoint < Generic
+		# Create a connected endpoint from an existing endpoint.
+		# @parameter endpoint [Generic] The endpoint to connect.
+		# @option close_on_exec [Boolean] Whether to close the socket on exec.
+		# @returns [ConnectedEndpoint] A new connected endpoint instance.
 		def self.connected(endpoint, close_on_exec: false)
 			socket = endpoint.connect
 			
@@ -19,6 +24,10 @@ module IO::Endpoint
 			return self.new(endpoint, socket, **endpoint.options)
 		end
 		
+		# Initialize a new connected endpoint.
+		# @parameter endpoint [Generic] The original endpoint that was connected.
+		# @parameter socket [Socket] The socket that was connected.
+		# @parameter options [Hash] Additional options to pass to the parent class.
 		def initialize(endpoint, socket, **options)
 			super(**options)
 			
@@ -26,7 +35,9 @@ module IO::Endpoint
 			@socket = socket
 		end
 		
+		# @attribute [Generic] The original endpoint that was connected.
 		attr :endpoint
+		# @attribute [Socket] The socket that was connected.
 		attr :socket
 		
 		# A endpoint for the local end of the bound socket.
@@ -41,6 +52,11 @@ module IO::Endpoint
 			AddressEndpoint.new(socket.to_io.remote_address, **options)
 		end
 		
+		# Connect using the already connected socket.
+		# @parameter wrapper [Wrapper] The wrapper to use (unused, socket is already connected).
+		# @yields {|socket| ...} If a block is given, yields the connected socket.
+		# 	@parameter socket [Socket] The connected socket.
+		# @returns [Socket] The connected socket or a duplicate if no block is given.
 		def connect(wrapper = self.wrapper, &block)
 			if block_given?
 				yield @socket
@@ -49,6 +65,7 @@ module IO::Endpoint
 			end
 		end
 		
+		# Close the connected socket.
 		def close
 			if @socket
 				@socket.close
@@ -56,16 +73,23 @@ module IO::Endpoint
 			end
 		end
 		
+		# Get a string representation of the connected endpoint.
+		# @returns [String] A string representation of the connected endpoint.
 		def to_s
 			"connected:#{@endpoint}"
 		end
 		
+		# Get a detailed string representation of the connected endpoint.
+		# @returns [String] A detailed string representation including the socket.
 		def inspect
 			"\#<#{self.class} #{@socket} connected for #{@endpoint}>"
 		end
 	end
-		
+	
 	class Generic
+		# Create a connected endpoint from this endpoint.
+		# @parameter options [Hash] Options to pass to {ConnectedEndpoint.connected}.
+		# @returns [ConnectedEndpoint] A new connected endpoint instance.
 		def connected(**options)
 			ConnectedEndpoint.connected(self, **options)
 		end

data/lib/io/endpoint/generic.rb

@@ -12,10 +12,15 @@ module IO::Endpoint
 	
 	# Endpoints represent a way of connecting or binding to an address.
 	class Generic
+		# Initialize a new generic endpoint.
+		# @parameter options [Hash] Configuration options for the endpoint.
 		def initialize(**options)
 			@options = options.freeze
 		end
 		
+		# Create a new endpoint with merged options.
+		# @parameter options [Hash] Additional options to merge with existing options.
+		# @returns [Generic] A new endpoint instance with merged options.
 		def with(**options)
 			dup = self.dup
 			
@@ -26,43 +31,43 @@ module IO::Endpoint
 		
 		attr_accessor :options
 		
-		# @return [String] The hostname of the bound socket.
+		# @returns [String] The hostname of the bound socket.
 		def hostname
 			@options[:hostname]
 		end
 		
 		# If `SO_REUSEPORT` is enabled on a socket, the socket can be successfully bound even if there are existing sockets bound to the same address, as long as all prior bound sockets also had `SO_REUSEPORT` set before they were bound.
-		# @return [Boolean, nil] The value for `SO_REUSEPORT`.
+		# @returns [Boolean, nil] The value for `SO_REUSEPORT`.
 		def reuse_port?
 			@options[:reuse_port]
 		end
 		
 		# If `SO_REUSEADDR` is enabled on a socket prior to binding it, the socket can be successfully bound unless there is a conflict with another socket bound to exactly the same combination of source address and port. Additionally, when set, binding a socket to the address of an existing socket in `TIME_WAIT` is not an error.
-		# @return [Boolean] The value for `SO_REUSEADDR`.
+		# @returns [Boolean] The value for `SO_REUSEADDR`.
 		def reuse_address?
 			@options[:reuse_address]
 		end
 		
 		# Controls SO_LINGER. The amount of time the socket will stay in the `TIME_WAIT` state after being closed.
-		# @return [Integer, nil] The value for SO_LINGER.
+		# @returns [Integer, nil] The value for SO_LINGER.
 		def linger
 			@options[:linger]
 		end
 		
-		# @return [Numeric] The default timeout for socket operations.
+		# @returns [Numeric] The default timeout for socket operations.
 		def timeout
 			@options[:timeout]
 		end
 		
-		# @return [Address] the address to bind to before connecting.
+		# @returns [Address] the address to bind to before connecting.
 		def local_address
 			@options[:local_address]
 		end
 		
 		# Bind a socket to the given address. If a block is given, the socket will be automatically closed when the block exits.
 		# @parameter wrapper [Wrapper] The wrapper to use for binding.
-		# @yields {|socket| ...}	An optional block which will be passed the socket.
-		#   @parameter socket [Socket] The socket which has been bound.
+		# @yields {|socket| ...} If a block is given, yields the bound socket.
+		# 	@parameter socket [Socket] The socket which has been bound.
 		# @returns [Array(Socket)] the bound socket
 		def bind(wrapper = self.wrapper, &block)
 			raise NotImplementedError
@@ -70,14 +75,15 @@ module IO::Endpoint
 		
 		# Connects a socket to the given address. If a block is given, the socket will be automatically closed when the block exits.
 		# @parameter wrapper [Wrapper] The wrapper to use for connecting.
-		# @return [Socket] the connected socket
+		# @returns [Socket] the connected socket
 		def connect(wrapper = self.wrapper, &block)
 			raise NotImplementedError
 		end
 		
 		# Bind and accept connections on the given address.
 		# @parameter wrapper [Wrapper] The wrapper to use for accepting connections.
-		# @yields [Socket] The accepted socket.
+		# @yields {|socket| ...} For each accepted connection, yields the socket.
+		# 	@parameter socket [Socket] The accepted socket.
 		def accept(wrapper = self.wrapper, &block)
 			bind(wrapper) do |server|
 				wrapper.accept(server, **@options, &block)
@@ -85,7 +91,7 @@ module IO::Endpoint
 		end
 		
 		# Enumerate all discrete paths as endpoints.
-		# @yields {|endpoint| ...} A block which will be passed each endpoint.
+		# @yields {|endpoint| ...} For each endpoint, yields it.
 		# 	@parameter endpoint [Endpoint] The endpoint.
 		def each
 			return to_enum unless block_given?
@@ -97,8 +103,8 @@ module IO::Endpoint
 		#
 		# You should not use untrusted input as it may execute arbitrary code.
 		#
-		# @param string [String] URI as string. Scheme will decide implementation used.
-		# @param options keyword arguments passed through to {#initialize}
+		# @parameter string [String] URI as string. Scheme will decide implementation used.
+		# @parameter options keyword arguments passed through to {#initialize}
 		#
 		# @see Endpoint.ssl ssl - invoked when parsing a URL with the ssl scheme "ssl://127.0.0.1"
 		# @see Endpoint.tcp tcp - invoked when parsing a URL with the tcp scheme: "tcp://127.0.0.1"

data/lib/io/endpoint/host_endpoint.rb

@@ -6,17 +6,25 @@
 require_relative "address_endpoint"
 
 module IO::Endpoint
+	# Represents an endpoint for a hostname and service that resolves to multiple addresses.
 	class HostEndpoint < Generic
+		# Initialize a new host endpoint.
+		# @parameter specification [Array] The host specification array containing nodename, service, family, socktype, protocol, and flags.
+		# @parameter options [Hash] Additional options to pass to the parent class.
 		def initialize(specification, **options)
 			super(**options)
 			
 			@specification = specification
 		end
 		
+		# Get a string representation of the host endpoint.
+		# @returns [String] A string representation showing hostname and service.
 		def to_s
 			"host:#{@specification[0]}:#{@specification[1]}"
 		end
 		
+		# Get a detailed string representation of the host endpoint.
+		# @returns [String] A detailed string representation including all specification parameters.
 		def inspect
 			nodename, service, family, socktype, protocol, flags = @specification
 			
@@ -24,27 +32,34 @@ module IO::Endpoint
 		end
 		
 		
+		# @attribute [Array] The host specification array.
 		attr :specification
 		
+		# Get the hostname from the specification.
+		# @returns [String, nil] The hostname (nodename) from the specification.
 		def hostname
 			@specification[0]
 		end
 		
+		# Get the service from the specification.
+		# @returns [String, Integer, nil] The service (port) from the specification.
 		def service
 			@specification[1]
 		end
 		
 		# Try to connect to the given host by connecting to each address in sequence until a connection is made.
-		# @yield [Socket] the socket which is being connected, may be invoked more than once
-		# @return [Socket] the connected socket
-		# @raise if no connection could complete successfully
+		# @yields {|socket| ...} If a block is given, yields the connected socket (may be invoked multiple times during connection attempts).
+		# 	@parameter socket [Socket] The socket which is being connected.
+		# @returns [Socket] the connected socket
+		# @raises [Exception] if no connection could complete successfully
 		def connect(wrapper = self.wrapper, &block)
 			last_error = nil
 			
 			Addrinfo.foreach(*@specification) do |address|
 				begin
 					socket = wrapper.connect(address, **@options)
-				rescue Errno::ECONNREFUSED, Errno::ENETUNREACH, Errno::EAGAIN => last_error
+				rescue => last_error
+					Console.debug(self, "Failed to connect:", address, exception: last_error)
 					# Try again unless if possible, otherwise raise...
 				else
 					return socket unless block_given?
@@ -61,15 +76,17 @@ module IO::Endpoint
 		end
 		
 		# Invokes the given block for every address which can be bound to.
-		# @yield [Socket] the bound socket
-		# @return [Array<Socket>] an array of bound sockets
+		# @yields {|socket| ...} For each address that can be bound, yields the bound socket.
+		# 	@parameter socket [Socket] The bound socket.
+		# @returns [Array<Socket>] an array of bound sockets
 		def bind(wrapper = self.wrapper, &block)
 			Addrinfo.foreach(*@specification).map do |address|
 				wrapper.bind(address, **@options, &block)
 			end
 		end
 		
-		# @yield [AddressEndpoint] address endpoints by resolving the given host specification
+		# @yields {|endpoint| ...} For each resolved address, yields an address endpoint.
+		# 	@parameter endpoint [AddressEndpoint] An address endpoint.
 		def each
 			return to_enum unless block_given?
 			
@@ -79,20 +96,20 @@ module IO::Endpoint
 		end
 	end
 	
-	# @param arguments nodename, service, family, socktype, protocol, flags. `socktype` will be set to Socket::SOCK_STREAM.
-	# @param options keyword arguments passed on to {HostEndpoint#initialize}
+	# @parameter arguments nodename, service, family, socktype, protocol, flags. `socktype` will be set to Socket::SOCK_STREAM.
+	# @parameter options keyword arguments passed on to {HostEndpoint#initialize}
 	#
-	# @return [HostEndpoint]
+	# @returns [HostEndpoint]
 	def self.tcp(*arguments, **options)
 		arguments[3] = ::Socket::SOCK_STREAM
 		
 		HostEndpoint.new(arguments, **options)
 	end
-
-	# @param arguments nodename, service, family, socktype, protocol, flags. `socktype` will be set to Socket::SOCK_DGRAM.
-	# @param options keyword arguments passed on to {HostEndpoint#initialize}
+	
+	# @parameter arguments nodename, service, family, socktype, protocol, flags. `socktype` will be set to Socket::SOCK_DGRAM.
+	# @parameter options keyword arguments passed on to {HostEndpoint#initialize}
 	#
-	# @return [HostEndpoint]
+	# @returns [HostEndpoint]
 	def self.udp(*arguments, **options)
 		arguments[3] = ::Socket::SOCK_DGRAM
 		

data/lib/io/endpoint/shared_endpoint.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2024, by Samuel Williams.
+# Copyright, 2023-2025, by Samuel Williams.
 
 require_relative "bound_endpoint"
 require_relative "connected_endpoint"

data/lib/io/endpoint/socket_endpoint.rb

@@ -1,29 +1,41 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2024, by Samuel Williams.
+# Copyright, 2023-2025, by Samuel Williams.
 
 require_relative "generic"
 
 module IO::Endpoint
 	# This class doesn't exert ownership over the specified socket, wraps a native ::IO.
 	class SocketEndpoint < Generic
+		# Initialize a new socket endpoint.
+		# @parameter socket [Socket] The socket to wrap.
+		# @parameter options [Hash] Additional options to pass to the parent class.
 		def initialize(socket, **options)
 			super(**options)
 			
 			@socket = socket
 		end
 		
+		# Get a string representation of the socket endpoint.
+		# @returns [String] A string representation showing the socket.
 		def to_s
 			"socket:#{@socket}"
 		end
 		
+		# Get a detailed string representation of the socket endpoint.
+		# @returns [String] A detailed string representation including the socket.
 		def inspect
 			"\#<#{self.class} #{@socket.inspect}>"
 		end
 		
+		# @attribute [Socket] The wrapped socket.
 		attr :socket
 		
+		# Bind using the wrapped socket.
+		# @yields {|socket| ...} If a block is given, yields the socket.
+		# 	@parameter socket [Socket] The socket.
+		# @returns [Socket] The socket.
 		def bind(&block)
 			if block_given?
 				yield @socket
@@ -32,6 +44,10 @@ module IO::Endpoint
 			end
 		end
 		
+		# Connect using the wrapped socket.
+		# @yields {|socket| ...} If a block is given, yields the socket.
+		# 	@parameter socket [Socket] The socket.
+		# @returns [Socket] The socket.
 		def connect(&block)
 			if block_given?
 				yield @socket
@@ -41,6 +57,10 @@ module IO::Endpoint
 		end
 	end
 	
+	# Create a socket endpoint from an existing socket.
+	# @parameter socket [Socket] The socket to wrap.
+	# @parameter options [Hash] Additional options to pass to the socket endpoint.
+	# @returns [SocketEndpoint] A new socket endpoint instance.
 	def self.socket(socket, **options)
 		SocketEndpoint.new(socket, **options)
 	end

data/lib/io/endpoint/ssl_endpoint.rb

@@ -1,55 +1,75 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2024, by Samuel Williams.
+# Copyright, 2023-2025, by Samuel Williams.
 
 require_relative "host_endpoint"
 require_relative "generic"
 
 require "openssl"
 
+# @namespace
 module OpenSSL
+	# @namespace
 	module SSL
+		# Represents an SSL socket with additional methods for compatibility.
 		class SSLSocket
 			unless method_defined?(:start)
+				# Start the SSL handshake (alias for accept).
 				def start
 					self.accept
 				end
 			end
 		end
 		
+		# Represents a module that forwards socket methods to the underlying IO object.
 		module SocketForwarder
 			unless method_defined?(:close_on_exec=)
+				# Set whether the socket should be closed on exec.
+				# @parameter value [Boolean] Whether to close on exec.
 				def close_on_exec=(value)
 					to_io.close_on_exec = value
 				end
 			end
 			
 			unless method_defined?(:local_address)
+				# Get the local address of the socket.
+				# @returns [Addrinfo] The local address.
 				def local_address
 					to_io.local_address
 				end
 			end
 			
 			unless method_defined?(:remote_address)
+				# Get the remote address of the socket.
+				# @returns [Addrinfo] The remote address.
 				def remote_address
 					to_io.remote_address
 				end
 			end
 			
 			unless method_defined?(:wait)
+				# Wait for the socket to become ready.
+				# @parameter arguments [Array] Arguments to pass to the underlying IO wait method.
+				# @returns [IO, nil] The socket if ready, nil otherwise.
 				def wait(*arguments)
 					to_io.wait(*arguments)
 				end
 			end
 			
 			unless method_defined?(:wait_readable)
+				# Wait for the socket to become readable.
+				# @parameter arguments [Array] Arguments to pass to the underlying IO wait_readable method.
+				# @returns [IO, nil] The socket if readable, nil otherwise.
 				def wait_readable(*arguments)
 					to_io.wait_readable(*arguments)
 				end
 			end
 			
 			unless method_defined?(:wait_writable)
+				# Wait for the socket to become writable.
+				# @parameter arguments [Array] Arguments to pass to the underlying IO wait_writable method.
+				# @returns [IO, nil] The socket if writable, nil otherwise.
 				def wait_writable(*arguments)
 					to_io.wait_writable(*arguments)
 				end
@@ -57,12 +77,16 @@ module OpenSSL
 			
 			if IO.method_defined?(:timeout)
 				unless method_defined?(:timeout)
+					# Get the timeout for socket operations.
+					# @returns [Numeric, nil] The timeout value.
 					def timeout
 						to_io.timeout
 					end
 				end
 				
 				unless method_defined?(:timeout=)
+					# Set the timeout for socket operations.
+					# @parameter value [Numeric, nil] The timeout value.
 					def timeout=(value)
 						to_io.timeout = value
 					end
@@ -73,7 +97,12 @@ module OpenSSL
 end
 
 module IO::Endpoint
+	# Represents an SSL/TLS endpoint that wraps another endpoint.
 	class SSLEndpoint < Generic
+		# Initialize a new SSL endpoint.
+		# @parameter endpoint [Generic] The underlying endpoint to wrap with SSL.
+		# @option ssl_context [OpenSSL::SSL::SSLContext, nil] An optional SSL context to use.
+		# @parameter options [Hash] Additional options including `:ssl_params` and `:hostname`.
 		def initialize(endpoint, **options)
 			super(**options)
 			
@@ -86,29 +115,44 @@ module IO::Endpoint
 			end
 		end
 		
+		# Get a string representation of the SSL endpoint.
+		# @returns [String] A string representation showing the underlying endpoint.
 		def to_s
 			"ssl:#{@endpoint}"
 		end
 		
+		# Get a detailed string representation of the SSL endpoint.
+		# @returns [String] A detailed string representation including the underlying endpoint.
 		def inspect
 			"\#<#{self.class} endpoint=#{@endpoint.inspect}>"
 		end
 		
+		# Get the address from the underlying endpoint.
+		# @returns [Address, nil] The address from the underlying endpoint.
 		def address
 			@endpoint.address
 		end
 		
+		# Get the hostname for SSL verification.
+		# @returns [String, nil] The hostname from options or the underlying endpoint.
 		def hostname
 			@options[:hostname] || @endpoint.hostname
 		end
 		
+		# @attribute [Generic] The underlying endpoint.
 		attr :endpoint
+		# @attribute [Hash] The options hash.
 		attr :options
 		
+		# Get SSL parameters from options.
+		# @returns [Hash, nil] SSL parameters if specified in options.
 		def params
 			@options[:ssl_params]
 		end
 		
+		# Build an SSL context with configured parameters.
+		# @parameter context [OpenSSL::SSL::SSLContext] An optional SSL context to configure.
+		# @returns [OpenSSL::SSL::SSLContext] The configured SSL context.
 		def build_context(context = ::OpenSSL::SSL::SSLContext.new)
 			if params = self.params
 				context.set_params(params)
@@ -120,16 +164,24 @@ module IO::Endpoint
 			return context
 		end
 		
+		# Get or build the SSL context.
+		# @returns [OpenSSL::SSL::SSLContext] The SSL context.
 		def context
 			@context ||= build_context
 		end
 		
+		# Create an SSL server socket from an IO object.
+		# @parameter io [IO] The underlying IO object.
+		# @returns [OpenSSL::SSL::SSLServer] A new SSL server socket.
 		def make_server(io)
 			::OpenSSL::SSL::SSLServer.new(io, self.context).tap do |server|
 				server.start_immediately = false
 			end
 		end
 		
+		# Create an SSL client socket from an IO object.
+		# @parameter io [IO] The underlying IO object.
+		# @returns [OpenSSL::SSL::SSLSocket] A new SSL client socket.
 		def make_socket(io)
 			::OpenSSL::SSL::SSLSocket.new(io, self.context).tap do |socket|
 				# We consider the underlying IO is owned by the SSL socket:
@@ -138,8 +190,9 @@ module IO::Endpoint
 		end
 		
 		# Connect to the underlying endpoint and establish a SSL connection.
-		# @yield [Socket] the socket which is being connected
-		# @return [Socket] the connected socket
+		# @yields {|socket| ...} If a block is given, yields the SSL server socket.
+		# 	@parameter socket [Socket] The SSL server socket.
+		# @returns [Socket] the connected socket
 		def bind(*arguments, **options, &block)
 			if block_given?
 				@endpoint.bind(*arguments, **options) do |server|
@@ -153,8 +206,9 @@ module IO::Endpoint
 		end
 		
 		# Connect to the underlying endpoint and establish a SSL connection.
-		# @yield [Socket] the socket which is being connected
-		# @return [Socket] the connected socket
+		# @yields {|socket| ...} If a block is given, yields the connected SSL socket.
+		# 	@parameter socket [Socket] The connected SSL socket.
+		# @returns [Socket] the connected socket
 		def connect(&block)
 			socket = self.make_socket(@endpoint.connect)
 			
@@ -170,7 +224,7 @@ module IO::Endpoint
 			end
 			
 			return socket unless block_given?
-				
+			
 			begin
 				yield socket
 			ensure
@@ -178,6 +232,9 @@ module IO::Endpoint
 			end
 		end
 		
+		# Enumerate all endpoints by wrapping each underlying endpoint with SSL.
+		# @yields {|endpoint| ...} For each underlying endpoint, yields an SSL-wrapped endpoint.
+		# 	@parameter endpoint [SSLEndpoint] An SSL endpoint.
 		def each
 			return to_enum unless block_given?
 			
@@ -186,13 +243,13 @@ module IO::Endpoint
 			end
 		end
 	end
-
-	# @param arguments
-	# @param ssl_context [OpenSSL::SSL::SSLContext, nil]
-	# @param hostname [String, nil]
-	# @param options keyword arguments passed through to {Endpoint.tcp}
+	
+	# @parameter arguments
+	# @parameter ssl_context [OpenSSL::SSL::SSLContext, nil]
+	# @parameter hostname [String, nil]
+	# @parameter options keyword arguments passed through to {Endpoint.tcp}
 	#
-	# @return [SSLEndpoint]
+	# @returns [SSLEndpoint]
 	def self.ssl(*arguments, ssl_context: nil, hostname: nil, **options)
 		SSLEndpoint.new(self.tcp(*arguments, **options), ssl_context: ssl_context, hostname: hostname)
 	end

data/lib/io/endpoint/unix_endpoint.rb

@@ -1,13 +1,17 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2024, by Samuel Williams.
+# Copyright, 2023-2025, by Samuel Williams.
 
 require_relative "address_endpoint"
 
 module IO::Endpoint
 	# This class doesn't exert ownership over the specified unix socket and ensures exclusive access by using `flock` where possible.
 	class UNIXEndpoint < AddressEndpoint
+		# Initialize a new UNIX domain socket endpoint.
+		# @parameter path [String] The path to the UNIX socket.
+		# @parameter type [Integer] The socket type (defaults to Socket::SOCK_STREAM).
+		# @parameter options [Hash] Additional options to pass to the parent class.
 		def initialize(path, type = Socket::SOCK_STREAM, **options)
 			# I wonder if we should implement chdir behaviour in here if path is longer than 104 characters.
 			super(Address.unix(path, type), **options)
@@ -15,16 +19,23 @@ module IO::Endpoint
 			@path = path
 		end
 		
+		# Get a string representation of the UNIX endpoint.
+		# @returns [String] A string representation showing the socket path.
 		def to_s
 			"unix:#{@path}"
 		end
 		
+		# Get a detailed string representation of the UNIX endpoint.
+		# @returns [String] A detailed string representation including the path.
 		def inspect
 			"\#<#{self.class} path=#{@path.inspect}>"
 		end
 		
+		# @attribute [String] The path to the UNIX socket.
 		attr :path
 		
+		# Check if the socket is currently bound and accepting connections.
+		# @returns [Boolean] True if the socket is bound and accepting connections, false otherwise.
 		def bound?
 			self.connect do
 				return true
@@ -35,7 +46,12 @@ module IO::Endpoint
 			return false
 		end
 		
-		def bind(&block)
+		# Bind the UNIX socket, handling stale socket files.
+		# @yields {|socket| ...} If a block is given, yields the bound socket.
+		# 	@parameter socket [Socket] The bound socket.
+		# @returns [Array(Socket)] The bound socket.
+		# @raises [Errno::EADDRINUSE] If the socket is still in use by another process.
+		def bind(...)
 			super
 		rescue Errno::EADDRINUSE
 			# If you encounter EADDRINUSE from `bind()`, you can check if the socket is actually accepting connections by attempting to `connect()` to it. If the socket is still bound by an active process, the connection will succeed. Otherwise, it should be safe to `unlink()` the path and try again.
@@ -48,11 +64,11 @@ module IO::Endpoint
 		end
 	end
 	
-	# @param path [String]
-	# @param type Socket type
-	# @param options keyword arguments passed through to {UNIXEndpoint#initialize}
+	# @parameter path [String]
+	# @parameter type Socket type
+	# @parameter options keyword arguments passed through to {UNIXEndpoint#initialize}
 	#
-	# @return [UNIXEndpoint]
+	# @returns [UNIXEndpoint]
 	def self.unix(path = "", type = ::Socket::SOCK_STREAM, **options)
 		UNIXEndpoint.new(path, type, **options)
 	end

data/lib/io/endpoint/version.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2024, by Samuel Williams.
+# Copyright, 2023-2025, by Samuel Williams.
 
+# @namespace
 class IO
+	# @namespace
 	module Endpoint
-		VERSION = "0.15.1"
+		VERSION = "0.16.0"
 	end
 end

data/lib/io/endpoint/wrapper.rb

@@ -6,10 +6,15 @@
 require "socket"
 
 module IO::Endpoint
+	# Represents a wrapper for socket operations that provides scheduling and configuration.
 	class Wrapper
 		include ::Socket::Constants
 		
 		if Fiber.respond_to?(:scheduler)
+			# Schedule a block to run asynchronously.
+			# Uses Fiber scheduler if available, otherwise falls back to Thread.
+			# @yields { ...} The block to schedule.
+			# @returns [Fiber, Thread] The scheduled fiber or thread.
 			def schedule(&block)
 				if Fiber.scheduler
 					Fiber.schedule(&block)
@@ -18,6 +23,10 @@ module IO::Endpoint
 				end
 			end
 		else
+			# Schedule a block to run asynchronously.
+			# Uses Thread for scheduling.
+			# @yields { ...} The block to schedule.
+			# @returns [Thread] The scheduled thread.
 			def schedule(&block)
 				Thread.new(&block)
 			end
@@ -28,12 +37,18 @@ module IO::Endpoint
 			schedule(&block)
 		end
 		
+		# Set the timeout for an IO object.
+		# @parameter io [IO] The IO object to set timeout on.
+		# @parameter timeout [Numeric, nil] The timeout value.
 		def set_timeout(io, timeout)
 			if io.respond_to?(:timeout=)
 				io.timeout = timeout
 			end
 		end
 		
+		# Set whether a socket should be buffered.
+		# @parameter socket [Socket] The socket to configure.
+		# @parameter buffered [Boolean] Whether the socket should be buffered.
 		def set_buffered(socket, buffered)
 			case buffered
 			when true
@@ -220,6 +235,8 @@ module IO::Endpoint
 		
 		DEFAULT = new
 		
+		# Get the default wrapper instance.
+		# @returns [Wrapper] The default wrapper instance.
 		def self.default
 			DEFAULT
 		end

data/lib/io/endpoint.rb

@@ -7,7 +7,10 @@ require_relative "endpoint/version"
 require_relative "endpoint/generic"
 require_relative "endpoint/shared_endpoint"
 
+# Represents a collection of endpoint classes for network I/O operations.
 module IO::Endpoint
+	# Get the current file descriptor limit for the process.
+	# @returns [Integer] The soft limit for the number of open file descriptors.
 	def self.file_descriptor_limit
 		Process.getrlimit(Process::RLIMIT_NOFILE).first
 	end

data/readme.md

@@ -6,7 +6,9 @@ Provides a separation of concerns interface for IO endpoints. This allows you to
 
 ## Usage
 
-Please see the [documentation](https://socketry.github.io/io-endpoint) for more information.
+Please see the [project documentation](https://socketry.github.io/io-endpoint) for more details.
+
+  - [Getting Started](https://socketry.github.io/io-endpointguides/getting-started/index) - This guide explains how to get started with `io-endpoint`, a library that provides a separation of concerns interface for network I/O endpoints.
 
 ## Contributing
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: io-endpoint
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  version: 0.16.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -36,12 +36,14 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-02-13 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/getting-started.md
+- context/index.yaml
 - lib/io/endpoint.rb
 - lib/io/endpoint/address_endpoint.rb
 - lib/io/endpoint/bound_endpoint.rb
@@ -70,14 +72,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Provides a separation of concerns interface for IO endpoints.
 test_files: []