protocol-http 0.51.1 → 0.52.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7152574d762fbdc22baa9dcd2f9d22931a2da4a9b3e0727af9580b7bebe31a1e
-  data.tar.gz: 8a704017b5e0897741233497d779a40eba812357238105bef7910090c08cf7a3
+  metadata.gz: 9e1927ee19fba11fbeb421268490fabcde86d7ef9ca5d472320b9aaad6763892
+  data.tar.gz: fe4c304a05ce7c3637ad460e976dbbf114c22dfb49fe425f9a2dbde1cf280d35
 SHA512:
-  metadata.gz: 7bd538f9a03da7137f2f58c77777859b5a2b6b14bef08f055104427d9c029d4bc75912dcd10f8e385680c127439c78e6980436ee9200656f0a41b8d2342de0e8
-  data.tar.gz: 8a00a43b390046bba90ce8c523aa99cf5aff1a2fd1b3c6b3f480538ef9a201c2c9a6ef5646558feb649625498c95a224ef9ec1c1bfa78caa29f2b1a6128a7e55
+  metadata.gz: 97d19c21e2d67d5870077b7ae2856438a1e4314934f01bc93148f63be4db4d55ffee18f45f66ed7b0665678dd8b0deb4718cda92fd9334f198bb2fa335bb297f
+  data.tar.gz: 674bd9d94d4efacde5d42d8c02dd8876f7f8f96290a26051343103c11f6e68ae54678746bf6d034071c0bba3a5dd7263affecc8c3e86be9ec1766faefc93e50a

data/agent.md

