io-endpoint 0.16.0 → 0.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85b2a321334cd16a75da466ebff7b9f380410788f173936e9bffd5482599e2ad
-  data.tar.gz: f207fe739fe89220f59037ec54b1020795509598d4f0deb7a9caaf2cb36e8ea5
+  metadata.gz: 6a1fd8b9900456445fa95fc7de22135fc86c96c9ed05586acec98c492de11ab7
+  data.tar.gz: b179c79964d3fba2d92753fc4494fd0fa2a88bcb825dc20561a61784adc60fec
 SHA512:
-  metadata.gz: 7154bdc644a2e8f2689567b9804d4019c263f07dd28f44ec98084ed4c3459ea1521724dcf0d4b90d2be9928a9eb4bbcb58895e18e10d461109f91dbdc6cb45ea
-  data.tar.gz: d8f01abe1ee5d1c93184505f03c2ec4226b6b4eed20754d413b8dcdfa5d5e339d3169069a420fac31b26eca2e157548ad7479e51f8457a14c8f3db5d1efe9e78
+  metadata.gz: 6370da98fec490d732f957fd5cf947396551bed010d88211a4e6684529d4ea930bff17753ae672c3cc8e482315f96bd2d31ee4365a77bb85476fa12da23ace4f
+  data.tar.gz: c478357360832dd7c225979f2531025025f711fca06616b4efd2a7398d700a1c248021a5d2be6749fd9b5dc5950cd04a953ac383527c8d2cb301745ee5ac5038

data/context/index.yaml

@@ -10,3 +10,8 @@ files:
   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.
+- path: named-endpoints.md
+  title: Named Endpoints
+  description: This guide explains how to use `IO::Endpoint::NamedEndpoints` to manage
+    multiple endpoints by name, enabling scenarios like running the same application
+    on different protocols or ports.

data/context/named-endpoints.md

