From 7c8fe21c7aa1fee5b73b3d21848b1d9442499a59 Mon Sep 17 00:00:00 2001
From: WeidiDeng <weidi_deng@icloud.com>
Date: Mon, 10 Apr 2023 11:15:39 +0800
Subject: [PATCH] Add comments

---
 modules/caddyhttp/app.go           |  4 ++--
 modules/caddyhttp/http2listener.go |  6 ++++++
 modules/caddyhttp/server.go        | 14 ++++++++------
 3 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/modules/caddyhttp/app.go b/modules/caddyhttp/app.go
index 2e8c87e8e31..53b57820dc9 100644
--- a/modules/caddyhttp/app.go
+++ b/modules/caddyhttp/app.go
@@ -471,7 +471,7 @@ func (app *App) Start() error {
 						server:   srv.server,
 						h2server: h2server,
 					}
-					srv.http2listeners = append(srv.http2listeners, http2lnWrapper)
+					srv.h2listeners = append(srv.h2listeners, http2lnWrapper)
 					ln = http2lnWrapper
 				}
 
@@ -608,7 +608,7 @@ func (app *App) Stop() error {
 		defer finishedShutdown.Done()
 		startedShutdown.Done()
 
-		for i, s := range server.http2listeners {
+		for i, s := range server.h2listeners {
 			if err := s.Shutdown(ctx); err != nil {
 				app.logger.Error("http2 listener shutdown",
 					zap.Error(err),
diff --git a/modules/caddyhttp/http2listener.go b/modules/caddyhttp/http2listener.go
index 2ee6f898d4f..51b356a7779 100644
--- a/modules/caddyhttp/http2listener.go
+++ b/modules/caddyhttp/http2listener.go
@@ -12,6 +12,12 @@ import (
 	"golang.org/x/net/http2"
 )
 
+// http2Listener wraps the listener to solve the following problems:
+// 1. server h2 natively without using h2c hack when listener handles tls connection but
+// don't return *tls.Conn
+// 2. graceful shutdown. the shutdown logic is copied from stdlib http.Server, it's an extra maintenance burden but
+// whatever, the shutdown logic maybe extracted to be used with h2c graceful shutdown. http2.Server supports graceful shutdown
+// sending GO_AWAY frame to connected clients, but doesn't track connection status. It requires explicit call of http2.ConfigureServer
 type http2Listener struct {
 	cnt uint64
 	net.Listener
diff --git a/modules/caddyhttp/server.go b/modules/caddyhttp/server.go
index 8581d468d8d..96da8fb9259 100644
--- a/modules/caddyhttp/server.go
+++ b/modules/caddyhttp/server.go
@@ -19,6 +19,7 @@ import (
 	"crypto/tls"
 	"encoding/json"
 	"fmt"
+	"github.com/quic-go/quic-go"
 	"io"
 	"net"
 	"net/http"
@@ -34,7 +35,6 @@ import (
 	"github.com/caddyserver/caddy/v2/modules/caddyevents"
 	"github.com/caddyserver/caddy/v2/modules/caddytls"
 	"github.com/caddyserver/certmagic"
-	"github.com/quic-go/quic-go"
 	"github.com/quic-go/quic-go/http3"
 	"go.uber.org/zap"
 	"go.uber.org/zap/zapcore"
@@ -195,11 +195,11 @@ type Server struct {
 	errorLogger  *zap.Logger
 	ctx          caddy.Context
 
-	server         *http.Server
-	h3server       *http3.Server
-	h3listeners    []net.PacketConn // TODO: we have to hold these because quic-go won't close listeners it didn't create
-	http2listeners []*http2Listener
-	addresses      []caddy.NetworkAddress
+	server      *http.Server
+	h3server    *http3.Server
+	h3listeners []net.PacketConn // TODO: we have to hold these because quic-go won't close listeners it didn't create
+	h2listeners []*http2Listener
+	addresses   []caddy.NetworkAddress
 
 	trustedProxies IPRangeSource
 
@@ -214,6 +214,8 @@ type Server struct {
 
 // ServeHTTP is the entry point for all HTTP requests.
 func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	// If there are listener wrappers that process tls connections but don't return a *tls.Conn, this field will be nil.
+	// Can be removed if https://github.com/golang/go/pull/56110 is ever merged.
 	if r.TLS == nil {
 		conn := r.Context().Value(ConnCtxKey).(net.Conn)
 		if csc, ok := conn.(connectionStateConn); ok {