Learning Caddy - gRPC & Modern Protocols

#Introduction

Modern microservices often communicate with gRPC — an RPC framework using HTTP/2 and protobuf. gRPC promises high performance and two-way streaming, but it comes with one requirement: HTTP/2 is mandatory. Episode 26 covers how Caddy serves and proxies gRPC.

You'll also learn gRPC-Web for browser clients, gRPC-specific load balancing, and HTTP/3 (QUIC) — the next-generation protocol Caddy enables automatically.

After this episode, you'll be able to make Caddy an API gateway for gRPC services while supporting the most modern protocols available.

#gRPC Basics

#Why gRPC Needs HTTP/2

gRPC uses HTTP/2 features that don't exist in HTTP/1.1:

• Multiplexing: many streams in one connection.
• Binary framing: efficient for protobuf.
• Streaming: bidirectional server and client streaming.
• Header compression: HPACK to save bandwidth.

Without HTTP/2, gRPC doesn't run at all. Caddy handles the client side automatically (browsers or gRPC clients connecting over HTTPS), but the backend side needs to be set up.

#gRPC Reverse Proxy

#The h2c Transport

gRPC backends typically speak HTTP/2 cleartext (h2c). The configuration:

grpc.example.com {
    reverse_proxy localhost:50051 {
        transport http {
            versions h2c 2
        }
    }
}

transport http { versions h2c 2 } forces the backend connection to use HTTP/2 without TLS. Caddy handles TLS with the client (HTTPS), then forwards to the backend over h2c.

#Protocol Detection

Caddy detects the application/grpc content type and handles streams correctly. Streaming, unary, and bidirectional calls all work through the same configuration. No special matchers needed.

#TLS Considerations

• gRPC clients connect over HTTPS — Caddy provides the certificate.
• The backend uses h2c (no TLS) because it's already on the internal network.
• If the backend has its own TLS, use the http transport with tls enabled.

#gRPC Load Balancing

#Long-Lived Connections and Health Checks

gRPC uses long-lived HTTP/2 connections with many streams. When using multiple backends:

grpc.example.com {
    reverse_proxy {
        to grpc-a:50051 grpc-b:50051 grpc-c:50051
        lb_policy round_robin
        transport http {
            versions h2c 2
        }
        health_uri /healthz
        health_interval 10s
    }
}

health_uri /healthz probes gRPC backends periodically. Failed backends are removed from the pool — long-lived HTTP/2 connections need proactive health checks.

#gRPC Service Health

Standard gRPC services expose a health-check protocol. Make sure the /healthz endpoint is configured in the application, or use grpc-health-probe. Healthy backends are detected automatically and re-registered after recovery.

#gRPC-Web

#gRPC from the Browser

Browsers can't use native gRPC (it needs full HTTP/2 control). The solution is gRPC-Web:

• A web application calls the gRPC-Web endpoint.
• Caddy forwards to the gRPC backend.
• The backend handles both, or a gRPC-Web proxy handles it.

Caddy supports gRPC-Web by proxying those requests as usual. What you need to watch is CORS — because requests come from a different origin:

grpc.example.com {
    @preflight {
        method OPTIONS
    }
    handle @preflight {
        header Access-Control-Allow-Origin *
        header Access-Control-Allow-Methods "POST"
        header Access-Control-Allow-Headers "content-type, x-grpc-web"
        respond 204
    }
    header Access-Control-Allow-Origin *
    reverse_proxy localhost:50051 {
        transport http {
            versions h2c 2
        }
    }
}

header Access-Control-Allow-Headers "content-type, x-grpc-web" allows the gRPC-Web-specific headers on preflight. Without proper CORS, browsers block calls from the web app.

#gRPC-Web Use Cases

• Admin UIs that call backend services.
• Internal dashboards built on microservices.
• Mobile web apps that need streaming data.

#HTTP/3 (QUIC)

#Enabling HTTP/3

HTTP/3 runs over UDP with the QUIC protocol. Caddy enables it automatically:

{
    servers {
        protocols h1 h2 h3
    }
}
 
example.com {
    root * /var/www
    file_server
}

protocols h1 h2 h3 includes HTTP/3. The only external requirement: UDP port 443 open in the firewall. Without it, Caddy still runs on HTTP/2.

#QUIC Advantages

• 0-RTT: a much faster handshake.
• Multiplexing without head-of-line blocking — other streams aren't held up.
• Connection migration: connections survive network changes.
• Built-in encryption: TLS 1.3 is always on.

#The Alt-Svc Header

Caddy sends the Alt-Svc: h3=... header, which tells browsers that HTTP/3 is available. Browsers that support it automatically use QUIC on subsequent requests. This header is handled automatically — no configuration needed.

#Conclusion

Episode 26 covered gRPC and modern protocols: the HTTP/2 requirement, gRPC reverse proxying with transport http { versions h2c 2 }, load balancing with health checks, gRPC-Web with CORS for browsers, and HTTP/3 (QUIC) with UDP port 443 and the Alt-Svc header.

Key takeaways:

• gRPC requires HTTP/2; the backend uses h2c.
• versions h2c 2 in the transport enables HTTP/2 cleartext.
• Proactive health checks matter for gRPC backend pools.
• gRPC-Web needs CORS with the x-grpc-web header.
• HTTP/3 activates automatically if UDP 443 is open.
• Alt-Svc tells browsers to use QUIC.

In the next episode, episode 27, we'll cover Docker integration — the official Caddy image, multi-stage builds, Docker Compose with volumes and networks, certificate persistence, service discovery between containers, and Caddy as a reverse proxy for many applications.