protocol-http 0.51.1 → 0.52.0

data/context/message-body.md

@@ -0,0 +1,330 @@
+# Message Body
+
+This guide explains how to work with HTTP request and response message bodies using `Protocol::HTTP::Body` classes.
+
+## Overview
+
+HTTP message bodies represent the actual (often stateful) data content of requests and responses. `Protocol::HTTP` provides a rich set of body classes for different use cases, from simple string content to streaming data and file serving.
+
+All body classes inherit from {ruby Protocol::HTTP::Body::Readable}, which provides a consistent interface for reading data in chunks. Bodies can be:
+- **Buffered**: All content stored in memory.
+- **Streaming**: Content generated or read on-demand.
+- **File-based**: Content read directly from files.
+- **Transforming**: Content modified as it flows through e.g. compression, encryption.
+
+## Core Body Interface
+
+Every body implements the `Readable` interface:
+
+``` ruby
+# Read the next chunk of data:
+chunk = body.read
+# => "Hello" or nil when finished
+
+# Check if body has data available without blocking:
+body.ready?  # => true/false
+
+# Check if body is empty:
+body.empty?  # => true/false
+
+# Close the body and release resources:
+body.close
+
+# Iterate through all chunks: 
+body.each do |chunk|
+	puts chunk
+end
+
+# Read entire body into a string:
+content = body.join
+```
+
+## Buffered Bodies
+
+Use {ruby Protocol::HTTP::Body::Buffered} for content that's fully loaded in memory:
+
+``` ruby
+# Create from string:
+body = Protocol::HTTP::Body::Buffered.new(["Hello", " ", "World"])
+
+# Create from array of strings:
+chunks = ["First chunk", "Second chunk", "Third chunk"]
+body = Protocol::HTTP::Body::Buffered.new(chunks)
+
+# Wrap various types automatically:
+body = Protocol::HTTP::Body::Buffered.wrap("Simple string")
+body = Protocol::HTTP::Body::Buffered.wrap(["Array", "of", "chunks"])
+
+# Access properties:
+body.length      # => 13 (total size in bytes)
+body.empty?      # => false
+body.ready?      # => true (always ready)
+
+# Reading:
+first_chunk = body.read    # => "Hello"
+second_chunk = body.read   # => " "
+third_chunk = body.read    # => "World"
+fourth_chunk = body.read   # => nil (finished)
+
+# Rewind to beginning:
+body.rewind
+body.read  # => "Hello" (back to start)
+```
+
+### Buffered Body Features
+
+``` ruby
+# Check if rewindable:
+body.rewindable?  # => true for buffered bodies
+
+# Get all content as single string:
+content = body.join  # => "Hello World"
+
+# Convert to array of chunks:
+chunks = body.to_a   # => ["Hello", " ", "World"]
+
+# Write additional chunks:
+body.write("!")
+body.join  # => "Hello World!"
+
+# Clear all content:
+body.clear
+body.empty?  # => true
+```
+
+## File Bodies
+
+Use {ruby Protocol::HTTP::Body::File} for serving files efficiently:
+
+``` ruby
+require 'protocol/http/body/file'
+
+# Open a file:
+body = Protocol::HTTP::Body::File.open("/path/to/file.txt")
+
+# Create from existing File object:
+file = File.open("/path/to/image.jpg", "rb")
+body = Protocol::HTTP::Body::File.new(file)
+
+# Serve partial content (ranges):
+range = 100...200  # bytes 100-199
+body = Protocol::HTTP::Body::File.new(file, range)
+
+# Properties:
+body.length      # => file size or range size
+body.empty?      # => false (unless zero-length file)
+body.ready?      # => false (may block when reading)
+
+# File bodies read in chunks automatically:
+body.each do |chunk|
+	# Process each chunk (typically 64KB)
+	puts "Read #{chunk.bytesize} bytes"
+end
+```
+
+### File Body Range Requests
+
+``` ruby
+# Serve specific byte ranges (useful for HTTP range requests):
+file = File.open("large_video.mp4", "rb")
+
+# First 1MB:
+partial_body = Protocol::HTTP::Body::File.new(file, 0...1_048_576)
+
+# Custom block size for reading:
+body = Protocol::HTTP::Body::File.new(file, block_size: 8192)  # 8KB chunks
+```
+
+## Writable Bodies
+
+Use {ruby Protocol::HTTP::Body::Writable} for dynamic content generation:
+
+``` ruby
+require 'protocol/http/body/writable'
+
+# Create a writable body:
+body = Protocol::HTTP::Body::Writable.new
+
+# Write data in another thread/fiber:
+Thread.new do
+	body.write("First chunk\n")
+	sleep 0.1
+	body.write("Second chunk\n")
+	body.write("Final chunk\n")
+	body.close_write  # Signal no more data
+end
+
+# Read from main thread:
+body.each do |chunk|
+	puts "Received: #{chunk}"
+end
+# Output:
+# Received: First chunk
+# Received: Second chunk  
+# Received: Final chunk
+```
+
+### Writable Body with Backpressure
+
+``` ruby
+# Use SizedQueue to limit buffering:
+queue = Thread::SizedQueue.new(10)  # Buffer up to 10 chunks
+body = Protocol::HTTP::Body::Writable.new(queue: queue)
+
+# Writing will block if queue is full:
+body.write("chunk 1")
+# ... write up to 10 chunks before blocking
+```
+
+## Streaming Bodies
+
+Use {ruby Protocol::HTTP::Body::Streamable} for computed content:
+
+``` ruby
+require 'protocol/http/body/streamable'
+
+# Generate content dynamically:
+body = Protocol::HTTP::Body::Streamable.new do |output|
+	10.times do |i|
+		output.write("Line #{i}\n")
+		# Could include delays, computation, database queries, etc.
+	end
+end
+
+# Content is generated as it's read:
+body.each do |chunk|
+	puts "Got: #{chunk}"
+end
+```
+
+## Stream Bodies (IO Wrapper)
+
+Use {ruby Protocol::HTTP::Body::Stream} to wrap IO-like objects:
+
+``` ruby
+require 'protocol/http/body/stream'
+
+# Wrap an IO object:
+io = StringIO.new("Hello\nWorld\nFrom\nStream")
+body = Protocol::HTTP::Body::Stream.new(io)
+
+# Read line by line:
+line1 = body.gets    # => "Hello\n"
+line2 = body.gets    # => "World\n"
+
+# Read specific amounts:
+data = body.read(5)  # => "From\n"
+
+# Read remaining data:
+rest = body.read     # => "Stream"
+```
+
+## Body Transformations
+
+### Compression Bodies
+
+``` ruby
+require 'protocol/http/body/deflate'
+require 'protocol/http/body/inflate'
+
+# Compress a body:
+original = Protocol::HTTP::Body::Buffered.new(["Hello World"])
+compressed = Protocol::HTTP::Body::Deflate.new(original)
+
+# Decompress a body:
+decompressed = Protocol::HTTP::Body::Inflate.new(compressed)
+content = decompressed.join  # => "Hello World"
+```
+
+### Wrapper Bodies
+
+Create custom body transformations:
+
+``` ruby
+require 'protocol/http/body/wrapper'
+
+class UppercaseBody < Protocol::HTTP::Body::Wrapper
+	def read
+		if chunk = super
+			chunk.upcase
+		end
+	end
+end
+
+# Use the wrapper:
+original = Protocol::HTTP::Body::Buffered.wrap("hello world")
+uppercase = UppercaseBody.new(original)
+content = uppercase.join  # => "HELLO WORLD"
+```
+
+## Life-cycle
+
+### Initialization
+
+Bodies are typically initialized with the data they need to process. For example:
+
+``` ruby
+body = Protocol::HTTP::Body::Buffered.wrap("Hello World")
+```
+
+### Reading
+
+Once initialized, bodies can be read in chunks:
+
+``` ruby
+body.each do |chunk|
+	puts "Read #{chunk.bytesize} bytes"
+end
+```
+
+### Closing
+
+It's important to close bodies when done to release resources:
+
+``` ruby
+begin
+	# ... read from the body ...
+rescue => error
+	# Ignore.
+ensure
+	# The body should always be closed:
+	body.close(error)
+end
+```
+
+## Advanced Usage
+
+### Rewindable Bodies
+
+Make any body rewindable by buffering:
+
+``` ruby
+require 'protocol/http/body/rewindable'
+
+# Wrap a non-rewindable body:
+file_body = Protocol::HTTP::Body::File.open("data.txt")
+rewindable = Protocol::HTTP::Body::Rewindable.new(file_body)
+
+# Read some data:
+first_chunk = rewindable.read
+
+# Rewind and read again:
+rewindable.rewind
+same_chunk = rewindable.read  # Same as first_chunk
+```
+
+### Head Bodies (Response without content)
+
+For HEAD requests that need content-length but no body:
+
+``` ruby
+require 'protocol/http/body/head'
+
+# Create head body from another body:
+original = Protocol::HTTP::Body::File.open("large_file.zip")
+head_body = Protocol::HTTP::Body::Head.for(original)
+
+head_body.length  # => size of original file
+head_body.read    # => nil (no actual content)
+head_body.empty?  # => true
+```

