h2o

A high-performance HTTP/2 client for Crystal with full protocol compliance, connection pooling, and advanced features like HPACK compression and stream multiplexing. Optimized for production use with comprehensive CI testing.

Development Attribution

This project was developed heavily with the assistance of Claude Opus and Claude Sonnet 4. The codebase is largely (99%) generated by Claude Code through extensive collaboration, careful prompting, and iterative validation.

Important Notice: While this library is actively used in production environments and has been tested against multiple APIs and HTTP/2 endpoints, it should be considered experimental. This code represents the result of extensive AI-assisted development with careful validation and testing, but was not written by an expert in the HTTP/2 protocol or the Crystal programming language.

All functionality included in this library, including the Circuit Breaker and Circuit Breaker Persistence Adapters, are currently in use in production environments but should be considered somewhat experimental. Users should thoroughly test and validate the library for their specific use cases before production deployment.

Features

• 🚀 Full HTTP/2 Support: Complete implementation of RFC 7540
• 🔐 TLS with ALPN: Automatic HTTP/2 negotiation via TLS ALPN
• 🗜️ HPACK Compression: RFC 7541 compliant header compression
• 🔀 Stream Multiplexing: Concurrent request handling over single connection
• 🏊 Connection Pooling: Efficient connection reuse and management
• 📊 Flow Control: Both connection and stream-level flow control
• ⚡ High Performance: Optimized for speed and low memory usage
• 🧪 Comprehensive Tests: Full test coverage with integration tests
• 🔄 Circuit Breaker: Built-in circuit breaker pattern for resilience

H2SPEC Compliance

h2o demonstrates 100% compliance with the HTTP/2 specification through comprehensive native testing:

For detailed test documentation and implementation details, see:

• H2SPEC Compliance Documentation - Complete test coverage and methodology
• Native Test Implementation - Crystal-native H2SPEC compliance tests with RFC section mapping

Installation

Add this to your application's shard.yml:

dependencies:
  h2o:
    github: nomadlabsinc/h2o
    branch: main

Then run:

shards install

Quick Start

require "h2o"

# Create a client
client = H2O::Client.new

# Make a simple GET request
response = client.get("https://httpbin.org/get")
puts response.status  # => 200
puts response.body    # => JSON response

# Make a POST request with body
headers = H2O::Headers.new
headers["content-type"] = "application/json"
body = %q({"key": "value"})

response = client.post("https://httpbin.org/post", body, headers)
puts response.status  # => 200

# Clean up
client.close

Basic Usage

Connection Pooling

client = H2O::Client.new(connection_pool_size: 20)

Request Timeouts

client = H2O::Client.new(timeout: 10.seconds)

Custom Headers

headers = H2O::Headers.new
headers["authorization"] = "Bearer your-token"
response = client.get("https://api.example.com/protected", headers)

HTTP Methods

client = H2O::Client.new

response = client.get("https://api.example.com/users")
response = client.post("https://api.example.com/users", body)
response = client.put("https://api.example.com/users/1", body)
response = client.delete("https://api.example.com/users/1")
response = client.head("https://api.example.com/users")
response = client.options("https://api.example.com/users")
response = client.patch("https://api.example.com/users/1", body)

Advanced Features

For detailed documentation on advanced features, see:

• Circuit Breaker Documentation - Resilience patterns, failure handling, and monitoring
• API Reference - Complete API documentation and usage patterns
• Integration Guide - Advanced integration and configuration examples

Contributing

1. Fork it (https://github.com/nomadlabsinc/h2o/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Please ensure all tests pass and code is properly formatted before submitting.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Authors

• Nomad Labs Inc. - creator and maintainer

Acknowledgments

• Crystal Language Team for the excellent language and standard library
• HTTP/2 specification authors (RFC 7540, RFC 7541)
• The Crystal community for inspiration and best practices