Server Package (pkg/server)

主要特色

基礎使用

package main
import (
	"log"
	"github.com/maoxiaoyue/hypgo/pkg/config"
	"github.com/maoxiaoyue/hypgo/pkg/logger"
	"github.com/maoxiaoyue/hypgo/pkg/server"
)
func main() {
	// 1. 讀取配置
	cfg, _ := config.LoadConfig("config.yaml")
	// 2. 初始化 Logger
	logInstance, _ := logger.New("info", "stdout", nil, true)
	// 3. 建立伺服器實例
	srv := server.New(cfg, logInstance)
	// 4. 定義路由 (取得內建的 Router)
	r := srv.Router()
	r.GET("/api/ping", func(c *context.Context) {
		c.String(200, "pong")
	})
	// 5. 啟動伺服器 (會阻塞直到收到關閉訊號)
	if err := srv.Start(); err != nil {
		log.Fatalf("伺服器發生錯誤: %v", err)
	}
}

配置範例

server:
 addr: ":443"
 protocol: "auto" # 支援 http1, http2, http3, auto
 graceful_restart: true # 監聽重啟訊號 (Unix only)
 tls:
 enabled: true # 若是 http3 或 auto 這裡必須是 true
 cert_file: "/path/to/cert.pem"
 key_file: "/path/to/key.pem"

自訂路由與中間件結合

r := srv.Router()
// 掛載全域中間件
r.Use(middleware.Logger(middleware.LoggerConfig{}))
// 掛載靜態檔案
r.Static("/public", "./assets")
// 自訂 404 處理器(委派給 Router)
srv.NotFound(func(c *context.Context) {
	c.String(404, "Page Not Found!")
})
// 自訂 405 處理器(委派給 Router)
srv.MethodNotAllowed(func(c *context.Context) {
	c.String(405, "Method Not Allowed!")
})

三協議架構設計

HTTP/1.1 (startHTTP1)

HTTP/2 (startHTTP2WithFallback)

HTTP/3 (startHTTP3)

Auto Protocol

Client → TCP → HTTP/1.1 or HTTP/2 (via ALPN)
Client → UDP → HTTP/3 (via Alt-Svc header upgrade)

TLS 安全設計

統一 Cipher Suites

var strongCipherSuites = []uint16{
 tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
 tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
 tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,
 tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
 tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
 tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
}

0-RTT Session Cache(防 Replay Attack)

// SessionCache 特性:
// - maxSize = 10,000 條目(防止記憶體耗盡 DoS)
// - TTL = 24 小時(過期自動淘汰)
// - LRU 淘汰:超過上限時移除最舊條目
// - GetAndDelete 原子操作:防止 race window replay attack

證書載入

Graceful Shutdown

並行 Shutdown

// Shutdown 內部行為:
// 1. shuttingDown.Store(true) ← atomic,無競態
// 2. listener.Close() ← 停止接受新連線
// 3. 並行:httpServer.Shutdown(ctx) + h3Server.Close()
// 4. close(shutdownChan) ← 通知 graceful restart goroutine 退出

Graceful Restart(Unix)

1. 收到 SIGUSR2
2. Fork 新進程(傳遞 listener FD)
3. Poll 等待新進程就緒(每 200ms ×ばつ 15 次 = 3 秒)
4. 舊進程 Shutdown(30 秒 timeout)
5. 移除 PID 檔案 → Exit

shuttingDown 競態防護

// 寫入(Shutdown 時)
s.shuttingDown.Store(true)
// 讀取(Health 檢查)
if s.shuttingDown.Load() { ... }

Project Manifest(AI 協作)

m := srv.Manifest()
manifest.WriteYAML(os.Stdout, m)
manifest.SaveToFile(".hyp/manifest.yaml", m, "yaml")

version: "1.0"
framework: HypGo
server:
 addr: ":8080"
 protocol: http2
 tls: true
routes:
 - method: POST
 path: /api/users
 handler_names: [controllers.CreateUser]
 summary: "建立使用者"
 tags: [users]
 input_type: CreateUserRequest
 output_type: UserResponse
database:
 driver: postgres
 has_replicas: true

hyp context # YAML 到 stdout
hyp context -f json # JSON 格式
hyp context -o manifest.yaml # 儲存到檔案

AutoSync 自動同步