@@ -0,0 +1,140 @@
+# Named Endpoints
+
+This guide explains how to use `IO::Endpoint::NamedEndpoints` to manage multiple endpoints by name, enabling scenarios like running the same application on different protocols or ports.
+
+## Overview
+
+`NamedEndpoints` is a collection of endpoints that can be accessed by symbolic names. Unlike {ruby IO::Endpoint::CompositeEndpoint}, which treats endpoints as an ordered list for failover, `NamedEndpoints` allows you to:
+
+- **Access endpoints by name**: Use symbolic keys like `:http1` or `:http2` instead of array indices.
+- **Run multiple configurations**: Serve the same application on different protocols, ports, or transports simultaneously.
+- **Iterate over endpoints**: Process all endpoints while maintaining their names for configuration lookup.
+
+## When to Use NamedEndpoints
+
+Use `NamedEndpoints` when you need to:
+
+- Run the same server application on multiple endpoints with different configurations (e.g., HTTP/1 and HTTP/2).
+- Access endpoints by symbolic names rather than position.
+- Bind multiple endpoints and create servers for each one.
+- Manage a collection of endpoints where each has a specific role or configuration.
+
+If you need failover behavior (trying endpoints in order until one succeeds), use {ruby IO::Endpoint::CompositeEndpoint} instead.
+
+## Creating Named Endpoints
+
+### Using the Constructor
+
+Create a `NamedEndpoints` instance by passing a hash of endpoints:
+
+```ruby
+require "io/endpoint"
+
+http1_endpoint = IO::Endpoint.tcp("localhost", 8080)
+http2_endpoint = IO::Endpoint.tcp("localhost", 8090)
+
+named = IO::Endpoint::NamedEndpoints.new(
+	http1: http1_endpoint,
+	http2: http2_endpoint
+)
+```
+
+### Using the Factory Method
+
+The `IO::Endpoint.named` factory method provides a convenient way to create named endpoints:
+
+```ruby
+require "io/endpoint"
+
+named = IO::Endpoint.named(
+	http1: IO::Endpoint.tcp("localhost", 8080),
+	http2: IO::Endpoint.tcp("localhost", 8090),
+	https: IO::Endpoint.ssl("localhost", 8443)
+)
+```
+
+## Accessing Endpoints
+
+Access endpoints by their names using the `[]` operator:
+
+```ruby
+named = IO::Endpoint.named(
+	http1: IO::Endpoint.tcp("localhost", 8080),
+	http2: IO::Endpoint.tcp("localhost", 8090)
+)
+
+# Access by name
+http1 = named[:http1]
+http2 = named[:http2]
+
+# Returns nil if not found
+missing = named[:nonexistent]  # => nil
+```
+
+## Iterating Over Endpoints
+
+### Using `each`
+
+The `each` method yields both the name and endpoint:
+
+```ruby
+named = IO::Endpoint.named(
+	http1: IO::Endpoint.tcp("localhost", 8080),
+	http2: IO::Endpoint.tcp("localhost", 8090)
+)
+
+named.each do |name, endpoint|
+	puts "Endpoint #{name} is bound to #{endpoint}"
+end
+```
+
+To map over endpoint values, use `endpoints.values.map`:
+
+```ruby
+protocols = named.endpoints.values.map do |endpoint|
+	endpoint.protocol.to_s
+end
+
+# => ["HTTP1", "HTTP2"]
+```
+
+## Binding Endpoints
+
+To bind endpoints, iterate over the collection and bind each endpoint individually, or use the `bound` method to create a new collection with all endpoints bound.
+
+The `bound` method creates a new `NamedEndpoints` instance where all endpoints are bound:
+
+```ruby
+named = IO::Endpoint.named(
+	http1: IO::Endpoint.tcp("localhost", 8080),
+	http2: IO::Endpoint.tcp("localhost", 8090)
+)
+
+bound_named = named.bound(reuse_address: true)
+
+# All endpoints are now bound
+bound_named.each do |name, bound_endpoint|
+	server = bound_endpoint.sockets.first
+	server.listen(10)
+end
+```
+
+## Connecting to Endpoints
+
+To connect to a specific endpoint, access it by name and call `connect` on that endpoint:
+
+```ruby
+named = IO::Endpoint.named(
+	primary: IO::Endpoint.tcp("server1.example.com", 80),
+	secondary: IO::Endpoint.tcp("server2.example.com", 80)
+)
+
+# Connect to a specific endpoint by name
+named[:primary].connect do |socket|
+	socket.write("GET / HTTP/1.1\r\n\r\n")
+	response = socket.read
+	puts response
+end
+```
+
+If you need failover behavior (trying endpoints in order until one succeeds), use {ruby IO::Endpoint::CompositeEndpoint} instead.