@@ -0,0 +1,145 @@
+# Agent
+
+## Context
+
+This section provides links to documentation from installed packages. It is automatically generated and may be updated by running `bake agent:context:install`.
+
+**Important:** Before performing any code, documentation, or analysis tasks, always read and apply the full content of any relevant documentation referenced in the following sections. These context files contain authoritative standards and best practices for documentation, code style, and project-specific workflows. **Do not proceed with any actions until you have read and incorporated the guidance from relevant context files.**
+
+**Setup Instructions:** If the referenced files are not present or if dependencies have been updated, run `bake agent:context:install` to install the latest context files.
+
+### agent-context
+
+Install and manage context files from Ruby gems.
+
+#### [Getting Started](.context/agent-context/getting-started.md)
+
+This guide explains how to use `agent-context`, a tool for discovering and installing contextual information from Ruby gems to help AI agents.
+
+### async
+
+A concurrency framework for Ruby.
+
+#### [Getting Started](.context/async/getting-started.md)
+
+This guide shows how to add async to your project and run code asynchronously.
+
+#### [Scheduler](.context/async/scheduler.md)
+
+This guide gives an overview of how the scheduler is implemented.
+
+#### [Tasks](.context/async/tasks.md)
+
+This guide explains how asynchronous tasks work and how to use them.
+
+#### [Best Practices](.context/async/best-practices.md)
+
+This guide gives an overview of best practices for using Async.
+
+#### [Debugging](.context/async/debugging.md)
+
+This guide explains how to debug issues with programs that use Async.
+
+#### [Thread safety](.context/async/thread-safety.md)
+
+This guide explains thread safety in Ruby, focusing on fibers and threads, common pitfalls, and best practices to avoid problems like data corruption, race conditions, and deadlocks.
+
+### async-service
+
+A service layer for Async.
+
+#### [Getting Started](.context/async-service/getting-started.md)
+
+This guide explains how to get started with `async-service` to create and run services in Ruby.
+
+#### [Service Architecture](.context/async-service/service-architecture.md)
+
+This guide explains the key architectural components of `async-service` and how they work together to provide a clean separation of concerns.
+
+#### [Best Practices](.context/async-service/best-practices.md)
+
+This guide outlines recommended patterns and practices for building robust, maintainable services with `async-service`.
+
+### decode
+
+Code analysis for documentation generation.
+
+#### [Getting Started with Decode](.context/decode/getting-started.md)
+
+The Decode gem provides programmatic access to Ruby code structure and metadata. It can parse Ruby files and extract definitions, comments, and documentation pragmas, enabling code analysis, documentation generation, and other programmatic manipulations of Ruby codebases.
+
+#### [Documentation Coverage](.context/decode/coverage.md)
+
+This guide explains how to test and monitor documentation coverage in your Ruby projects using the Decode gem's built-in bake tasks.
+
+#### [Ruby Documentation](.context/decode/ruby-documentation.md)
+
+This guide covers documentation practices and pragmas supported by the Decode gem for documenting Ruby code. These pragmas provide structured documentation that can be parsed and used to generate API documentation and achieve complete documentation coverage.
+
+#### [Setting Up RBS Types and Steep Type Checking for Ruby Gems](.context/decode/types.md)
+
+This guide covers the process for establishing robust type checking in Ruby gems using RBS and Steep, focusing on automated generation from source documentation and proper validation.
+
+### falcon
+
+A fast, asynchronous, rack-compatible web server.
+
+#### [Getting Started](.context/falcon/getting-started.md)
+
+This guide gives an overview of how to use Falcon for running Ruby web applications.
+
+#### [Rails Integration](.context/falcon/rails-integration.md)
+
+This guide explains how to host Rails applications with Falcon.
+
+#### [Deployment](.context/falcon/deployment.md)
+
+This guide explains how to deploy applications using the Falcon web server. It covers the recommended deployment methods, configuration options, and examples for different environments, including systemd and kubernetes.
+
+#### [Performance Tuning](.context/falcon/performance-tuning.md)
+
+This guide explains the performance characteristics of Falcon.
+
+#### [WebSockets](.context/falcon/websockets.md)
+
+This guide explains how to use WebSockets with Falcon.
+
+#### [Interim Responses](.context/falcon/interim-responses.md)
+
+This guide explains how to use interim responses in Falcon to send early hints to the client.
+
+#### [How It Works](.context/falcon/how-it-works.md)
+
+This guide gives an overview of how Falcon handles an incoming web request.
+
+### sus
+
+A fast and scalable test runner.
+
+#### [Using Sus Testing Framework](.context/sus/usage.md)
+
+Sus is a modern Ruby testing framework that provides a clean, BDD-style syntax for writing tests. It's designed to be fast, simple, and expressive.
+
+#### [Mocking](.context/sus/mocking.md)
+
+There are two types of mocking in sus: `receive` and `mock`. The `receive` matcher is a subset of full mocking and is used to set expectations on method calls, while `mock` can be used to replace method implementations or set up more complex behavior.
+
+#### [Shared Test Behaviors and Fixtures](.context/sus/shared.md)
+
+Sus provides shared test contexts which can be used to define common behaviours or tests that can be reused across one or more test files.
+
+### utopia-project
+
+A project documentation tool based on Utopia.
+
+#### [Getting Started](.context/utopia-project/getting-started.md)
+
+This guide explains how to use `utopia-project` to add documentation to your project.
+
+#### [Documentation Guides](.context/utopia-project/documentation-guidelines.md)
+
+This guide explains how to create and maintain documentation for your project using `utopia-project`.
+
+#### [GitHub Pages Integration](.context/utopia-project/github-pages-integration.md)
+
+This guide shows you how to use `utopia-project` with GitHub Pages to deploy documentation.

data/context/design-overview.md

