> ## Documentation Index > Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt > Use this file to discover all available pages before exploring further. # H2C > HTTP/2 cleartext middleware for unencrypted HTTP/2 connections. ## Overview The `h2c` middleware enables HTTP/2 cleartext (h2c) connections, allowing HTTP/2 over unencrypted connections for development and internal services. Use it when you need: * HTTP/2 without TLS * Development HTTP/2 testing * Internal service communication ## Installation ```go theme={null} import "github.com/go-mizu/mizu/middlewares/h2c" ``` ## Quick Start ```go theme={null} app := mizu.New() // Enable h2c server := h2c.Server(app) server.ListenAndServe(":8080") ``` ## Examples ### Basic H2C Server ```go theme={null} app := mizu.New() app.Get("/", func(c *mizu.Ctx) error { return c.Text(200, "HTTP/2 Cleartext!") }) // Wrap with h2c server := h2c.Server(app) log.Fatal(server.ListenAndServe(":8080")) ``` ### With Custom Server ```go theme={null} app := mizu.New() server := &http.Server{ Addr: ":8080", Handler: h2c.Handler(app), } server.ListenAndServe() ``` ## API Reference ### Functions ```go theme={null} // Server creates h2c-enabled server func Server(handler http.Handler) *http.Server // Handler wraps handler for h2c support func Handler(handler http.Handler) http.Handler ``` ## Technical Details ### Implementation Overview The h2c middleware provides HTTP/2 cleartext support through two main mechanisms: 1. **HTTP/2 Prior Knowledge**: Direct HTTP/2 connections where the client knows in advance that the server supports HTTP/2. Detected by checking `ProtoMajor == 2`. 2. **HTTP/2 Upgrade**: HTTP/1.1 upgrade mechanism using the h2c upgrade protocol (RFC 7540, Section 3.2). ### Core Components #### Options Configuration * `AllowUpgrade` (default: true): Enables HTTP/1.1 to HTTP/2 upgrade requests * `AllowDirect` (default: true): Enables direct HTTP/2 connections with prior knowledge * `OnUpgrade`: Optional callback function triggered when an upgrade occurs #### Context Information The middleware stores connection information in the request context: ```go theme={null} type Info struct { IsHTTP2 bool // True if request uses HTTP/2 Upgraded bool // True if upgraded from HTTP/1.1 Direct bool // True if direct HTTP/2 connection } ``` #### Upgrade Detection The middleware validates h2c upgrade requests by checking: * `Connection` header contains "Upgrade" token * `Upgrade` header equals "h2c" (case-insensitive) * `HTTP2-Settings` header is present #### Connection Handling * Uses `http.Hijacker` interface to take over the TCP connection * Sends `101 Switching Protocols` response * Manages connection lifecycle with buffered reading via `BufferedConn` #### Helper Functions * `GetInfo(c *mizu.Ctx)`: Retrieves h2c information from context * `IsHTTP2(c *mizu.Ctx)`: Quick check if request is HTTP/2 * `ParseSettings(r *http.Request)`: Decodes base64-encoded HTTP2-Settings header * `IsHTTP2Preface(data []byte)`: Validates HTTP/2 connection preface bytes ## Security Warning H2C transmits data unencrypted. Only use for: * Development environments * Internal services behind TLS termination * Testing scenarios ## Best Practices * Never use h2c in production over public networks * Use behind TLS-terminating load balancer * Test with `curl --http2-prior-knowledge` ## Testing The h2c middleware includes comprehensive test coverage for all functionality: | Test Case | Description | Expected Behavior | | ------------------------------------------ | -------------------------- | --------------------------------------------------------------------------- | | TestNew | Basic middleware creation | Middleware initializes with default options and processes HTTP/1.1 requests | | TestDetectHTTP1 | HTTP/1.1 detection | Correctly identifies HTTP/1.x requests, sets IsHTTP2 to false | | TestIsH2CUpgrade | Upgrade request validation | Validates h2c upgrade headers (Connection, Upgrade, HTTP2-Settings) | | TestContainsToken | Header token parsing | Correctly parses comma-separated header values | | TestGetInfo | Context info retrieval | Retrieves h2c info from request context | | TestIsHTTP2 | HTTP/2 detection helper | Returns correct boolean for HTTP/2 detection | | TestParseSettings | HTTP2-Settings parsing | Decodes base64-encoded settings header | | TestParseSettingsEmpty | Empty settings handling | Returns nil for missing HTTP2-Settings header | | TestParseSettingsInvalid | Invalid settings handling | Returns error for malformed base64 | | TestOnUpgrade | Upgrade callback | Executes OnUpgrade callback when upgrade occurs | | TestServerHandler | ServerHandler creation | Creates handler with h2c support | | TestWrap | Handler wrapping | Wraps standard http.Handler with h2c support | | TestIsHTTP2Preface | Preface detection | Validates HTTP/2 connection preface bytes | | TestDetect | Detection-only mode | Detects h2c without handling upgrade | | TestWithOptionsDisabled | Disabled options | Respects AllowUpgrade and AllowDirect settings | | TestBufferedConn | Buffered connection | Handles buffered reading with Peek and Read | | TestGetInfo\_NoContext | Missing context info | Returns empty Info when middleware not used | | TestDetect\_WithH2CUpgrade | Upgrade detection | Correctly detects and marks upgrade requests | | TestServerHandler\_WithH2CUpgrade | Handler upgrade flow | Processes h2c upgrade in ServerHandler | | TestServerHandler\_UpgradeDisabled | Disabled upgrade handling | Falls back to handler when upgrade disabled | | TestInfo\_Fields | Info struct fields | Validates Info struct field values | | TestConnectionPreface | Preface constant | Verifies correct HTTP/2 preface constant | | TestWithOptions\_HTTP2PriorKnowledge | Prior knowledge handling | Detects direct HTTP/2 connections | | TestWithOptions\_H2CUpgradeWithCallback | Upgrade with callback | Executes callback during upgrade | | TestHandleUpgrade\_NonHijackable | Non-hijackable fallback | Falls back to HTTP/1.1 when hijack unsupported | | TestServerHandler\_HTTP2PriorKnowledge | Prior knowledge in handler | Handles HTTP/2 prior knowledge in ServerHandler | | TestServerHandler\_H2CUpgrade\_WithHijack | Successful hijack | Successfully hijacks connection for upgrade | | TestServerHandler\_H2CUpgrade\_HijackError | Hijack error handling | Falls back to handler on hijack error | | TestServerHandler\_NonHijackable | Handler fallback | Falls back when ResponseWriter not hijackable | | TestDetect\_HTTP2PriorKnowledge | Prior knowledge detection | Detects HTTP/2 prior knowledge in Detect mode | | TestBufferedConn\_Underlying | Underlying connection ops | Validates Write, Close operations on BufferedConn | | TestWithOptions\_H2CUpgrade\_HijackError | Middleware hijack error | Handles hijack errors in middleware | | TestBufferedConn\_NetConnInterface | net.Conn interface | Validates complete net.Conn interface implementation | ## Related Middlewares * [secure](/middlewares/secure) - HTTPS enforcement * [proxy](/middlewares/proxy) - Reverse proxy