Updated documentation + minor implementation improvements.

Author: ioquatix

guides/getting-started/readme.md

@@ -14,60 +14,117 @@ $ bundle add protocol-http
 
 `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.
+  - 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.
+  - [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
 
-### Headers
+### Request
 
-{ruby Protocol::HTTP::Headers} provides semantically meaningful interpretation of header values implements case-normalising keys.
+{ruby Protocol::HTTP::Request} represents an HTTP request which can be used both server and client-side.
 
 ``` ruby
-require 'protocol/http/headers'
+require 'protocol/http/request'
 
-headers = Protocol::HTTP::Headers.new
+# Short form (recommended):
+request = Protocol::HTTP::Request["GET", "/index.html", {"accept" => "text/html"}]
 
-headers['Content-Type'] = "image/jpeg"
+# Long form:
+headers = Protocol::HTTP::Headers[["accept", "text/html"]]
+request = Protocol::HTTP::Request.new("http", "example.com", "GET", "/index.html", "HTTP/1.1", headers)
 
-headers['content-type']
-# => "image/jpeg"
+# Access request properties
+request.method           # => "GET"
+request.path             # => "/index.html"
+request.headers          # => Protocol::HTTP::Headers instance
 ```
 
-### Hypertext References
+### Response
 
-{ruby Protocol::HTTP::Reference} is used to construct "hypertext references" which consist of a path and URL-encoded key/value pairs.
+{ruby Protocol::HTTP::Response} represents an HTTP response which can be used both server and client-side.
 
 ``` ruby
-require 'protocol/http/reference'
-
-reference = Protocol::HTTP::Reference.new("/search", q: 'kittens')
-
-reference.to_s
-# => "/search?q=kittens"
+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)
 ```
 
-### URL Parsing
+### Headers
+
+{ruby Protocol::HTTP::Headers} provides semantically meaningful interpretation of header values and implements case-normalising keys.
 
-{ruby Protocol::HTTP::URL} is used to parse incoming URLs to extract the query and other relevant details.
+#### Basic Usage
 
 ``` ruby
-require 'protocol/http/url'
+require 'protocol/http/headers'
 
-reference = Protocol::HTTP::Reference.parse("/search?q=kittens")
+headers = Protocol::HTTP::Headers.new
 
-parameters = Protocol::HTTP::URL.decode(reference.query)
-# => {"q"=>"kittens"}
+# Assignment by title-case key:
+headers['Content-Type'] = "image/jpeg"
+
+# Lookup by lower-case (normalized) key:
+headers['content-type']
+# => "image/jpeg"
 ```
 
-This implementation may be merged with {ruby Protocol::HTTP::Reference} or removed in the future.
+#### 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"]
+```

guides/hypertext-references/readme.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"
+```

guides/links.yaml

@@ -1,4 +1,14 @@
 getting-started:
   order: 1
+message-body:
+  order: 2
+middleware:
+  order: 3
+hypertext-references:
+  order: 4
+url-parsing:
+  order: 5
+streaming:
+  order: 6
 design-overview:
   order: 10