ZIO Quartz H2 Logo

Quartz H2

Quartz H2 is a high-performance HTTP/2 server built with Scala and Cats Effect, providing both HTTP/1.1 and HTTP/2 protocol support with various connection modes.

Server Architecture Overview

Quartz H2 is designed with flexibility and performance in mind, supporting multiple connection modes and protocols:

Connection Modes

  • Asynchronous NIO Mode - Uses Java NIO for non-blocking I/O operations with Cats Effect
  • Synchronous Socket Mode - Uses traditional Java Socket API for synchronous connections
  • Linux io_uring Mode - Leverages Linux's io_uring interface for high-performance I/O operations (Linux-specific)

Protocol Support

  • HTTP/2 with TLS (h2) - Full HTTP/2 protocol support over TLS connections
  • HTTP/2 Clear Text (h2c) - HTTP/2 protocol support without encryption
  • HTTP/1.1 - Backward compatibility with HTTP/1.1 protocol
  • Protocol Upgrade - Support for upgrading HTTP/1.1 connections to HTTP/2

Connection Flow

The server handles connections through the following process:

  1. Accept incoming connection (TCP or TLS)
  2. Detect protocol (HTTP/1.1 or HTTP/2)
  3. For HTTP/2: Process preface and establish HTTP/2 connection
  4. For HTTP/1.1: Process as HTTP/1.1 or attempt upgrade to HTTP/2 if requested
  5. Route requests to appropriate handlers
  6. Stream responses back to clients

Key Components

QuartzH2Server

The main server class that manages HTTP/2 connections with features like:

  • Connection management for HTTP/2 and HTTP/1.1
  • TLS configuration and ALPN negotiation
  • Server socket binding
  • Connection lifecycle hooks

Http2Connection

Manages HTTP/2 connections with features like:

  • Frame processing for different HTTP/2 frame types
  • Stream management
  • Flow control implementation
  • Settings management
  • Header compression

Http2Stream

Represents an individual HTTP/2 stream with:

  • Stream-level flow control
  • Header processing
  • Data queueing
  • Stream state management

Http11Connection

Handles HTTP/1.1 connections with support for:

  • Improved chunked transfer encoding
  • HTTP range requests with proper ETag generation
  • Enhanced error handling and logging
  • Keep-alive connections

Channel Types

Different channel implementations for I/O operations:

  • AsyncSocketChannel - For asynchronous NIO operations
  • SocketChannel - For Socket-based connections
  • TLSChannel - For secure connections with SSL/TLS
  • IOURingChannel - For Linux io_uring-based connections

Performance Features

  • Stream Multiplexing - Multiple requests over a single connection
  • Efficient Resource Usage - Configurable thread pools and connection limits
  • Linux io_uring Support - High-performance I/O operations on Linux systems
  • Cats Effect Integration - Leverages Cats Effect for functional concurrency and resource management
  • Configurable Timeouts - Idle connection timeouts to manage resources
  • Flow Control - Prevents overwhelming clients with data

Client Implementation

Quartz H2 includes a client implementation for making HTTP/2 requests to servers:

Connection Establishment

  • TLS with ALPN - Secure connections with protocol negotiation
  • Direct HTTP/2 - Plain HTTP/2 connections without TLS
  • Connection Pooling - Reusing connections for multiple requests

Request Handling

  • Streaming Requests - Support for streaming request bodies
  • Header Management - Proper handling of HTTP/2 headers
  • Response Processing - Processing and streaming of response data
  • Error Handling - Robust error handling for network issues

Documentation

Explore the documentation to learn more about Quartz H2:

Routes DSL

Learn how to define routes using the functional DSL

FS2 Streams Integration

Discover how to use FS2 Streams with Quartz H2

Architecture

Understand the architecture and design of Quartz H2

Flow Control

Learn about HTTP/2 flow control implementation

Cats Effect Async for Java NIO

Explore the Java NIO implementation with Cats Effect

Cats Effect Async for IoUring

Learn about the Linux io_uring integration with Cats Effect