Caddy 源碼全解析
caddy源碼全解析
Preface
Caddy 是 Go 語言建構的輕量配置化伺服器。同時代碼結構由于 Go 語言的輕便簡潔，比較易讀，推薦學弟學妹學習 Go 的時候也去檢視追一下它的源碼。不用怕相信這篇文章能給你很大的信心。
可能會有點多，建議多看幾遍。
Overview-CaddyMain
當然，建議看這篇文章的時候，檢視上手一下 Caddy 的實際配置操作應用，對了解源碼會有好處，如果沒有操作過也沒有關系。
Package
這是 caddy 包的結構
首先我們從一切的開始講起，即平時我們程式運作的 main.go 函數。
這是 上圖 caddy 檔案夾下的目錄結構。
在 caddy 檔案夾中的 main 函數啟動 caddy 伺服器。實際運作的是 run.go 中的檔案，這是友善測試使用
看 main.go 的代碼
通過改變 run 變量的值來友善測試，可以學習一下。
啟動流程
啟動 caddy 的流程畫了張圖
見到不認識的不用擔心，檢視上文的目錄結構可以找到他們大概的位置，下文會詳細講解。
可以在此圖中看到幾個重要的點
caddyfileLoader
這是加載 caddyfile 配置來啟動伺服器的。
如果配置使用過 caddy ，配置的 caddyfile 就是在這裡被
Loader
讀取後執行個體化伺服器的。如果沒有使用過，大緻說一下流程，使用 caddy 非常簡單，隻需配置上文所說的 caddyfile 檔案，按行配置選項，然後使用 caddy 運作讀取該配置檔案即可。簡單示例就是以下的文本。
Instance
是運作操作的執行個體，可以看到幾個主要的操作都是在他身上
Server
可以看到擁有
TCP
UDP
兩個 Server 的接口。
我們首先關心的是
Start()
啟動伺服器。
啟動伺服器
發送 StartupEvent, 參照下文中 Event 了解
// Executes Startup events
caddy.EmitEvent(caddy.StartupEvent, nil)
讀取配置檔案：
caddyfileinput, err := caddy.LoadCaddyfile(serverType)
啟動：
instance, err := caddy.Start(caddyfileinput)
發送 InstanceStartupEvent
caddy.EmitEvent(caddy.InstanceStartupEvent, instance
caddy.Start()
閱讀完代碼，畫一張圖幫助了解
是不是很簡單，來一點更詳細的互動
這裡除了
Instance
之外還有兩個新名詞
Controller
：它是用來幫助
Directives
設定它自身的，通過讀取
Token
，這裡的
Directives
實際上對應的就是上文所說的 caddyfile 中的配置檔案選項。這一點請參照下文中 Loader 下的
excuteDirective
了解。
Token
：是 caddy 自己的 詞法分析器 解析 caddyfile 配置檔案出的選項的标記。這一點請參照下文中 Loader 中的 Parser 了解
如果不了解，首先記住 caddy 是配置化的伺服器，
通過 caddyfile 配置 ->
那麼肯定要讀取它啦 ->
然後要解析它配置的到底是那些東西 ->
之後呢，就要讓配置的目标做到 caddyfile 中聲明的更改。
記住這個流程繼續看幾遍就能了解了。
Server
在 caddy.go 中定義着
Server
的接口，同時實作了優雅的退出。我們首先看圖了解組織結構
簡單看一下
Stopper
的接口
// Stopper is a type that can stop serving. The stop
// does not necessarily have to be graceful.
type Stopper interface {
// Stop stops the server. It blocks until the
// server is completely stopped.
Stop() error
}
GracefulServer
包含
Stopper
的接口實作了優雅退出，這是攔截了 系統 signal 的信号之後執行的結果，意在意外中斷的時候儲存好需要儲存的東西。
它同時包含着 WrapListener 函數。可以看出，他用來做中間件。
// WrapListener wraps a listener with the
// listener middlewares configured for this
// server, if any.
WrapListener(net.Listener) net.Listener
ServerType
最後看到不同 serverType 生成不同的 server
另外可以看到 這裡最重要的
Instance
下面我們進一步檢視
Instance
的代碼
Instance
instance 是 Server 用來執行操作的實體。首先來看他的結構。它的代碼在 主檔案夾中的 caddy.go 中
首先我們看一下 它的結構了解下它可能有的功能
struct
type Instance struct {
serverType string
caddyfileInput Input
wg *sync.WaitGroup
context Context
servers []ServerListener
OnFirstStartup []func() error // starting, not as part of a restart
OnStartup []func() error // starting, even as part of a restart
OnRestart []func() error // before restart commences
OnRestartFailed []func() error // if restart failed
OnShutdown []func() error // stopping, even as part of a restart
OnFinalShutdown []func() error // stopping, not as part of a restart
Storage map[interface{}]interface{}
StorageMu sync.RWMutex
}
serverType
serverType
caddyfileInput
Input
Instance
caddyfileInput
Input
Instance
wg
servers
wg
servers
context
Instance
serverType
context
Instance
serverType
servers
server
listeners
serverType
serverType
caddyfile
servers
server
listeners
serverType
serverType
caddyfile
OnXXX
OnXXX
Storage
Storage
雖然 Instance 操作着衆多操作，但是我們卻不能從它講起，從農村包圍城市，漸漸了解 Instance 能調用的函數，自然 Instance 的功能就清晰了。
Event
首先上圖：
首先我們看到的是 eventHooks 這個結構，實際上他是存儲
key：name value：EventHook
這樣的一個
map[string]EventHook
的結構，隻是從 sync 包中引入保證并發安全。
eventHooks = &sync.Map{}
然後是重要的
caddy.EventHook
結構。
type EventHook func(eventType EventName, eventInfo interface{}) error
然後我們關注到如何注冊，和圖中的
caddy.EmitEvent
注冊與分發
注冊 EventHook
可以看到使用
eventHooks.LoadOrStore
方法，不必贅述
func RegisterEventHook(name string, hook EventHook){
if name == "" {
panic("event hook must have a name")
}
_, dup := eventHooks.LoadOrStore(name, hook)
if dup {
panic("hook named" + name + "already registered")
}
}
分發 EmitEvent
通過傳入函數為參數調用回調函數
// EmitEvent executes the different hooks passing the EventType as an
// argument. This is a blocking function. Hook developers should
// use 'go' keyword if they don't want to block Caddy.
func EmitEvent(event EventName, info interface{}) {
eventHooks.Range(func(k, v interface{}) bool {
err := v.(EventHook)(event, info)
if err != nil {
log.Printf("error on '%s' hook: %v", k.(string), err)
}
return true //注意這裡傳回的是 true
})
}
這裡使用的 Range 函數，實際上是把事件資訊給每一個上述提過 map 中的 EventHook 提供參數進行回調執行，按順序調用，但是如果 傳入函數傳回 false ，疊代周遊執行就會中斷。
可以知道，上文 Overview中啟動伺服器 所說的發送 caddy.StartupEvent 事件就是調用的
caddy.EmitEvent(caddy.StartupEvent, nil)
講到這，相信已經對大緻的流程有了一點架構的概念。
下面我們繼續深入了解 在讀取
caddyfile
檔案的時候發生了什麼。
Loader
自定義的配置檔案都會有讀取分析。在 caddy 中 由
Loader
執行這一項職能。首先我們看一下它的工作流程。
這個圖來源于 plugin.go 檔案
可以看到這裡通過
Loader
解耦了 caddyfile 檔案的讀取，是以把它放在了 plugin.go 檔案中，作為一個插件注冊在 caddy app 中。
這裡可以看到最終流程是 name ->
caddy.Input
那麼這個
Input
是什麼呢？
實際上
Input
就是 caddyfile 在代碼中的映射。可以了解為，caddyfile 轉化為了
Input
給 caddy 讀取。誰來讀取它呢？
那麼幹活的主角登場啦！
Parser
這裡我們來看，各個流程的終點
Token
是如何被分析出來的,需要知道，這裡的
Token
代表着 caddyfile 中的每行選項配置
詞法分析
// allTokens lexes the entire input, but does not parse it.
// It returns all the tokens from the input, unstructured
// and in order.
func allTokens(input io.Reader) ([]Token, error) {
l := new(lexer)
err := l.load(input)
if err != nil {
return nil, err
}
var tokens []Token
for l.next() {
tokens = append(tokens, l.token)
}
return tokens, nil
}
這裡實際上關鍵在于 讀取，可以看到在
dispenser
中由
cursor
來進行
Token
數組中的疊代
關鍵在于移動
cursor
索引的函數
next()
// next loads the next token into the lexer.
// A token is delimited by whitespace, unless
// the token starts with a quotes character (")
// in which case the token goes until the closing
// quotes (the enclosing quotes are not included).
// Inside quoted strings, quotes may be escaped
// with a preceding \ character. No other chars
// may be escaped. The rest of the line is skipped
// if a "#" character is read in. Returns true if
// a token was loaded; false otherwise.
func (l *lexer) next() bool {
var val []rune
var comment, quoted, escaped bool
makeToken := func() bool {
l.token.Text = string(val)
return true
}
for {
ch, _, err := l.reader.ReadRune()
if err != nil {
if len(val) > 0 {
return makeToken()
}
if err == io.EOF {
return false
}
panic(err)
}
if quoted {
if !escaped {
if ch == '\\' {
escaped = true
continue
} else if ch == '"' {
quoted = false
return makeToken()
}
}
if ch == '\n' {
l.line++
}
if escaped {
// only escape quotes
if ch != '"' {
val = append(val, '\\')
}
}
val = append(val, ch)
escaped = false
continue
}
if unicode.IsSpace(ch) {
if ch == '\r' {
continue
}
if ch == '\n' {
l.line++
comment = false
}
if len(val) > 0 {
return makeToken()
}
continue
}
if ch == '#' {
comment = true
}
if comment {
continue
}
if len(val) == 0 {
l.token = Token{Line: l.line}
if ch == '"' {
quoted = true
continue
}
}
val = append(val, ch)
}
}
了解了
next
函數，就很容易知道如何分析一塊選項的
token
了，不過都是
next()
的包裝函數罷了。
excuteDirective
func executeDirectives(inst *Instance, filename string,
directives []string, sblocks []caddyfile.ServerBlock, justValidate bool) error {
// map of server block ID to map of directive name to whatever.
storages := make(map[int]map[string]interface{})
// It is crucial that directives are executed in the proper order.
// We loop with the directives on the outer loop so we execute
// a directive for all server blocks before going to the next directive.
// This is important mainly due to the parsing callbacks (below).
for _, dir := range directives {
for i, sb := range sblocks {
var once sync.Once
if _, ok := storages[i]; !ok {
storages[i] = make(map[string]interface{})
}
for j, key := range sb.Keys {
// Execute directive if it is in the server block
if tokens, ok := sb.Tokens[dir]; ok {
controller := &Controller{
instance: inst,
Key: key,
Dispenser: caddyfile.NewDispenserTokens(filename, tokens),
OncePerServerBlock: func(f func() error) error {
var err error
once.Do(func() {
err = f()
})
return err
},
ServerBlockIndex: i,
ServerBlockKeyIndex: j,
ServerBlockKeys: sb.Keys,
ServerBlockStorage: storages[i][dir],
}
setup, err := DirectiveAction(inst.serverType, dir)
if err != nil {
return err
}
err = setup(controller)
if err != nil {
return err
}
storages[i][dir] = controller.ServerBlockStorage // persist for this server block
}
}
}
if !justValidate {
// See if there are any callbacks to execute after this directive
if allCallbacks, ok := parsingCallbacks[inst.serverType]; ok {
callbacks := allCallbacks[dir]
for _, callback := range callbacks {
if err := callback(inst.context); err != nil {
return err
}
}
}
}
}
return nil
}
caddyfile 既然被解析完畢，那麼就要開始執行配置更改了，這裡實際上是 caddy.go 中的 函數，最後在 caddy 的 main.go 中調用來執行更改。
DirectiveAction
很容易發現，這裡是通過 操作 Controller 來實作的，此時可以再傳回最上文檢視上一次提到 Controller 的時候。
// DirectiveAction gets the action for directive dir of
// server type serverType.
func DirectiveAction(serverType, dir string) (SetupFunc, error) {
if stypePlugins, ok := plugins[serverType]; ok {
if plugin, ok := stypePlugins[dir]; ok {
return plugin.Action, nil
}
}
if genericPlugins, ok := plugins[""]; ok {
if plugin, ok := genericPlugins[dir]; ok {
return plugin.Action, nil
}
}
return nil, fmt.Errorf("no action found for directive '%s' with server type '%s' (missing a plugin?)",
dir, serverType)
}
了解完這些，我們注意到有一個 叫做
Action
的東西，它又是怎麼來的？别急，他就在
Plugin
包中。我們知道了，配置檔案實際上是配置各種
plugin
作為插件安裝在 caddy 伺服器上，而 caddyfile 正是被轉化為了 Token，Dispenser 來執行配置更改，即不同的插件安裝。那麼
Action
就是
Plugin
的
SetupFunc
啦，來看看吧。
Plugin
你會注意到，在目錄中有一個 叫 caddyhttp 的檔案夾中的檔案夾特别多，不用問，這就是 http 的可選
Plugin
啦
Overview
這裡概覽了
Plugin
是如何注冊的。
可以在這裡看到我們之前講解的很多的熟悉的概念，這是因為我們快要讀完 caddy 的架構了，剩下的實際上是具體的
Plugin
的各種擴充實作了。
可以看到，
Plugin
是注冊在不同的 伺服器類型
serverType
下的，實際上是在兩重 map 映射的結構中，圖中可以看出，然後是
Action
，最近的上文才說明了它，用它來進行
Plugin
的安裝。
然後來到
Controller
，實際進行配置的家夥，看到了之前所說的
Dispenser
和
Token
配置，還記得嗎，他們在剛才的詞法分析裡才出現過。
接下來我們看一個
HTTP
Plugin
的例子
errors
的實作
caddyHTTP
errors
這裡我們從下看，caddy.Listener 定義在 caddy.go 中，用來支援 零停機時間加載。
往上看到 Middleware 調用，我們來看看 errorsHandle 的結構
// ErrorHandler handles HTTP errors (and errors from other middleware).
type ErrorHandler struct {
Next httpserver.Handler
GenericErrorPage string // default error page filename
ErrorPages map[int]string // map of status code to filename
Log *httpserver.Logger
Debug bool // if true, errors are written out to client rather than to a log
}
可以看到，Next 字段明顯是 Chain 調用的下一個 Handler 處理。事實上，每一個 Plugin 或者算是 HTTP 服務中的中間件都有這個字段用于 建構鍊式調用。
每一個 Plugin 值得注意的兩個，
一個是他們會實作 ServeHTTP 接口進行 HTTP 請求處理。
func (h ErrorHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) (int, error) {
defer h.recovery(w, r)
status, err := h.Next.ServeHTTP(w, r)
if err != nil {
errMsg := fmt.Sprintf("%s [ERROR %d %s] %v", time.Now().Format(timeFormat), status, r.URL.Path, err)
if h.Debug {
// Write error to response instead of to log
w.Header().Set("Content-Type", "text/plain; charset=utf-8")
w.WriteHeader(status)
fmt.Fprintln(w, errMsg)
return 0, err // returning 0 signals that a response has been written
}
h.Log.Println(errMsg)
}
if status >= 400 {
h.errorPage(w, r, status)
return 0, err
}
return status, err
}
另一個是安裝到 caddy 中的 setup.go 檔案，我們看一下 Plugin 安裝的全流程。
Directives
前面提到過很多次 Directives 這裡做一個它的整個流程概覽。上文中提到，這些注冊實際上都是 Controller 執行的。下半部分是 關于 HTTP 的服務配置
這裡的重點在 errors.serup() 可以看到，它建立了 errors.ErrHandler 并注冊到了 httpserver 的一對中間件中
// setup configures a new errors middleware instance.
func setup(c *caddy.Controller) error {
handler, err := errorsParse(c)
···
httpserver.GetConfig(c).AddMiddleware(func(next httpserver.Handler) httpserver.Handler {
handler.Next = next
return handler
})
return nil
}
實際上這裡還有一個關于 caddy.Controller 到 ErrorHandler 的一個轉換 通過 errorsParse 函數
謝謝閱讀，如果有不對的地方歡迎指正。
歡迎關注我的微信公衆号 abserari 或我的微信 abser9216
有條件的也可以關注我的 telegram ：https://t.me/abserari
![Linux之父警告全球程式員：我剛釋出的5.12核心有bug，你們千萬别用[圖]](data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=)