socketry 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: c946ff077911e96715c6ed49e1f05d68048c5ce1
-  data.tar.gz: fc23762cd7df18e38aa1b256fa8043455d15e76c
+SHA256:
+  metadata.gz: bb6cedf3671c482943ca47ac78560a9336a24483c8360acf69d9fc0b554ed763
+  data.tar.gz: 3ddc39a363c81b193a83bef5f686061f97b22c116012eb0aba573cf784580773
 SHA512:
-  metadata.gz: b2e079c8d3765b5279a8fccaed3315ffdb18697350a248318539a0e06e366c3e1d11b8ff7806b457c1c003e91a8e35cbed0a5bb1244c64fcaae4beda73f21913
-  data.tar.gz: 9dcc209420f1d8db8486dbd6ab89a7213689256fc3f12f1d7e82a04ff97f6fe1cc75ad35b7655bec3949a7876612ce7c72db76af14adc30223b67cf1dc415b41
+  metadata.gz: a1768e2f61b5471f105cebc4b694efe141c3fecd5e7d74cf209224b714f7ff15868d95b0434de9cea869f3bfa7803e213db0c4f1d4a19a519893de51915f6cc8
+  data.tar.gz: 2b0816ac308875a0b43703f6ffee289e59f8e575949d8edbea9156eb45c84edc0361b3823120ee2ccb19276f0c0670d2bfa3e58fd629484a8edd50df351553cd

data/context/configuration.md

