docs: annotate Foundry source and deployment lifecycle in Chinese [skip ci]

This commit is contained in:
2026-11-16 17:52:11 +08:00
parent 30829eeb86
commit 1090591503
123 changed files with 1279 additions and 3 deletions
+12
View File
@@ -1,3 +1,4 @@
// 邮箱登录链路:注册写待验证记录和 outbox,确认链接才创建账户;登录直接校验 bcrypt。
package auth
import (
@@ -13,11 +14,14 @@ import (
"golang.org/x/crypto/bcrypt"
)
// emailAddress 统一大小写并拒绝显示名形式,只接受最多 254 字节的纯邮箱地址。
func emailAddress(value string) (string, bool) {
value = strings.ToLower(strings.TrimSpace(value))
address, err := mail.ParseAddress(value)
return value, err == nil && address.Address == value && len(value) <= 254
}
// emailBody 限制 16 KiB、拒绝未知字段及尾随 JSON;失败时已经写出 400。
func emailBody(w http.ResponseWriter, r *http.Request, input any) bool {
decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, 16384))
decoder.DisallowUnknownFields()
@@ -28,6 +32,7 @@ func emailBody(w http.ResponseWriter, r *http.Request, input any) bool {
return true
}
// rateLimit 将键摘要计入数据库十五分钟固定窗口,过期后第一次访问重新计数。
func (s *service) rateLimit(ctx context.Context, key string, limit int) (bool, error) {
var count int
err := s.db.QueryRowContext(ctx, `
@@ -40,6 +45,7 @@ RETURNING attempts
return count <= limit, err
}
// emailAction 由 project 路由调用;先限频,再以非阻塞信号量限制密码哈希占用。
func (s *service) emailAction(w http.ResponseWriter, r *http.Request, project, action string) error {
if action == "verify-email" {
return s.verifyEmail(w, r, project)
@@ -70,6 +76,7 @@ func (s *service) emailAction(w http.ResponseWriter, r *http.Request, project, a
w.Header().Set("Retry-After", "900")
return reject(w, 429, "rate_limited")
}
// 四个槽位都忙时立即返回 429,不让昂贵 bcrypt 请求无限排队。
select {
case s.passwordSlots <- struct{}{}:
defer func() { <-s.passwordSlots }()
@@ -87,6 +94,7 @@ func (s *service) emailAction(w http.ResponseWriter, r *http.Request, project, a
return err
}
passwordHash := []byte(hash)
// 不存在的账户使用启动时生成的 dummy 哈希,但无论密码比对结果如何均拒绝登录。
if missing {
passwordHash = s.dummyPassword
}
@@ -102,6 +110,8 @@ func (s *service) emailAction(w http.ResponseWriter, r *http.Request, project, a
return nil
}
// registerEmail 在邮箱级事务锁下更新三十分钟验证记录,邮件与记录共同提交。
// 已注册邮箱不写新邮件,仍返回相同 202,避免从此响应枚举账号。
func (s *service) registerEmail(w http.ResponseWriter, r *http.Request, project, email, password string) error {
hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
if err != nil {
@@ -147,6 +157,8 @@ INSERT INTO email_outbox(project,recipient,subject,body,expires_at) VALUES($1,$2
return nil
}
// verifyEmail 先定位邮箱再加同一事务锁,随后删除并返回有效记录以保证验证码一次性消费。
// 账户、邮箱凭据、会话都成功后才提交,任何失败交由 defer 回滚。
func (s *service) verifyEmail(w http.ResponseWriter, r *http.Request, project string) error {
var input struct {
Token string `json:"token"`