Modernize code.

ioquatix · ioquatix · commit 0a3363e6122f · 2025-10-23T22:45:38.000+13:00
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -0,0 +1,20 @@
+# GitHub Copilot Instructions
+
+## Use Agent Context
+
+When working on this project, consult the `agents.md` file for project-specific guidelines, architecture decisions, and development patterns. This file contains curated information that will help you make better decisions aligned with the project's goals and standards.
+
+If the file does not exist, you will need to install it, by running the following command:
+
+```bash
+$ bundle install
+$ bundle exec bake agent:context:install
+```
+
+This command will set up the necessary context files that help you understand the project structure, dependencies, and conventions.
+
+## Ignoring Files
+
+The `.gitignore` file is split into two sections, separated by a blank line. The first section is automatically generated, while the second section is user controlled.
+
+While working on pull requests, you should not add unrelated changes to the `.gitignore` file as part of the pull request.
diff --git a/.github/workflows/documentation-coverage.yaml b/.github/workflows/documentation-coverage.yaml
@@ -6,7 +6,6 @@ permissions:
   contents: read
 
 env:
-  CONSOLE_OUTPUT: XTerm
   COVERAGE: PartialSummary
 
 jobs:
@@ -17,7 +16,7 @@ jobs:
     - uses: actions/checkout@v4
     - uses: ruby/setup-ruby@v1
       with:
-        ruby-version: "3.4"
+        ruby-version: ruby
         bundler-cache: true
     
     - name: Validate coverage
diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml
@@ -17,7 +17,6 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  CONSOLE_OUTPUT: XTerm
   BUNDLE_WITH: maintenance
 
 jobs:
@@ -29,7 +28,7 @@ jobs:
 
     - uses: ruby/setup-ruby@v1
       with:
-        ruby-version: "3.4"
+        ruby-version: ruby
         bundler-cache: true
     
     - name: Installing packages
diff --git a/.github/workflows/rubocop.yaml b/.github/workflows/rubocop.yaml
@@ -5,9 +5,6 @@ on: [push, pull_request]
 permissions:
   contents: read
 
-env:
-  CONSOLE_OUTPUT: XTerm
-
 jobs:
   check:
     runs-on: ubuntu-latest
diff --git a/.github/workflows/test-coverage.yaml b/.github/workflows/test-coverage.yaml
@@ -6,7 +6,6 @@ permissions:
   contents: read
 
 env:
-  CONSOLE_OUTPUT: XTerm
   COVERAGE: PartialSummary
 
 jobs:
@@ -21,7 +20,7 @@ jobs:
           - macos
         
         ruby:
-          - "3.4"
+          - ruby
     
     steps:
     - uses: actions/checkout@v4
@@ -49,7 +48,7 @@ jobs:
     - uses: actions/checkout@v4
     - uses: ruby/setup-ruby@v1
       with:
-        ruby-version: "3.4"
+        ruby-version: ruby
         bundler-cache: true
     
     - uses: actions/download-artifact@v4
diff --git a/.github/workflows/test-external.yaml b/.github/workflows/test-external.yaml
@@ -5,9 +5,6 @@ on: [push, pull_request]
 permissions:
   contents: read
 
-env:
-  CONSOLE_OUTPUT: XTerm
-
 jobs:
   test:
     name: ${{matrix.ruby}} on ${{matrix.os}}
diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -5,9 +5,6 @@ on: [push, pull_request]
 permissions:
   contents: read
 
-env:
-  CONSOLE_OUTPUT: XTerm
-
 jobs:
   test:
     name: ${{matrix.ruby}} on ${{matrix.os}}
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,7 @@
-/.bundle/
-/pkg/
+/agents.md
+/.context
+/.bundle
+/pkg
 /gems.locked
 /.covered.db
 /external
diff --git a/.rubocop.yml b/.rubocop.yml
@@ -1,6 +1,13 @@
+plugins:
+  - rubocop-md
+  - rubocop-socketry
+
 AllCops:
   DisabledByDefault: true
 
+Layout/ConsistentBlankLineIndentation:
+  Enabled: true
+
 Layout/IndentationStyle:
   Enabled: true
   EnforcedStyle: tabs
@@ -27,6 +34,9 @@ Layout/BeginEndAlignment:
   Enabled: true
   EnforcedStyleAlignWith: start_of_line
 