data/context/middleware.md

@@ -0,0 +1,195 @@
+# Middleware
+
+This guide explains how to build and use HTTP middleware with `Protocol::HTTP::Middleware`.
+
+## Overview
+
+The middleware interface provides a convenient wrapper for implementing HTTP middleware components that can process requests and responses. Middleware enables you to build composable HTTP applications by chaining multiple processing layers.
+
+A middleware instance generally needs to respond to two methods:
+- `call(request)` -> `response`.
+- `close()` (called when shutting down).
+
+## Basic Middleware Interface
+
+You can implement middleware without using the `Middleware` class by implementing the interface directly:
+
+``` ruby
+class SimpleMiddleware
+	def initialize(delegate)
+		@delegate = delegate
+	end
+	
+	def call(request)
+		# Process request here
+		response = @delegate.call(request)
+		# Process response here
+		return response
+	end
+	
+	def close
+		@delegate&.close
+	end
+end
+```
+
+## Using the Middleware Class
+
+The `Protocol::HTTP::Middleware` class provides a convenient base for building middleware:
+
+``` ruby
+require 'protocol/http/middleware'
+
+class LoggingMiddleware < Protocol::HTTP::Middleware
+	def call(request)
+		puts "Processing: #{request.method} #{request.path}"
+		
+		response = super  # Calls @delegate.call(request)
+		
+		puts "Response: #{response.status}"
+		return response
+	end
+end
+
+# Use with a delegate:
+app = LoggingMiddleware.new(Protocol::HTTP::Middleware::HelloWorld)
+```
+
+## Building Middleware Stacks
+
+Use `Protocol::HTTP::Middleware.build` to construct middleware stacks:
+
+``` ruby
+require 'protocol/http/middleware'
+
+app = Protocol::HTTP::Middleware.build do
+	use LoggingMiddleware
+	use CompressionMiddleware
+	run Protocol::HTTP::Middleware::HelloWorld
+end
+
+# Handle a request:
+request = Protocol::HTTP::Request["GET", "/"]
+response = app.call(request)
+```
+
+The builder works by:
+- `use` adds middleware to the stack
+- `run` specifies the final application (defaults to `NotFound`)
+- Middleware is chained in reverse order (last `use` wraps first)
+
+## Block-Based Middleware
+
+Convert a block into middleware using `Middleware.for`:
+
+``` ruby
+middleware = Protocol::HTTP::Middleware.for do |request|
+	if request.path == '/health'
+		Protocol::HTTP::Response[200, {}, ["OK"]]
+	else
+		# This would normally delegate, but this example doesn't have a delegate
+		Protocol::HTTP::Response[404]
+	end
+end
+
+request = Protocol::HTTP::Request["GET", "/health"]
+response = middleware.call(request)
+# => Response with status 200
+```
+
+## Built-in Middleware
+
+### HelloWorld
+
+Always returns "Hello World!" response:
+
+``` ruby
+app = Protocol::HTTP::Middleware::HelloWorld
+response = app.call(request)
+# => 200 "Hello World!"
+```
+
+### NotFound
+
+Always returns 404 response:
+
+``` ruby
+app = Protocol::HTTP::Middleware::NotFound  
+response = app.call(request)
+# => 404 Not Found
+```
+
+### Okay
+
+Always returns 200 response with no body:
+
+``` ruby
+app = Protocol::HTTP::Middleware::Okay
+response = app.call(request)
+# => 200 OK
+```
+
+## Real-World Middleware Examples
+
+### Authentication Middleware
+
+``` ruby
+class AuthenticationMiddleware < Protocol::HTTP::Middleware
+	def initialize(delegate, api_key: nil)
+		super(delegate)
+		@api_key = api_key
+	end
+	
+	def call(request)
+		auth_header = request.headers['authorization']
+		
+		unless auth_header == "Bearer #{@api_key}"
+			return Protocol::HTTP::Response[401, {}, ["Unauthorized"]]
+		end
+		
+		super
+	end
+end
+
+# Usage:
+app = Protocol::HTTP::Middleware.build do
+	use AuthenticationMiddleware, api_key: "secret123"
+	run MyApplication
+end
+```
+
+### Content Type Middleware
+
+``` ruby
+class ContentTypeMiddleware < Protocol::HTTP::Middleware
+	def call(request)
+		response = super
+		
+		# Add content-type header if not present
+		unless response.headers.include?('content-type')
+			response.headers['content-type'] = 'text/plain'
+		end
+		
+		response
+	end
+end
+```
+
+## Testing Middleware
+
+``` ruby
+describe MyMiddleware do
+	let(:app) {MyMiddleware.new(Protocol::HTTP::Middleware::Okay)}
+	
+	it "processes requests correctly" do
+		request = Protocol::HTTP::Request["GET", "/test"]
+		response = app.call(request)
+		
+		expect(response.status).to be == 200
+	end
+	
+	it "closes properly" do
+		expect { app.close }.not.to raise_exception
+	end
+end
+```

