type CertPool struct {
  	byName map[string][]int 
  
  	// lazyCerts contains funcs that return a certificate,
  	// lazily parsing/decompressing it as needed.
    // 对证书进行解析操作
  	lazyCerts []lazyCert
  
  	// haveSum maps from sum224(cert.Raw) to true. It's used only
  	// for AddCert duplicate detection, to avoid CertPool.contains
  	// calls in the AddCert path (because the contains method can
  	// call getCert and otherwise negate savings from lazy getCert
  	// funcs).
    // 只用于 AddCert 重复检测
  	haveSum map[sum224]bool
  }

type lazyCert struct {
	// rawSubject is the Certificate.RawSubject value.
	// It's the same as the CertPool.byName key, but in []byte
	// form to make CertPool.Subjects (as used by crypto/tls) do
	// fewer allocations.
  // 使 CertPool.Subjects（由 crypto/tls 使用）做更少的分配。
	rawSubject []byte

	// getCert returns the certificate.
	//
	// It is not meant to do network operations or anything else
	// where a failure is likely; the func is meant to lazily
	// parse/decompress data that is already known to be good. The
	// error in the signature primarily is meant for use in the
	// case where a cert file existed on local disk when the program
	// started up is deleted later before it's read.
  // 这里的 func 意在延迟解析/解压缩已知良好的数据
	getCert func() (*Certificate, error)
}

// Authenticator 从经过验证的客户端证书中提取用户信息
type Authenticator struct {
   verifyOptionsFn VerifyOptionFunc
   user            UserConversion
}

// 给 Authenticator 提供了一个 VerifyOptions 的浅拷贝
type VerifyOptionFunc func() (x509.VerifyOptions, bool)

// 从客户端的证书链中提取用户信息
type UserConversion interface {
	 User(chain []*x509.Certificate) (*authenticator.Response, bool, error)
}

func New(opts x509.VerifyOptions, user UserConversion) *Authenticator {
   return NewDynamic(StaticVerifierFn(opts), user)
}

// 对于VerifyOptions中无法更改的选项进行浅拷贝并直接返回，
func StaticVerifierFn(opts x509.VerifyOptions) VerifyOptionFunc {
	 return func() (x509.VerifyOptions, bool) {
		  return opts, true
	 }
}

func NewDynamic(verifyOptionsFn VerifyOptionFunc, user UserConversion) *Authenticator {
	 return &Authenticator{verifyOptionsFn, user}
}

func (a *Authenticator) AuthenticateRequest(req *http.Request) (*authenticator.Response, bool, error) {
   if req.TLS == nil || len(req.TLS.PeerCertificates) == 0 {
      return nil, false, nil
   }

   // Use intermediates, if provided
   // 获取浅拷贝
   optsCopy, ok := a.verifyOptionsFn()
   // if there are intentionally no verify options, then we cannot authenticate this request
   if !ok {
      return nil, false, nil
   }
   // 这里的Intermediates是验证x509时的字段，属于证书的概念，一般来说颁发证书时，是一条证书链，其中包括root cert-intermediate cert-end user cert。intermediate 用于保证 end user 证书未被篡改。
   // 如果 Intermediates 为空，但存在 PeerCertificates，则新建一个 CertPool ，并将每一个 PeerCertificates 添加进去
   if optsCopy.Intermediates == nil && len(req.TLS.PeerCertificates) > 1 {
      optsCopy.Intermediates = x509.NewCertPool()
      for _, intermediate := range req.TLS.PeerCertificates[1:] {
         optsCopy.Intermediates.AddCert(intermediate)
      }
   }

   // 更新监控的 Histogram 指标
   remaining := req.TLS.PeerCertificates[0].NotAfter.Sub(time.Now())
   clientCertificateExpirationHistogram.WithContext(req.Context()).Observe(remaining.Seconds())
   // 进行验证，这里的验证在go源码中。
   // 主要是验证签发者和DNS是否合理
   chains, err := req.TLS.PeerCertificates[0].Verify(optsCopy)
   if err != nil {
      return nil, false, fmt.Errorf(
         "verifying certificate %s failed: %w",
         certificateIdentifier(req.TLS.PeerCertificates[0]),
         err,
      )
   }

   var errlist []error
   for _, chain := range chains {
      user, ok, err := a.user.User(chain)
      if err != nil {
         errlist = append(errlist, err)
         continue
      }

      if ok {
         return user, ok, err
      }
   }
   return nil, false, utilerrors.NewAggregate(errlist)
}

type Verifier struct {
   verifyOptionsFn VerifyOptionFunc
   auth            authenticator.Request

   // allowedCommonNames contains the common names which a verified certificate is allowed to have.
   // If empty, all verified certificates are allowed.
   // 为空，表示允许所有经过验证的证书。
   allowedCommonNames StringSliceProvider
}

// 从请求中提取身份验证信息
type Request interface {
	AuthenticateRequest(req *http.Request) (*Response, bool, error)
}

type StringSliceProvider interface {
	// Value returns the current string slice.  Callers should never mutate the returned value.
	Value() []string
}

func (a *Verifier) AuthenticateRequest(req *http.Request) (*authenticator.Response, bool, error) {
   if req.TLS == nil || len(req.TLS.PeerCertificates) == 0 {
      return nil, false, nil
   }

   // Use intermediates, if provided
   optsCopy, ok := a.verifyOptionsFn()
   // if there are intentionally no verify options, then we cannot authenticate this request
   if !ok {
      return nil, false, nil
   }
   if optsCopy.Intermediates == nil && len(req.TLS.PeerCertificates) > 1 {
      optsCopy.Intermediates = x509.NewCertPool()
      for _, intermediate := range req.TLS.PeerCertificates[1:] {
         optsCopy.Intermediates.AddCert(intermediate)
      }
   }

   if _, err := req.TLS.PeerCertificates[0].Verify(optsCopy); err != nil {
      return nil, false, err
   }
   if err := a.verifySubject(req.TLS.PeerCertificates[0].Subject); err != nil {
      return nil, false, err
   }
   // 可以自定义 auth 的 func 进行验证
   return a.auth.AuthenticateRequest(req)
}