+Layout/RescueEnsureAlignment:
+  Enabled: true
+
 Layout/ElseAlignment:
   Enabled: true
 
@@ -35,10 +45,14 @@ Layout/DefEndAlignment:
 
 Layout/CaseIndentation:
   Enabled: true
+  EnforcedStyle: end
 
 Layout/CommentIndentation:
   Enabled: true
 
+Layout/FirstHashElementIndentation:
+  Enabled: true
+
 Layout/EmptyLinesAroundClassBody:
   Enabled: true
 
@@ -48,6 +62,15 @@ Layout/EmptyLinesAroundModuleBody:
 Layout/EmptyLineAfterMagicComment:
    Enabled: true
 
+Layout/SpaceInsideBlockBraces:
+  Enabled: true
+  EnforcedStyle: no_space
+  SpaceBeforeBlockParameters: false
+
+Layout/SpaceAroundBlockParameters:
+  Enabled: true
+  EnforcedStyleInsidePipes: no_space
+
 Style/FrozenStringLiteralComment:
   Enabled: true
 
diff --git a/async-rest.gemspec b/async-rest.gemspec
@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
 		"source_code_uri" => "https://github.com/socketry/async-rest.git",
 	}
 	
-	spec.files = Dir.glob(["{lib}/**/*", "*.md"], File::FNM_DOTMATCH, base: __dir__)
+	spec.files = Dir.glob(["{context,lib}/**/*", "*.md"], File::FNM_DOTMATCH, base: __dir__)
 	
 	spec.required_ruby_version = ">= 3.2"
 	
diff --git a/bake.rb b/bake.rb
@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+# Update the project documentation with the new version number.
+#
+# @parameter version [String] The new version number.
+def after_gem_release_version_increment(version)
+	context["releases:update"].call(version)
+	context["utopia:project:update"].call
+end
diff --git a/context/getting-started.md b/context/getting-started.md
@@ -0,0 +1,61 @@
+# Getting Started
+
+This guide explains the design of the `async-rest` gem and how to use it to access RESTful APIs.
+
+## Installation
+
+Add the gem to your project:
+
+``` shell
+$ bundle add async-rest
+```
+
+## Core Concepts
+
+The `async-rest` gem has two core concepts:
+
+- A {ruby Async::REST::Resource} instance represents a specific resource and a delegate (HTTP connection) for accessing that resource.
+- A {ruby Async::REST::Representation} instance represents a specific representation of a resource - usually a specific request to a URL that returns a response with a given content type.
+
+Just as a webpage has hyperlinks, forms and buttons for connecting information and performing actions, a representation may also carry associated links to actions that can be performed on a resource. However, many services define a fixed set of actions that can be performed on a given resource using a schema. As such, the `async-rest` gem does not have a standard mechanism for discovering actions on a resource at runtime (or follow a design that requires this).
+
+## Usage
+
+Generally speaking, you should model your interface around representations. Each representation should be a subclass of {ruby Async::REST::Representation} and define methods that represent the actions that can be performed on that resource.
+
+```ruby
+require "async/rest"
+
+module DNS
+	class Query < Async::REST::Representation[Async::REST::Wrapper::JSON]
+		def question
+			value[:Question]
+		end
+		
+		def answer
+			value[:Answer]
+		end
+	end
+	
+	class Client < Async::REST::Resource
+		# This is the default endpoint to use unless otherwise specified:
+		ENDPOINT = Async::HTTP::Endpoint.parse("https://dns.google/resolve")
+		
+		# Resolve a DNS query.
+		def resolve(name, type)
+			Query.get(self.with(parameters: { name: name, type: type }))
+		end
+	end
+end
+
+DNS::Client.open do |client|
+	query = client.resolve("example.com", "AAAA")
+	
+	puts query.question
+	# {:name=>"example.com.", :type=>28}
+	puts query.answer
+	# {:name=>"example.com.", :type=>28, :TTL=>13108, :data=>"2606:2800:220:1:248:1893:25c8:1946"}
+end
+```
+
+It should be noted that the above client is not a representation, but a resource. That is because `https://dns.google.com/resolve` is a fixed endpoint that does not have a schema for discovering actions at runtime. The `resolve` method is a convenience method that creates a new representation and performs a GET request to the endpoint.
diff --git a/context/index.yaml b/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: A library for RESTful clients (and hopefully servers).
+metadata:
+  documentation_uri: https://socketry.github.io/async-rest/
+  source_code_uri: https://github.com/socketry/async-rest.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains the design of the `async-rest` gem and how to use
+    it to access RESTful APIs.
diff --git a/examples/slack/clean.rb b/examples/slack/clean.rb
@@ -39,13 +39,13 @@ def rate_limited?(response)
 			channel_id = message[:channel][:id]
 			channel_name = message[:channel][:name]
 			timestamp = message[:ts]