@@ -0,0 +1,154 @@
+# Configuration and Builder
+
+Use a mutable `Configuration` and a separate `Builder` for Ruby configuration DSLs in Socketry projects. This guide defines their responsibilities, construction, file loading, and explicit freezing.
+
+## Design
+
+Create the configuration first. Pass it to a builder, which applies the DSL to that same object. Return the configuration after evaluation, keeping it mutable.
+
+- `Configuration` owns the configuration state, defaults, readers, and mutation methods. It can be configured directly through its public API.
+- `Builder` provides the DSL and file-loading context. It changes the configuration through its public API. Use `Builder` as the standard name for this role, including when it loads files.
+- `Configuration.build` evaluates a block through a builder and returns the configuration.
+- `Configuration.load` loads files in order into one configuration and returns it.
+- `Configuration#freeze` finalises the configuration when the caller chooses. `.build` and `.load` do not call it automatically.
+
+The builder does not keep a second set of configuration values to transfer later. There is no final `Builder#build` step, `new(builder.attributes)` conversion, snapshot copying, or automatic freezing. Configuration readers belong on `Configuration`; the builder only needs its configuration reference and any DSL context such as a root directory.
+
+Keep domain invariants in configuration mutation methods so they also apply to direct callers. The builder can translate convenient DSL arguments into those operations. Use ordinary writers for simple values and methods such as `add` for collections. A DSL method can have the same name as a configuration reader because they are on different objects.
+
+## Example
+
+The classes below share a project namespace. In a gem, they can live in separate `configuration.rb` and `builder.rb` files. `entry` and `concurrency` illustrate a collection and a scalar setting; use the project's own domain operations and defaults.
+
+```ruby
+# frozen_string_literal: true
+
+module Example
+	class Builder
+		def initialize(configuration, root = Dir.pwd)
+			@configuration = configuration
+			@root = File.expand_path(root)
+		end
+		
+		attr :root
+		
+		def entry(name, value)
+			@configuration.add(name, value)
+		end
+		
+		def concurrency(value)
+			@configuration.concurrency = value
+		end
+		
+		def self.load_file(configuration, path)
+			path = File.realpath(path)
+			builder = self.new(configuration, File.dirname(path))
+			builder.instance_eval(File.read(path), path, 1)
+		end
+		
+		def load_file(path)
+			self.class.load_file(@configuration, File.expand_path(path, @root))
+		end
+	end
+	
+	class Configuration
+		def self.build(root: Dir.pwd, &block)
+			configuration = self.new
+			builder = Builder.new(configuration, root)
+			
+			if block
+				if block.arity.zero?
+					builder.instance_eval(&block)
+				else
+					block.call(builder)
+				end
+			end
+			
+			return configuration
+		end
+		
+		def self.load(paths)
+			configuration = self.new
+			Array(paths).each{|path| configuration.load_file(path)}
+			return configuration
+		end
+		
+		def initialize
+			@entries = {}
+			@concurrency = 1
+		end
+		
+		attr :entries
+		attr_accessor :concurrency
+		
+		def add(name, value)
+			@entries[name.to_sym] = value
+		end
+		
+		def load_file(path)
+			Builder.load_file(self, path)
+			return self
+		end
+		
+		def freeze
+			return self if frozen?
+			
+			@entries.freeze
+			
+			super
+		end
+	end
+end
+```
+
+The DSL and direct API operate on the same mutable state:
+
+```ruby
+configuration = Example::Configuration.build do
+	entry :primary, "https://example.com"
+	concurrency 2
+end
+
+configuration.add(:secondary, "https://secondary.example.com")
+configuration.concurrency = 4
+
+Example::Configuration.build do |builder|
+	builder.entry(:primary, "https://example.com")
+end
+```
+
+The example allows an omitted block to return defaults. With a zero-arity block, `self` is the builder; with an explicit block argument, the caller's `self` is preserved. Both factories return the configuration regardless of the block's or file's last expression.
+
+## Explicit Freezing
+
+Implement `Configuration#freeze` to freeze the state owned by the configuration, then call `super` to freeze the configuration itself. Return `self` immediately when already frozen so repeated calls do not repeat finalisation. The same configuration object is returned; freezing does not construct a replacement.
+
+The example owns the `entries` hash and freezes it in place. Its registered values are application-supplied objects retained by reference, so they remain untouched. Freeze owned nested configuration data as appropriate to its schema, but do not recursively freeze arbitrary handlers, policies, or other application objects. Freezing the outer object alone would still allow `add` to modify an unfrozen hash.
+
+The caller decides when configuration is complete:
+
+```ruby
+configuration.freeze
+```
+
+After this call, `concurrency=` and `add` raise `FrozenError`, including when called through a builder attached to the configuration. References previously obtained from `configuration.entries` refer to the same frozen hash. Registered objects keep their own lifecycle and mutability.
+
+If finalisation prepares derived state, do that before calling `super`. Runtime methods must not depend on assigning new instance variables after the configuration has been frozen.
+
+## File Loading
+
+Each file is evaluated by a new builder attached to the shared configuration. Its root is that file's directory. A nested `load_file "other.rb"` resolves against the calling builder's root and creates another builder for the referenced file. The original builder keeps its root throughout; no temporary root assignment or restoration is needed.
+
+Resolve the file path before creating the builder, and pass the filename and starting line to `instance_eval` for useful source locations. Configuration files execute trusted application Ruby.
+
+Multiple top-level files share one configuration. The example applies them in order, with later entries replacing earlier entries of the same name. Preserve the domain's duplicate and override rules when adapting the pattern. Evaluation errors propagate; mutations made before an error remain on an existing configuration. Loading is not transactional.
+
+## Applying the Standard
+
+Use this design for new configuration DSLs and when standardising existing ones. Preserve existing public names and entry points as compatibility wrappers where needed; an existing `Loader` can retain its name while the implementation moves to `Builder`. Keep runtime query methods and domain validation on the configuration.
+
+Verify that block and file factories return the configured object, that it can still be changed through the direct API, and that builders for multiple files update that same object. Explicit freezing should return that object, tolerate repeated calls, and prevent changes to its owned state through writers, collection readers, or attached builders, while leaving application objects untouched. For nested files, check relative resolution, stable builder roots, and exception source locations.
+
+## Established Examples
+
+This design follows [Falcon's configuration/loader separation from June 2019](https://github.com/socketry/falcon/commit/438e04eb295400f0481d72b610a2f9c9ea062746), carried into [Async::Service in February 2024](https://github.com/socketry/async-service/commit/d2d717b7605d364df3a853e8a810aeab2bc36078). Async::Service's [configuration](https://github.com/socketry/async-service/blob/f32af00e5c7a54c936023b96f180710e811d410e/lib/async/service/configuration.rb) and [loader](https://github.com/socketry/async-service/blob/f32af00e5c7a54c936023b96f180710e811d410e/lib/async/service/loader.rb) illustrate the mutable state and per-file loading scopes. This standard uses the name `Builder` for that DSL role.

data/lib/socketry/version.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+# @namespace
 module Socketry
-  VERSION = "0.5.1"
+	VERSION = "0.6.0"
 end

data/lib/socketry.rb

@@ -1,25 +1,6 @@
 # frozen_string_literal: true
 
-# Ruby stdlib dependencies
-require "io/wait"
-require "ipaddr"
-require "socket"
-require "openssl"
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
 
-# External gems
-require "hitimes"
-
-# Socketry codebase
-require "socketry/version"
-
-require "socketry/exceptions"
-require "socketry/resolver/resolv"
-require "socketry/resolver/system"
-require "socketry/timeout"
-
-require "socketry/tcp/server"
-require "socketry/tcp/socket"
-require "socketry/ssl/server"
-require "socketry/ssl/socket"
-require "socketry/udp/datagram"
-require "socketry/udp/socket"
+require_relative "socketry/version"

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 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
+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.

data/readme.md

@@ -0,0 +1,47 @@
+# Socketry
+
+Socketry project metadata, agent context, and skills.
+
+[![Development Status](https://github.com/socketry/socketry/workflows/Test/badge.svg)](https://github.com/socketry/socketry/actions?workflow=Test)
+
+## Agent Context
+
+This gem distributes project conventions in the top-level `context/` directory:
+
+  - [Configuration and Builder](context/configuration.md) defines the mutable configuration and builder design for Ruby configuration DSLs.
+
+Projects that include `socketry` and [`agent-context`](https://github.com/socketry/agent-context) can install the context and update their `agents.md` index with:
+
+``` bash
+bundle exec bake agent:context:install --gem socketry
+```
+
+## Agent Skills
+
+This gem provides reusable agent skills in the top-level `skills/` directory. Use [`agent-skills`](https://github.com/socketry/agent-skills) to discover and install them into a project.
+
+## Releases
+
+Releases use [`bake-gem-github`](https://github.com/socketry/bake-gem-github). With Ruby 3.3 or later, install maintenance dependencies before preparing a release:
+
+``` bash
+bundle config set --local with maintenance
+bundle install
+```
+
+Add release notes under `Unreleased` in `releases.md`. From a clean, up-to-date `main`, prepare a release pull request:
+
+``` bash
+bundle exec bake gem:github:release:patch # or minor or major
+```
+
+The release hook versions the notes. GitHub validates the release changes, then publishes the merged release to RubyGems using Trusted Publishing.
+
+Publishing uses the `rubygems` GitHub environment, restricted to `main`. For initial activation, register a RubyGems Trusted Publisher for `socketry/socketry`, workflow `release-publish.yaml`, environment `rubygems`. After merging the setup and confirming the `Gem build` and `Release validation` checks run, review and apply the repository policy:
+
+``` bash
+bundle exec bake gem:github:setup:plan
+bundle exec bake gem:github:setup:apply
+```
+
+The policy requires two PR approvals with administrator bypass. See the [release setup guide](https://socketry.github.io/bake-gem-github/guides/getting-started/index) for configuration and recovery.

data/releases.md

@@ -0,0 +1,6 @@
+# Releases
+
+## Unreleased
+
+- Distribute the mutable Configuration and Builder convention through `agent-context`.
+- Prepare reviewed releases and publish through GitHub Actions using `bake-gem-github`.

data/skills/socketry-github-repository/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: socketry-github-repository
+description: Create and maintain Socketry GitHub repositories using the project conventions.
+---
+
+# Socketry GitHub Repository
+
+Use this skill when creating or maintaining GitHub repositories for Socketry projects.
+
+## Repository Metadata
+
+Repository metadata should be concise, accurate, and consistent with the project purpose.
+
+- Use the canonical GitHub organization and repository name for the project.
+- Set a clear repository description that explains what the project provides.
+- Set the homepage to the project documentation site when one exists.
+- Add relevant topics that help discovery without duplicating words already present in the repository name.
+- Prefer existing Socketry naming conventions over inventing new phrasing.
+
+## Repository Setup
+
+When creating a new repository, configure the repository so it is immediately useful to contributors and automation.
+
+- Ensure the default branch is `main`.
+- Enable `Issues`.
+- Enable `Sponsorships`.
+- Enable `Preserve this repository`.
+- Enable `Discussions`.
+- Enable `Pull Requests`.
+- Disable `Projects`.
+- Disable `Wiki`.
+
+### Pull Requests
+
+- Disable `Allow merge commits`.
+- Enable `Allow squash merging`.
+- Enable `Allow rebase merging`.
+- Enable `Always suggest updating pull request branches`.
+- Enable `Allow auto-merge`.
+- Enable `Automatically delete head branches`.
+
+### Commits
+
+- Enable `Require contributors to sign off on web-based commits`.
+- Enable `Allow comments on individual commits`.
+
+## Issue Types
+
+Use GitHub issue types to classify work:
+
+- Use `Bug` for defect fixes and regressions.
+- Use `Feature` for new user-facing capabilities.
+- Use `Task` for maintenance, refactoring, documentation, tests, release work, and internal improvements.
+
+Do not duplicate issue type information in issue or pull request body sections when GitHub metadata is available.
+
+## Labels
+
+Prefer existing repository and organization labels. Use labels for workflow and review state rather than repeating information already captured by issue type.
+
+Do not create new labels unless the repository genuinely needs a reusable classification that is not already represented by existing labels or issue types.
+
+## Branches and Protection
+
+Repository protection should ensure changes to `main` are reviewed without blocking administrative maintenance.
+
+- Protect the `main` branch.
+- Require a pull request before merging into `main`.
+- Require one approval before merging into `main`.
+- Allow administrators to bypass the branch protection rules.
+- Configure required status checks selectively so auto-merge works for normal pull requests.
+- Require only stable status checks needed for safe auto-merge.
+- Do not require experimental or informational checks.
+- Do not require coverage checks unless the repository already reliably passes them.
+
+## Maintenance
+
+When maintaining an existing repository, make the smallest safe metadata or settings change needed.
+
+- Inspect the current repository settings before changing them.
+- Preserve deliberate project-specific settings.
+- Do not rename, archive, transfer, or delete a repository without explicit user approval.
+- Do not disable issues, pull requests, or required checks without explicit user approval.
+
+## GitHub CLI
+
+Use the GitHub CLI when making repository changes. Prefer explicit commands which show the target repository.
+
+Before changing repository settings, confirm the target repository with:
+
+```bash
+gh repo view OWNER/REPOSITORY
+```
+
+When a command changes repository settings, use the full `OWNER/REPOSITORY` name rather than relying on the current directory.

data/skills/socketry-pull-request/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: socketry-pull-request
+description: Prepare Socketry pull request titles, commits, and descriptions using the project conventions.
+---
+
+# Socketry Pull Request
+
+Use this skill when preparing commits or pull requests for Socketry projects.
+
+## Titles and Commits
+
+- Pull request titles must use Markdown and end with a full stop.
+- Pull request titles must be complete sentences.
+- Commit messages must use Markdown and end with a full stop.
+- The first line of a commit message must focus on what was changed.
+- Most commit messages should only be a single line.
+- Relevant context should be retained in the code itself, such as comments, rather than using the commit message as a side channel for important details.
+- Commit messages must not include agent links, attribution footers, generated-by annotations, or similar metadata.
+
+## Pull Request Description
+
+The pull request description should lead directly into a brief summary, followed by a detailed description of the problem and solution.
+
+Do not add a `Types of Changes` section to the pull request description. Use GitHub issue type metadata for classification instead.
+
+Use this structure, replacing the placeholder text with project-specific content:
+
+```markdown
+Briefly summarize the change in 1-3 sentences.
+
+Describe the problem, context, and solution. Include implementation details that help reviewers understand the change. Link relevant issues if applicable. Include screenshots for aesthetic changes.
+```
+
+## Testing
+
+Changes should include suitable test coverage. Aim for complete coverage of the behavior being changed or introduced.
+
+Do not list passing test commands or verification steps in the pull request description unless they explain an unusual risk, limitation, or manual validation requirement.
+
+### External Tests
+
+If downstream dependencies are directly affected by the change, add them as external tests when useful. See the `bake-test-external` gem for details.
+
+## Release Notes
+
+If the change is user visible, add a brief release note following the `bake-releases` documentation.
+
+## Issue Type
+
+Set the GitHub issue type correctly when creating or updating a pull request:
+
+- Use `Bug` for defect fixes and regressions.
+- Use `Feature` for new user-facing capabilities.
+- Use `Task` for maintenance, refactoring, documentation, tests, release work, and internal improvements.

metadata

@@ -1,81 +1,34 @@
 --- !ruby/object:Gem::Specification
 name: socketry
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
-- Tony Arcieri
-autorequire: 
-bindir: exe
+- Samuel Williams
+bindir: bin
 cert_chain: []
-date: 2016-11-26 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: hitimes
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.2'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.2'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-description: Socketry wraps Ruby's sockets with an advanced timeout engine which is
-  able to provide multiple simultaneous timeout behaviors in a thread-safe way.
-email:
-- bascule@gmail.com
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".rspec"
-- ".rubocop.yml"
-- ".ruby-version"
-- ".travis.yml"
-- CHANGES.md
-- Gemfile
-- Guardfile
-- LICENSE.txt
-- README.md
-- Rakefile
+- context/configuration.md
 - lib/socketry.rb
-- lib/socketry/exceptions.rb
-- lib/socketry/resolver/resolv.rb
-- lib/socketry/resolver/system.rb
-- lib/socketry/ssl/server.rb
-- lib/socketry/ssl/socket.rb
-- lib/socketry/tcp/server.rb
-- lib/socketry/tcp/socket.rb
-- lib/socketry/timeout.rb
-- lib/socketry/udp/datagram.rb
-- lib/socketry/udp/socket.rb
 - lib/socketry/version.rb
-- logo.png
-- socketry.gemspec
-homepage: https://github.com/socketry/socketry/
+- license.md
+- readme.md
+- releases.md
+- skills/socketry-github-repository/SKILL.md
+- skills/socketry-pull-request/SKILL.md
+homepage: https://github.com/socketry/socketry
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  bug_tracker_uri: https://github.com/socketry/socketry/issues
+  changelog_uri: https://github.com/socketry/socketry/blob/main/releases.md
+  funding_uri: https://github.com/sponsors/ioquatix/
+  source_code_uri: https://github.com/socketry/socketry.git
 rdoc_options: []
 require_paths:
 - lib
@@ -83,16 +36,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.2.6
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.2
-signing_key: 
+rubygems_version: 4.0.16
 specification_version: 4
-summary: High-level wrappers for Ruby sockets with advanced thread-safe timeout support
+summary: Socketry project metadata, agent context, and skills.
 test_files: []

data/.gitignore

@@ -1,9 +0,0 @@
-/.bundle/
-/.yardoc
-/Gemfile.lock
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/

data/.rspec

@@ -1,4 +0,0 @@
---color
---format=documentation
---order random
---require spec_helper

data/.rubocop.yml

@@ -1,59 +0,0 @@
-AllCops:
-  DisplayCopNames: true
-
-#
-# Style
-#
-
-LineLength:
-  Max: 128
-
-Style/AccessorMethodName:
-  Enabled: false
-
-Style/ConditionalAssignment:
-  Enabled: false
-
-Style/NumericPredicate:
-  Enabled: false
-
-Style/RescueModifier:
-  Enabled: false
-
-Style/SpaceBeforeFirstArg:
-  Enabled: false
-
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
-#
-# Metrics
-#
-
-Metrics/AbcSize:
-  Max: 50
-
-Metrics/ClassLength:
-  Max: 200
-
-Metrics/CyclomaticComplexity:
-  Max: 15
-
-Metrics/MethodLength:
-  Max: 50
-
-Metrics/ParameterLists:
-  Enabled: false
-
-Metrics/PerceivedComplexity:
-  Max: 15
-
-#
-# Lint
-#
-
-Lint/HandleExceptions:
-  Enabled: false
-
-Lint/ShadowedException:
-  Enabled: false

data/.ruby-version

@@ -1 +0,0 @@
-2.3.3

data/.travis.yml

@@ -1,16 +0,0 @@
-language: ruby
-sudo: false
-
-bundler_args: --without development doc
-
-rvm:
-  - 2.2.6
-  - 2.3.3
-  - jruby-9.1.6.0
-
-matrix:
-  fast_finish: true
-
-branches:
-  only:
-    - master