@@ -0,0 +1,209 @@
+# Design Overview
+
+This guide explains the high level design of `protocol-http` in the context of wider design patterns that can be used to implement HTTP clients and servers.
+
+## Request/Response Model
+
+The main model we support is the request/response model. A client sends a request to a server which return response. The protocol is responsible for serializing the request and response objects.
+
+```mermaid
+sequenceDiagram
+	participant CA as Application
+	participant Client
+	participant Server
+	participant SA as Application
+	CA->>+Client: Request
+	Client->>+Server: Request
+	Server->>+SA: Request
+	SA->>+Server: Response
+	Server->>+Client: Response
+	Client->>+CA: Response
+```
+
+We provide an interface for request and response objects. This provides performance, predictability and robustness. This model has proven itself over several years, handling a variety of different use cases.
+
+~~~ ruby
+class Request
+	attr :method
+	attr :target
+	attr :headers
+	attr :body
+end
+
+class Response
+	attr :status
+	attr :headers
+	attr :body
+end
+~~~
+
+One other advantage is that it's symmetrical between clients and servers with a clear mapping, i.e. the protocol is responsible for transiting requests from the client to the server, and responses from the server back to the client. This helps us separate and define request/response interfaces independently from protocol implementation.
+
+### Client Design
+
+A request/response model implies that you create a request and receive a response back. This maps to a normal function call where the request is the argument and the response is the returned value.
+
+~~~ ruby
+request = Request.new("GET", url)
+response = client.call(request)
+
+response.headers
+response.read
+~~~
+
+## Stream Model
+
+An alternative model is the stream model. This model is more suitable for WebSockets and other persistent bi-directional channels.
+
+```mermaid
+sequenceDiagram
+	participant CA as Application
+	participant Client
+	participant Server
+	participant SA as Application
+	CA->>+Client: Stream
+	Client->>+Server: Stream
+	Server->>+SA: Stream
+```
+
+The interfaces for streaming can be implemented a bit differently, since a response is not returned but rather assigned to the stream, and the streaming occurs in the same execution context as the client or server handling the request.
+
+~~~ ruby
+class Stream
+	# Request details.
+	attr :method
+	attr :target
+	attr :headers
+	
+	attr :response
+	
+	# Write the response and start streaming the output body.
+	def respond(status, headers)
+		response.status = status
+		response.headers = headers
+	end
+	
+	# Request body.
+	attr_accessor :input
+	
+	# Response body.
+	attr_accessor :output
+	
+	# Write to the response body.
+	def write(...)
+		@output.write(...)
+	end
+	
+	# Read from the request body.
+	def read
+		@input.read
+	end
+end
+
+class Response
+	def initialize(method, target)
+		@input = Body::Writable.new
+		@output = Body::Writable.new
+	end
+	
+	attr_accessor :status
+	attr_accessor :headers
+	
+	# Prepare a stream for making a request.
+	def request(method, target, headers)
+		# Create a request stream suitable for writing into the buffered response:
+		Stream.new(method, target, headers, self, @input, @output)
+	end
+	
+	# Write to the request body.
+	def write(...)
+		@input.write(...)
+	end
+	
+	# Read from the response body.
+	def read
+		@output.read
+	end
+end
+~~~
+
+### Client Design
+
+A stream model implies that you create a stream which contains both the request and response bodies. This maps to a normal function call where the argument is the stream and the returned value is ignored.
+
+~~~ ruby
+response = Response.new
+stream = response.request("GET", url)
+
+client.call(stream)
+
+response.headers
+response.read
+~~~
+
+## Differences
+
+The request/response model has a symmetrical design which naturally uses the return value for the result of executing the request. The result encapsulates the behaviour of how to read the response status, headers and body. Because of that, streaming input and output becomes a function of the result object itself. As in:
+
+~~~ ruby
+def call(request)
+	body = Body::Writable.new
+	
+	Fiber.schedule do
+		while chunk = request.input.read
+			body.write(chunk.reverse)
+		end
+	end
+	
+	return Response[200, headers, body]
+end
+
+input = Body::Writable.new
+response = call(... body ...)
+
+input.write("Hello World")
+input.close
+response.read -> "dlroW olleH"
+~~~
+
+The streaming model does not have the same symmetry, and instead opts for a uni-directional flow of information.
+
+~~~ruby
+def call(stream)
+	stream.respond(200, headers)
+	
+	Fiber.schedule do
+		while chunk = stream.read
+			stream.write(chunk.reverse)
+		end
+	end
+end
+
+input = Body::Writable.new
+response = Response.new(...input...)
+call(response.stream)
+
+input.write("Hello World")
+input.close
+response.read -> "dlroW olleH"
+~~~
+
+The value of this uni-directional flow is that it is natural for the stream to be taken out of the scope imposed by the nested `call(request)` model. However, the user must explicitly close the stream, since it's no longer scoped to the client and/or server.
+
+## Interim Response Handling
+
+Interim responses are responses that are sent before the final response. They are used for things like `103 Early Hints` and `100 Continue`. These responses are sent before the final response, and are used to signal to the client that the server is still processing the request.
+
+```ruby
+body = Body::Writable.new
+
+interim_response_callback = proc do |status, headers|
+	if status == 100
+		# Continue sending the request body.
+		body.write("Hello World")
+		body.close
+	end
+end
+
+response = client.post("/upload", {'expect' => '100-continue'}, body, interim_response: interim_response_callback)
+```