-		
+			
 			pp [timestamp, channel_name, text]
-		
+			
 			message_delete = Async::REST::Representation.new(
 				delete.with(parameters: {channel: channel_id, ts: timestamp})
 			)
-		
+			
 			response = message_delete.post
 			if rate_limited?(response.read)
 				puts "Rate limiting..."
diff --git a/fixtures/async/rest/a_wrapper.rb b/fixtures/async/rest/a_wrapper.rb
@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require "sus/fixtures/async/http/server_context"
 
diff --git a/gems.rb b/gems.rb
@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 
 source "https://rubygems.org"
 
@@ -10,6 +10,9 @@
 group :maintenance, optional: true do
 	gem "bake-modernize"
 	gem "bake-gem"
+	gem "bake-releases"
+	
+	gem "agent-context"
 	
 	gem "utopia-project"
 end
@@ -18,7 +21,10 @@
 	gem "sus"
 	gem "covered"
 	gem "decode"
+	
 	gem "rubocop"
+	gem "rubocop-md"
+	gem "rubocop-socketry"
 	
 	gem "sus-fixtures-async-http"
 	
diff --git a/guides/getting-started/readme.md b/guides/getting-started/readme.md
@@ -24,7 +24,7 @@ Just as a webpage has hyperlinks, forms and buttons for connecting information a
 Generally speaking, you should model your interface around representations. Each representation should be a subclass of {ruby Async::REST::Representation} and define methods that represent the actions that can be performed on that resource.
 
 ```ruby
-require 'async/rest'
+require "async/rest"
 
 module DNS
 	class Query < Async::REST::Representation[Async::REST::Wrapper::JSON]
@@ -39,7 +39,7 @@ module DNS
 	
 	class Client < Async::REST::Resource
 		# This is the default endpoint to use unless otherwise specified:
-		ENDPOINT = Async::HTTP::Endpoint.parse('https://dns.google/resolve')
+		ENDPOINT = Async::HTTP::Endpoint.parse("https://dns.google/resolve")
 		
 		# Resolve a DNS query.
 		def resolve(name, type)
@@ -49,7 +49,7 @@ module DNS
 end
 
 DNS::Client.open do |client|
-	query = client.resolve('example.com', 'AAAA')
+	query = client.resolve("example.com", "AAAA")
 	
 	puts query.question
 	# {:name=>"example.com.", :type=>28}
diff --git a/lib/async/rest/resource.rb b/lib/async/rest/resource.rb
@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 
 require "async"
 require "async/http/client"
diff --git a/lib/async/rest/wrapper/form.rb b/lib/async/rest/wrapper/form.rb
@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 # Copyright, 2025, by Ayush Newatia.
 
 require_relative "json"
diff --git a/lib/async/rest/wrapper/url_encoded.rb b/lib/async/rest/wrapper/url_encoded.rb
@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require "json"
 
diff --git a/readme.md b/readme.md
diff --git a/releases.md b/releases.md
diff --git a/test/async/rest/wrapper/generic.rb b/test/async/rest/wrapper/generic.rb

Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,7 @@ Gem::Specification.new do \|spec\|`
`20`	`20`	`"source_code_uri" => "https://github.com/socketry/async-rest.git",`
`21`	`21`	`}`
`22`	`22`
`23`		`- spec.files = Dir.glob(["{lib}/*/", "*.md"], File::FNM_DOTMATCH, base: __dir__)`
	`23`	`+ spec.files = Dir.glob(["{context,lib}/*/", "*.md"], File::FNM_DOTMATCH, base: __dir__)`
`24`	`24`
`25`	`25`	`spec.required_ruby_version = ">= 3.2"`
`26`	`26`