data/lib/io/endpoint/named_endpoints.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "generic"
+
+module IO::Endpoint
+	# A named endpoints collection is a hash of endpoints that can be accessed by name.
+	#
+	# Unlike {CompositeEndpoint}, which treats endpoints as an ordered list for failover, `NamedEndpoints` allows you to access endpoints by symbolic names, making it useful for scenarios where you need to run the same application on multiple endpoints with different configurations (e.g., HTTP/1 and HTTP/2 on different ports).
+	class NamedEndpoints
+		# Initialize a new named endpoints collection.
+		# @parameter endpoints [Hash(Symbol, Generic)] A hash mapping endpoint names to endpoint instances.
+		def initialize(endpoints)
+			@endpoints = endpoints
+		end
+		
+		# Get a string representation of the named endpoints.
+		# @returns [String] A string representation listing all named endpoints.
+		def to_s
+			parts = @endpoints.map do |name, endpoint|
+				"#{name}:#{endpoint}"
+			end
+			"named:#{parts.join(",")}"
+		end
+		
+		# Get a detailed string representation of the named endpoints.
+		# @returns [String] A detailed string representation including all named endpoints.
+		def inspect
+			parts = @endpoints.map do |name, endpoint|
+				"#{name}: #{endpoint.inspect}"
+			end
+			"\#<#{self.class} #{parts.join(", ")}>"
+		end
+		
+		# @attribute [Hash(Symbol, Generic)] The endpoints hash mapping names to endpoint instances.
+		attr :endpoints
+		
+		# Access an endpoint by its name.
+		# @parameter key [Symbol] The name of the endpoint to access.
+		# @returns [Generic, nil] The endpoint with the given name, or nil if not found.
+		def [] key
+			@endpoints[key]
+		end
+		
+		# Enumerate all endpoints with their names.
+		# @yields {|name, endpoint| ...} For each endpoint, yields the name and endpoint.
+		# 	@parameter name [Symbol] The name of the endpoint.
+		# 	@parameter endpoint [Generic] The endpoint.
+		def each(&block)
+			@endpoints.each(&block)
+		end
+		
+		# Create a new named endpoints instance with all endpoints bound.
+		# @parameter options [Hash] Options to pass to each endpoint's bound method.
+		# @returns [NamedEndpoints] A new instance with bound endpoints.
+		def bound(**options)
+			self.class.new(
+				@endpoints.transform_values{|endpoint| endpoint.bound(**options)}
+			)
+		end
+		
+		# Create a new named endpoints instance with all endpoints connected.
+		# @parameter options [Hash] Options to pass to each endpoint's connected method.
+		# @returns [NamedEndpoints] A new instance with connected endpoints.
+		def connected(**options)
+			self.class.new(
+				@endpoints.transform_values{|endpoint| endpoint.connected(**options)}
+			)
+		end
+		
+		# Close all endpoints in the collection.
+		# Calls `close` on each endpoint value.
+		# @returns [void]
+		def close
+			@endpoints.each_value(&:close)
+		end
+	end
+	
+	# Create a named endpoints collection from keyword arguments.
+	# @parameter endpoints [Hash(Symbol, Generic)] Named endpoints as keyword arguments.
+	# @returns [NamedEndpoints] A new named endpoints instance.
+	# @example Create a named endpoints collection
+	# 	endpoints = IO::Endpoint.named(
+	# 		http1: IO::Endpoint.tcp("localhost", 8080),
+	# 		http2: IO::Endpoint.tcp("localhost", 8090)
+	# 	)
+	def self.named(**endpoints)
+		NamedEndpoints.new(endpoints)
+	end
+end

data/lib/io/endpoint/version.rb

@@ -7,6 +7,6 @@
 class IO
 	# @namespace
 	module Endpoint
-		VERSION = "0.16.0"
+		VERSION = "0.17.1"
 	end
 end