data/context/getting-started.md

@@ -0,0 +1,130 @@
+# Getting Started
+
+This guide explains how to use `protocol-http` for building abstract HTTP interfaces.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add protocol-http
+~~~
+
+## Core Concepts
+
+`protocol-http` has several core concepts:
+
+  - A {ruby Protocol::HTTP::Request} instance which represents an abstract HTTP request. Specific versions of HTTP may subclass this to track additional state.
+  - A {ruby Protocol::HTTP::Response} instance which represents an abstract HTTP response. Specific versions of HTTP may subclass this to track additional state.
+  - A {ruby Protocol::HTTP::Middleware} interface for building HTTP applications.
+  - A {ruby Protocol::HTTP::Headers} interface for storing HTTP headers with semantics based on documented specifications (RFCs, etc).
+  - A set of {ruby Protocol::HTTP::Body} classes which handle the internal request and response bodies, including bi-directional streaming.
+
+## Integration
+
+This gem does not provide any specific client or server implementation, rather it's used by several other gems.
+
+  - [Protocol::HTTP1](https://github.com/socketry/protocol-http1) & [Protocol::HTTP2](https://github.com/socketry/protocol-http2) which provide client and server implementations.
+  - [Async::HTTP](https://github.com/socketry/async-http) which provides connection pooling and concurrency.
+
+## Usage
+
+### Request
+
+{ruby Protocol::HTTP::Request} represents an HTTP request which can be used both server and client-side.
+
+``` ruby
+require 'protocol/http/request'
+
+# Short form (recommended):
+request = Protocol::HTTP::Request["GET", "/index.html", {"accept" => "text/html"}]
+
+# Long form:
+headers = Protocol::HTTP::Headers[["accept", "text/html"]]
+request = Protocol::HTTP::Request.new("http", "example.com", "GET", "/index.html", "HTTP/1.1", headers)
+
+# Access request properties
+request.method           # => "GET"
+request.path             # => "/index.html"
+request.headers          # => Protocol::HTTP::Headers instance
+```
+
+### Response
+
+{ruby Protocol::HTTP::Response} represents an HTTP response which can be used both server and client-side.
+
+``` ruby
+require 'protocol/http/response'
+
+# Short form (recommended):
+response = Protocol::HTTP::Response[200, {"content-type" => "text/html"}, "Hello, World!"]
+
+# Long form:
+headers = Protocol::HTTP::Headers["content-type" => "text/html"]
+body = Protocol::HTTP::Body::Buffered.wrap("Hello, World!")
+response = Protocol::HTTP::Response.new("HTTP/1.1", 200, headers, body)
+
+# Access response properties
+response.status          # => 200
+response.headers         # => Protocol::HTTP::Headers instance
+response.body            # => Body instance
+
+# Status checking methods
+response.success?        # => true (200-299)
+response.ok?             # => true (200)
+response.redirection?    # => false (300-399)
+response.failure?        # => false (400-599)
+```
+
+### Headers
+
+{ruby Protocol::HTTP::Headers} provides semantically meaningful interpretation of header values and implements case-normalising keys.
+
+#### Basic Usage
+
+``` ruby
+require 'protocol/http/headers'
+
+headers = Protocol::HTTP::Headers.new
+
+# Assignment by title-case key:
+headers['Content-Type'] = "image/jpeg"
+
+# Lookup by lower-case (normalized) key:
+headers['content-type']
+# => "image/jpeg"
+```
+
+#### Semantic Processing
+
+Many headers receive special semantic processing, automatically splitting comma-separated values and providing structured access:
+
+``` ruby
+# Accept header with quality values:
+headers['Accept'] = 'text/html, application/json;q=0.8, */*;q=0.1'
+accept = headers['accept']
+# => ["text/html", "application/json;q=0.8", "*/*;q=0.1"]
+
+# Access parsed media ranges with quality factors:
+accept.media_ranges.each do |range|
+	puts "#{range.type}/#{range.subtype} (q=#{range.quality_factor})"
+end
+# text/html (q=1.0)
+# application/json (q=0.8)
+# */* (q=0.1)
+
+# Accept-Encoding automatically splits values:
+headers['Accept-Encoding'] = 'gzip, deflate, br;q=0.9'
+headers['accept-encoding']
+# => ["gzip", "deflate", "br;q=0.9"]
+
+# Cache-Control splits directives:
+headers['Cache-Control'] = 'max-age=3600, no-cache, must-revalidate'
+headers['cache-control']
+# => ["max-age=3600", "no-cache", "must-revalidate"]
+
+# Vary header normalizes field names to lowercase:
+headers['Vary'] = 'Accept-Encoding, User-Agent'
+headers['vary']
+# => ["accept-encoding", "user-agent"]
+```

data/context/hypertext-references.md

@@ -0,0 +1,140 @@
+# Hypertext References
+
+This guide explains how to use `Protocol::HTTP::Reference` for constructing and manipulating hypertext references (URLs with parameters).
+
+## Overview
+
+{ruby Protocol::HTTP::Reference} is used to construct "hypertext references" which consist of a path and URL-encoded parameters. References provide a rich API for URL construction, path manipulation, and parameter handling.
+
+## Basic Construction
+
+``` ruby
+require 'protocol/http/reference'
+
+# Simple reference with parameters:
+reference = Protocol::HTTP::Reference.new("/search", nil, nil, {q: 'kittens', limit: 10})
+reference.to_s
+# => "/search?q=kittens&limit=10"
+
+# Parse existing URLs:
+reference = Protocol::HTTP::Reference.parse("/api/users?page=2&sort=name#results")
+reference.path       # => "/api/users"
+reference.query      # => "page=2&sort=name"
+reference.fragment   # => "results"
+
+# To get parameters as a hash, decode the query string:
+parameters = Protocol::HTTP::URL.decode(reference.query)
+parameters           # => {"page" => "2", "sort" => "name"}
+```
+
+## Path Manipulation
+
+References support sophisticated path manipulation including relative path resolution:
+
+``` ruby
+base = Protocol::HTTP::Reference.new("/api/v1/users")
+
+# Append paths:
+user_detail = base.with(path: "123")
+user_detail.to_s  # => "/api/v1/users/123"
+
+# Relative path navigation:
+parent = user_detail.with(path: "../groups", pop: true)
+parent.to_s  # => "/api/v1/groups"
+
+# Absolute path replacement:
+root = user_detail.with(path: "/status")
+root.to_s  # => "/status"
+```
+
+## Advanced Parameter Handling
+
+``` ruby
+# Complex parameter structures:
+reference = Protocol::HTTP::Reference.new("/search", nil, nil, {
+	filters: {
+		category: "books", 
+		price: {min: 10, max: 50}
+	},
+	tags: ["fiction", "mystery"]
+})
+
+reference.to_s
+# => "/search?filters[category]=books&filters[price][min]=10&filters[price][max]=50&tags[]=fiction&tags[]=mystery"
+
+# Parameter merging:
+base = Protocol::HTTP::Reference.new("/api", nil, nil, {version: "v1", format: "json"})
+extended = base.with(parameters: {detailed: true}, merge: true)
+extended.to_s
+# => "/api?version=v1&format=json&detailed=true"
+
+# Parameter replacement (using merge: false):
+replaced = base.with(parameters: {format: "xml"}, merge: false)
+replaced.to_s
+# => "/api?format=xml"
+```
+
+## Merge Behavior and Query Strings
+
+The `merge` parameter controls both parameter handling and query string behavior:
+
+``` ruby
+# Create a reference with both query string and parameters:
+ref = Protocol::HTTP::Reference.new("/api", "existing=query", nil, {version: "v1"})
+ref.to_s
+# => "/api?existing=query&version=v1"
+
+# merge: true (default) - keeps existing query string:
+merged = ref.with(parameters: {new: "argument"}, merge: true)
+merged.to_s
+# => "/api?existing=query&version=v1&new=argument"
+
+# merge: false with new parameters - clears query string:
+replaced = ref.with(parameters: {new: "argument"}, merge: false)
+replaced.to_s
+# => "/api?new=argument"
+
+# merge: false without new parameters - keeps everything:
+unchanged = ref.with(path: "v2", merge: false)
+unchanged.to_s
+# => "/api/v2?existing=query&version=v1"
+```
+
+## URL Encoding and Special Characters
+
+References handle URL encoding automatically:
+
+``` ruby
+# Spaces and special characters:
+reference = Protocol::HTTP::Reference.new("/search", nil, nil, {
+	q: "hello world",
+	filter: "price > $10"
+})
+reference.to_s
+# => "/search?q=hello%20world&filter=price%20%3E%20%2410"
+
+# Unicode support:
+unicode_ref = Protocol::HTTP::Reference.new("/files", nil, nil, {
+	name: "résumé.pdf",
+	emoji: "😀"
+})
+unicode_ref.to_s
+# => "/files?name=r%C3%A9sum%C3%A9.pdf&emoji=%F0%9F%98%80"
+```
+
+## Reference Merging
+
+References can be merged following RFC2396 URI resolution rules:
+
+``` ruby
+base = Protocol::HTTP::Reference.new("/docs/guide/")
+relative = Protocol::HTTP::Reference.new("../api/reference.html")
+
+merged = base + relative
+merged.to_s  # => "/docs/api/reference.html"
+
+# Absolute references override completely
+absolute = Protocol::HTTP::Reference.new("/completely/different/path")
+result = base + absolute
+result.to_s  # => "/completely/different/path"
+```

data/context/index.yaml

@@ -0,0 +1,36 @@
+# 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 abstractions to handle HTTP protocols.
+metadata:
+  documentation_uri: https://socketry.github.io/protocol-http/
+  source_code_uri: https://github.com/socketry/protocol-http.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `protocol-http` for building abstract
+    HTTP interfaces.
+- path: message-body.md
+  title: Message Body
+  description: This guide explains how to work with HTTP request and response message
+    bodies using `Protocol::HTTP::Body` classes.
+- path: middleware.md
+  title: Middleware
+  description: This guide explains how to build and use HTTP middleware with `Protocol::HTTP::Middleware`.
+- path: hypertext-references.md
+  title: Hypertext References
+  description: This guide explains how to use `Protocol::HTTP::Reference` for constructing
+    and manipulating hypertext references (URLs with parameters).
+- path: url-parsing.md
+  title: URL Parsing
+  description: This guide explains how to use `Protocol::HTTP::URL` for parsing and
+    manipulating URL components, particularly query strings and parameters.
+- path: streaming.md
+  title: Streaming
+  description: This guide gives an overview of how to implement streaming requests
+    and responses.
+- path: design-overview.md
+  title: Design Overview
+  description: This guide explains the high level design of `protocol-http` in the
+    context of wider design patterns that can be used to implement HTTP clients and
+    servers.