data/context/streaming.md

@@ -0,0 +1,132 @@
+# Streaming
+
+This guide gives an overview of how to implement streaming requests and responses.
+
+## Independent Uni-directional Streaming
+
+The request and response body work independently of each other can stream data in both directions. {ruby Protocol::HTTP::Body::Stream} provides an interface to merge these independent streams into an IO-like interface.
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'async'
+require 'async/http/client'
+require 'async/http/server'
+require 'async/http/endpoint'
+
+require 'protocol/http/body/stream'
+require 'protocol/http/body/writable'
+
+endpoint = Async::HTTP::Endpoint.parse('http://localhost:3000')
+
+Async do
+	server = Async::HTTP::Server.for(endpoint) do |request|
+		output = Protocol::HTTP::Body::Writable.new
+		stream = Protocol::HTTP::Body::Stream.new(request.body, output)
+		
+		Async do
+			# Simple echo server:
+			while chunk = stream.readpartial(1024)
+				stream.write(chunk)
+			end
+		rescue EOFError
+			# Ignore EOF errors.
+		ensure
+			stream.close
+		end
+		
+		Protocol::HTTP::Response[200, {}, output]
+	end
+	
+	server_task = Async{server.run}
+	
+	client = Async::HTTP::Client.new(endpoint)
+	
+	input = Protocol::HTTP::Body::Writable.new
+	response = client.get("/", body: input)
+	
+	begin
+		stream = Protocol::HTTP::Body::Stream.new(response.body, input)
+		
+		stream.write("Hello, ")
+		stream.write("World!")
+		stream.close_write
+		
+		while chunk = stream.readpartial(1024)
+			puts chunk
+		end
+	rescue EOFError
+		# Ignore EOF errors.
+	ensure
+		stream.close
+	end
+ensure
+	server_task.stop
+end
+```
+
+This approach works quite well, especially when the input and output bodies are independently compressed, decompressed, or chunked. However, some protocols, notably, WebSockets operate on the raw connection and don't require this level of abstraction.
+
+## Bi-directional Streaming
+
+While WebSockets can work on the above streaming interface, it's a bit more convenient to use the streaming interface directly, which gives raw access to the underlying stream where possible.
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'async'
+require 'async/http/client'
+require 'async/http/server'
+require 'async/http/endpoint'
+
+require 'protocol/http/body/stream'
+require 'protocol/http/body/writable'
+
+endpoint = Async::HTTP::Endpoint.parse('http://localhost:3000')
+
+Async do
+	server = Async::HTTP::Server.for(endpoint) do |request|
+		streamable = Protocol::HTTP::Body::Streamable.
+		output = Protocol::HTTP::Body::Writable.new
+		stream = Protocol::HTTP::Body::Stream.new(request.body, output)
+		
+		Async do
+			# Simple echo server:
+			while chunk = stream.readpartial(1024)
+				stream.write(chunk)
+			end
+		rescue EOFError
+			# Ignore EOF errors.
+		ensure
+			stream.close
+		end
+		
+		Protocol::HTTP::Response[200, {}, output]
+	end
+	
+	server_task = Async{server.run}
+	
+	client = Async::HTTP::Client.new(endpoint)
+	
+	input = Protocol::HTTP::Body::Writable.new
+	response = client.get("/", body: input)
+	
+	begin
+		stream = Protocol::HTTP::Body::Stream.new(response.body, input)
+		
+		stream.write("Hello, ")
+		stream.write("World!")
+		stream.close_write
+		
+		while chunk = stream.readpartial(1024)
+			puts chunk
+		end
+	rescue EOFError
+		# Ignore EOF errors.
+	ensure
+		stream.close
+	end
+ensure
+	server_task.stop
+end
+```