data/lib/io/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 "endpoint/version"
 require_relative "endpoint/generic"

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2023-2025, by Samuel Williams.  
+Copyright, 2023-2026, by Samuel Williams.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -10,6 +10,58 @@ Please see the [project documentation](https://socketry.github.io/io-endpoint) f
 
   - [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.
 
+  - [Named Endpoints](https://socketry.github.io/io-endpointguides/named-endpoints/index) - This guide explains how to use `IO::Endpoint::NamedEndpoints` to manage multiple endpoints by name, enabling scenarios like running the same application on different protocols or ports.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/io-endpointreleases/index) for all releases.
+
+### v0.17.1
+
+  - Add `#to_s` and `#inspect` for `IO::Endpoint::NamedEndpoints`.
+
+### v0.17.0
+
+  - Added `IO::Endpoint::NamedEndpoints` for accessing endpoints by symbolic names, useful for running applications on multiple endpoints with different configurations.
+
+### v0.16.0
+
+  - Improved error handling in `#connect` for more robust connection handling.
+  - Added getting started guide and improved documentation coverage.
+
+### v0.15.2
+
+  - Fixed `UNIXEndpoint#bind` to pass all arguments through to super.
+
+### v0.15.1
+
+  - Added `async-dns` to externals and restored removed method.
+
+### v0.15.0
+
+  - Allow wrapper to be customized using endpoint `options[:wrapper]`.
+  - Expose wrapper extension points for `connect` and `accept`.
+
+### v0.14.0
+
+  - Uniform `#to_s` and `#inspect` implementations across all endpoints.
+
+### v0.13.1
+
+  - Fixed state leak between iterations of the accept loop.
+
+### v0.13.0
+
+  - Propagate options assigned to composite endpoint to nested endpoints.
+
+### v0.12.0
+
+  - Expose `size` and internal endpoints for composite endpoint.
+
+## See Also
+
+  - [async-io](https://github.com/socketry/async-io) — Where this implementation originally came from.
+
 ## Contributing
 
 We welcome contributions to this project.
@@ -27,7 +79,3 @@ In order to protect users of this project, we require all contributors to comply
 ### Community Guidelines
 
 This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.
-
-## See Also
-
-  - [async-io](https://github.com/socketry/async-io) — Where this implementation originally came from.

data/releases.md

@@ -0,0 +1,111 @@
+# Releases
+
+## v0.17.1
+
+  - Add `#to_s` and `#inspect` for `IO::Endpoint::NamedEndpoints`.
+
+## v0.17.0
+
+  - Added `IO::Endpoint::NamedEndpoints` for accessing endpoints by symbolic names, useful for running applications on multiple endpoints with different configurations.
+
+## v0.16.0
+
+  - Improved error handling in `#connect` for more robust connection handling.
+  - Added getting started guide and improved documentation coverage.
+
+## v0.15.2
+
+  - Fixed `UNIXEndpoint#bind` to pass all arguments through to super.
+
+## v0.15.1
+
+  - Added `async-dns` to externals and restored removed method.
+
+## v0.15.0
+
+  - Allow wrapper to be customized using endpoint `options[:wrapper]`.
+  - Expose wrapper extension points for `connect` and `accept`.
+
+## v0.14.0
+
+  - Uniform `#to_s` and `#inspect` implementations across all endpoints.
+
+## v0.13.1
+
+  - Fixed state leak between iterations of the accept loop.
+
+## v0.13.0
+
+  - Propagate options assigned to composite endpoint to nested endpoints.
+
+## v0.12.0
+
+  - Expose `size` and internal endpoints for composite endpoint.
+
+## v0.10.3
+
+  - Fixed `SSLServer#accept` failures causing accept loop to exit. (\#10)
+
+## v0.10.2
+
+  - Centralized usage of `listen` to wrapper.
+
+## v0.10.1
+
+  - Ensure `listen` is called.
+
+## v0.10.0
+
+  - Don't hardcode timeout support - detect at run-time.
+
+## v0.9.0
+
+  - Correctly set `sync_close`. (\#7)
+
+## v0.8.1
+
+  - Remove broken `require_relative 'readable'`.
+
+## v0.8.0
+
+  - Removed `IO#readable?` dependency in favor of `io-stream` gem.
+
+## v0.7.2
+
+  - Added missing `SSLSocket#remote_address`.
+
+## v0.7.1
+
+  - Improved shims for `IO#readable?`.
+
+## v0.7.0
+
+  - Fixed shim for `OpenSSL::SSL::SSLSocket#local_address`.
+  - Added shim for `IO#readable?`.
+
+## v0.6.0
+
+  - Allow `Wrapper#accept` to ignore unknown options.
+
+## v0.5.0
+
+  - Fixed the OpenSSL shims. (\#5)
+  - Simplified implementation and separated connected/bound options. (\#4)
+
+## v0.4.0
+
+  - Improved compatibility with `async-http`/`async-io`. (\#3)
+
+## v0.3.0
+
+  - Fixed OpenSSL integration. (\#2)
+
+## v0.2.0
+
+  - Added option `buffered:` for controlling `TCP_NODELAY`.
+
+## v0.1.0
+
+  - Initial implementation extracted from `async-io`.
+  - Added support for thread and fiber wrappers.
+  - Support Ruby 2.7+ with optional `set_timeout`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: io-endpoint
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.17.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -44,6 +44,7 @@ extra_rdoc_files: []
 files:
 - context/getting-started.md
 - context/index.yaml
+- context/named-endpoints.md
 - lib/io/endpoint.rb
 - lib/io/endpoint/address_endpoint.rb
 - lib/io/endpoint/bound_endpoint.rb
@@ -51,6 +52,7 @@ files:
 - lib/io/endpoint/connected_endpoint.rb
 - lib/io/endpoint/generic.rb
 - lib/io/endpoint/host_endpoint.rb
+- lib/io/endpoint/named_endpoints.rb
 - lib/io/endpoint/shared_endpoint.rb
 - lib/io/endpoint/socket_endpoint.rb
 - lib/io/endpoint/ssl_endpoint.rb
@@ -59,6 +61,7 @@ files:
 - lib/io/endpoint/wrapper.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/io-endpoint
 licenses:
 - MIT
@@ -79,7 +82,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Provides a separation of concerns interface for IO endpoints.
 test_files: []