chore: directory migration - gateway→server, web→client/electron

2026-09-08 19:16:35 +08:00
parent fd9f99a3f9
commit f9d757b5e5
243 changed files with 5095 additions and 228 deletions
--- a/server/internal/handler/helpers.go
+++ b/server/internal/handler/helpers.go
@ -0,0 +1,410 @@
+package handler
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"reflect"
+	"strconv"
+	"strings"
+	"unicode/utf8"
+
+	"github.com/agentmail/gateway/internal/models"
+	"github.com/agentmail/gateway/internal/repo"
+)
+
+// JSON 写入 JSON 响应
+func JSON(w http.ResponseWriter, status int, data interface{}) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	json.NewEncoder(w).Encode(data)
+}
+
+// Error 写入错误响应
+func Error(w http.ResponseWriter, status int, msg string) {
+	JSON(w, status, map[string]string{"error": msg})
+}
+
+// Decode 从请求体解析 JSON。**拒绝未知字段。**
+//
+// # 为什么必须严格
+//
+// 宽容解码把「字段名写错」变成一种**静默成功**：请求返回 200，服务端却什么都
+// 没收到。生产实测过最坏的一种形状 —— homeagent 插件的 send_mail 传的是
+// `attachments: [{"attachment_id": …}]`，而服务端要的是 `attachment_ids: ["…"]`：
+//
+//	$ curl -X POST /mail/send -d '{…,"attachments":[{"attachment_id":"598f100e…"}]}'
+//	  HTTP 200  {"mail_id":"2a64fdc8…", …}
+//	$ sqlite3 "SELECT COUNT(*) FROM attachments WHERE mail_id='2a64fdc8…'"
+//	  0
+//
+// 邮件发出去了、附件一个都没带、没有任何一层报错。那个 bug 在库里活了很久 ——
+// **正因为没人会去核对一个返回 200 的请求**。
+//
+// 严格解码把它变成一个当场可见的 400。这是 `I-5`（失败必须当场可见）在
+// 请求解析层的落点：宁可让调用方收到一句「字段 X 不认识」，
+// 也不要让它以为自己传的东西生效了。
+//
+// 需要宽容的地方只有一处（心跳，见 DecodeLenient），且必须显式说明理由。
+func Decode(r *http.Request, v interface{}) error {
+	dec := json.NewDecoder(r.Body)
+	dec.DisallowUnknownFields()
+	return dec.Decode(v)
+}
+
+// DecodeLenient 解析请求体但**容忍未知字段**，同时把认不出的字段名报回来。
+//
+// 只给心跳用，理由是那条路径的职责是「我还活着」：插件比服务端新、多带了一个
+// 服务端还不认识的字段时，代价不该是整个心跳体（含会话快照与模型目录）被丢掉。
+//
+// 但**容忍不等于咽下去**。返回的 unknown 列表必须被调用方回报给插件
+// （心跳响应里的 `unknown_fields`），否则又变成一次静默忽略 —— 那正是
+// `attachments` vs `attachment_ids` 能拖那么久的原因。
+//
+// 实现上要解两遍（宽容一遍取值、严格一遍找未知字段），所以先把 body 读进内存。
+func DecodeLenient(r *http.Request, v interface{}) (unknown []string, err error) {
+	raw, err := io.ReadAll(io.LimitReader(r.Body, maxLenientBodyBytes))
+	if err != nil {
+		return nil, err
+	}
+	if len(raw) == 0 {
+		return nil, nil
+	}
+
+	// 取值这一遍必须宽容：未知字段不能让整个心跳体作废。
+	if uErr := json.Unmarshal(raw, v); uErr != nil {
+		return nil, uErr
+	}
+
+	// 再严格解一遍**只为找出未知字段**。json 每遇到一个未知字段就立即返回，
+	// 所以要循环剥：不循环的话「多带了三个字段」只会报出第一个。
+	probeType := reflect.TypeOf(v)
+	for probeType != nil && probeType.Kind() == reflect.Ptr {
+		probeType = probeType.Elem()
+	}
+	if probeType == nil {
+		return nil, nil
+	}
+	seen := map[string]bool{}
+	for i := 0; i < maxUnknownFieldsReported; i++ {
+		probe := reflect.New(probeType).Interface()
+		dec := json.NewDecoder(bytes.NewReader(raw))
+		dec.DisallowUnknownFields()
+		dErr := dec.Decode(probe)
+		if dErr == nil {
+			break
+		}
+		name := unknownFieldName(dErr)
+		// 不是未知字段错误（宽容那遍已经成功，所以这里本不应出现其他错），
+		// 或者同一个名字又出现一次 —— 都说明剥不下去了，停。
+		if name == "" || seen[name] {
+			break
+		}
+		seen[name] = true
+		unknown = append(unknown, name)
+		stripped, sErr := stripTopLevelKey(raw, name)
+		if sErr != nil {
+			break
+		}
+		raw = stripped
+	}
+	return unknown, nil
+}
+
+const (
+	// maxLenientBodyBytes 是心跳体的读取上限。会话快照 200 条 + 模型目录 300 条，
+	// 每条百来字节，2MB 有充足余量；超出的部分被截断后 json 解析会报错，
+	// 那正是我们想要的（一个畸形巨大的心跳体不该被当成有效上报）。
+	maxLenientBodyBytes = 2 << 20
+	// maxUnknownFieldsReported 是回报的未知字段数上限。
+	// 报头几个足够定位问题，无上限循环会让一个塞满垃圾键的请求变成 CPU 消耗。
+	maxUnknownFieldsReported = 8
+)
+
+// stripTopLevelKey 从一个 JSON 对象里删掉一个顶层键。
+//
+// 只动顶层：未知字段错误报的就是顶层键名。嵌套结构里的未知字段报的名字
+// 在顶层找不到，这里返回错误，循环随即停下 —— 那个字段仍会被报出来。
+func stripTopLevelKey(raw []byte, key string) ([]byte, error) {
+	var m map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &m); err != nil {
+		return nil, err
+	}
+	if _, ok := m[key]; !ok {
+		return nil, errors.New("key not at top level")
+	}
+	delete(m, key)
+	return json.Marshal(m)
+}
+
+// unknownFieldName 从 encoding/json 的未知字段错误里取出那个字段名。
+//
+// json 包没有为这种错误定义类型（返回的是 *errors.errorString），
+// 只能按文本匹配 `json: unknown field "xxx"`。
+// 匹配不上时返回空串，调用方回落到笼统文案。
+func unknownFieldName(err error) string {
+	const prefix = `json: unknown field "`
+	msg := err.Error()
+	i := strings.Index(msg, prefix)
+	if i < 0 {
+		return ""
+	}
+	rest := msg[i+len(prefix):]
+	j := strings.IndexByte(rest, '"')
+	if j < 0 {
+		return ""
+	}
+	return rest[:j]
+}
+
+// jsonFieldNames 反射列出一个请求结构体接受的 JSON 键。
+//
+// 用途是把「字段 X 不认识」补成「应为 a / b / c 之一」——
+// 少了这半句，调用方只知道自己错了，仍要去翻服务端源码才知道对的是什么。
+// 那正是 `attachments` vs `attachment_ids` 当初拖了那么久的原因。
+func jsonFieldNames(v interface{}) []string {
+	t := reflect.TypeOf(v)
+	for t != nil && t.Kind() == reflect.Ptr {
+		t = t.Elem()
+	}
+	if t == nil || t.Kind() != reflect.Struct {
+		return nil
+	}
+	out := make([]string, 0, t.NumField())
+	for i := 0; i < t.NumField(); i++ {
+		f := t.Field(i)
+		if f.PkgPath != "" {
+			continue // 非导出字段不参与 JSON
+		}
+		name := f.Tag.Get("json")
+		if idx := strings.IndexByte(name, ','); idx >= 0 {
+			name = name[:idx]
+		}
+		if name == "-" {
+			continue
+		}
+		if name == "" {
+			name = f.Name
+		}
+		out = append(out, name)
+	}
+	return out
+}
+
+// DecodeBody 解析请求体，失败时直接写 400 并返回 false。
+//
+// 与直接用 Decode 的区别是错误信息**指向具体字段**。原先 22 处调用点
+// 一律回一句固定的 "Invalid JSON"，客户端只知道「有问题」却不知道哪里有问题 ——
+// 实测踩过一次：`workspaces` 要的是 `[{name, path}]`，传字符串数组得到的
+// 就是那句固定文案，只能靠翻服务端结构体才发现。第三方客户端没有这个条件。
+func DecodeBody(w http.ResponseWriter, r *http.Request, v interface{}) bool {
+	if err := Decode(r, v); err != nil {
+		Error(w, http.StatusBadRequest, decodeErrMsg(err, v))
+		return false
+	}
+	return true
+}
+
+// decodeErrMsg 把 json 解码错误翻成一句能照着改的话。
+//
+// 刻意不回显 json 包的原文：它带 Go 的类型名（如 models.Workspace），
+// 那是本侧的实现细节，对调用方没有意义，也不该出现在公开 API 的响应里。
+func decodeErrMsg(err error, target interface{}) string {
+	if errors.Is(err, io.EOF) {
+		return "请求体为空"
+	}
+
+	// 未知字段：把认识的键一并列出来。只说「不认识 x」的话，调用方还得去翻
+	// 服务端源码才知道对的拼法 —— 而拼错字段名恰恰是最容易犯、最难自查的错
+	//（宽容解码时它连报错都没有，见 Decode 的注释）。
+	if bad := unknownFieldName(err); bad != "" {
+		msg := "不认识的字段 \"" + bad + "\""
+		if names := jsonFieldNames(target); len(names) > 0 {
+			msg += "；本端点接受：" + strings.Join(names, " / ")
+		}
+		return msg
+	}
+	// 截断的 JSON 走的不是 SyntaxError 而是 ErrUnexpectedEOF ——
+	// 不单独处理的话会落到最后那句笼统的兜底文案里
+	if errors.Is(err, io.ErrUnexpectedEOF) {
+		return "JSON 语法错误：请求体在解析完成前就结束了（可能被截断）"
+	}
+
+	var typeErr *json.UnmarshalTypeError
+	if errors.As(err, &typeErr) {
+		if typeErr.Field != "" {
+			return "字段 \"" + typeErr.Field + "\" 类型不对：期望 " +
+				jsonKindName(typeErr.Type) + "，收到 " + typeErr.Value
+		}
+		return "请求体类型不对：期望 " + jsonKindName(typeErr.Type) + "，收到 " + typeErr.Value
+	}
+
+	var syntaxErr *json.SyntaxError
+	if errors.As(err, &syntaxErr) {
+		return "JSON 语法错误（第 " + strconv.FormatInt(syntaxErr.Offset, 10) + " 字节处）"
+	}
+
+	return "请求体不是合法 JSON"
+}
+
+// jsonKindName 把 Go 类型说成 JSON 的说法。
+// 调用方写的是 JSON，用 []models.Workspace 去解释它要的是什么毫无帮助。
+func jsonKindName(t reflect.Type) string {
+	if t == nil {
+		return "未知类型"
+	}
+	switch t.Kind() {
+	case reflect.Slice, reflect.Array:
+		return jsonKindName(t.Elem()) + " 数组"
+	case reflect.Map, reflect.Struct:
+		return "object"
+	case reflect.String:
+		return "string"
+	case reflect.Bool:
+		return "boolean"
+	case reflect.Ptr:
+		return jsonKindName(t.Elem())
+	default:
+		if k := t.Kind(); k >= reflect.Int && k <= reflect.Float64 {
+			return "number"
+		}
+		return t.Kind().String()
+	}
+}
+
+// httpError 携带 HTTP 状态码的错误
+type httpError struct {
+	status int
+	msg    string
+}
+
+func (e httpError) Error() string { return e.msg }
+
+func errBadRequest(msg string) error { return httpError{http.StatusBadRequest, msg} }
+func errNotFound(msg string) error   { return httpError{http.StatusNotFound, msg} }
+func errConflict(msg string) error   { return httpError{http.StatusConflict, msg} }
+
+// errRateLimited 用于新建会话速率限制。用 429 而不是 403：
+// 前者表示「稍后再来」，后者表示「你没这个权限」——语义完全不同，
+// 客户端据此决定是重试还是放弃。
+func errRateLimited(msg string) error { return httpError{http.StatusTooManyRequests, msg} }
+
+// writeKeyErr 把 repo 层的密钥错误映射成 HTTP 响应。
+// 「已使用 / 已过期」与「无效」分开报，便于运维判断是重签还是查配置。
+func writeKeyErr(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, repo.ErrKeyUsed):
+		Error(w, http.StatusUnauthorized, "密钥已使用（一次性密钥只能用一次）")
+	case errors.Is(err, repo.ErrKeyExpired):
+		Error(w, http.StatusUnauthorized, "密钥已过期")
+	case errors.Is(err, repo.ErrKeyNotFound):
+		Error(w, http.StatusUnauthorized, "密钥无效")
+	case errors.Is(err, repo.ErrKeyTypeInvalid):
+		Error(w, http.StatusBadRequest, "密钥类型非法，应为 permanent / one_time / timed")
+	case errors.Is(err, repo.ErrKeyNeedsExpiry):
+		Error(w, http.StatusBadRequest, "timed 密钥必须给出正的 expires_hours")
+	case errors.Is(err, repo.ErrKeyTooShort):
+		Error(w, http.StatusBadRequest, "密钥太短（至少 32 位）")
+	case errors.Is(err, repo.ErrKeyTokenTaken):
+		Error(w, http.StatusConflict, "该密钥已登记过")
+	default:
+		if strings.Contains(err.Error(), "已退役") {
+			Error(w, http.StatusConflict, err.Error())
+		} else {
+			Error(w, http.StatusInternalServerError, "密钥操作失败")
+		}
+	}
+}
+
+// validateSessionAlias 校验会话别名是否可安全出现在三维地址 name@path.<alias> 的末段。
+// "new" 是寻址保留字；含 . 会让 path/session 切分歧义；含 @ 与空白同理。
+func validateSessionAlias(alias string) error {
+	if alias == "new" {
+		return errBadRequest(`会话别名不可为 "new"：该词已作为寻址保留字`)
+	}
+	if strings.ContainsAny(alias, ". \t/@") {
+		return errBadRequest("会话别名不可含 . 空白 / 或 @（会与三维地址解析冲突）")
+	}
+	return nil
+}
+
+// normalizeAlias 把 Agent 平台侧的 slug/标题改写为合法的寻址别名。
+//
+// 平台侧命名不一定遵守本侧的寻址约束（可能含 . / @ 空白），直接入库会让
+// name@path.session 切分歧义，因此非法字符统一换成 -，并压缩连续的 -。
+// 保留字 "new" 加前缀避开；全部不可用时返回空串交由调用方报错。
+func normalizeAlias(s string) string {
+	var b strings.Builder
+	lastDash := false
+	for _, r := range s {
+		switch {
+		case r == '.' || r == '/' || r == '@' || r == ' ' || r == '\t' || r == '\n' || r == '\r':
+			if !lastDash && b.Len() > 0 {
+				b.WriteByte('-')
+				lastDash = true
+			}
+		default:
+			b.WriteRune(r)
+			lastDash = false
+		}
+	}
+	out := strings.Trim(b.String(), "-")
+	if out == "new" {
+		return "session-new"
+	}
+	// VARCHAR(128) 上限，按字节截断时不能切坏多字节字符
+	const maxBytes = 128
+	if len(out) > maxBytes {
+		cut := out[:maxBytes]
+		for len(cut) > 0 && !utf8.ValidString(cut) {
+			cut = cut[:len(cut)-1]
+		}
+		out = strings.Trim(cut, "-")
+	}
+	return out
+}
+
+// writeErr 将 httpError 按其状态码写出，其余错误统一 500 + fallback 文案
+func writeErr(w http.ResponseWriter, err error, fallback string) {
+	if he, ok := err.(httpError); ok {
+		Error(w, he.status, he.msg)
+		return
+	}
+	Error(w, http.StatusInternalServerError, fallback)
+}
+
+// emptySlice 把 nil slice 转为空 JSON 数组 []
+func emptySlice[T any](s []T) []T {
+	if s == nil {
+		return []T{}
+	}
+	return s
+}
+
+// agentLimiterKey 把「这是不是 Agent 发起的」翻译成速率限制的键。
+// 人类返回空串 = 不限速（手工操作的频率天然受限）。
+func agentLimiterKey(isAgent bool, actor string) string {
+	if isAgent {
+		return actor
+	}
+	return ""
+}
+
+// validPermissionModeInput 校验人显式指定的权限档位。
+//
+// 与 repo 层的 Normalize 分工不同：**人显式传了一个认不出的档位时必须报错**，
+// 不能静默用默认档。他以为自己给了 plan，实际拿到 workspace —— 那是比报错
+// 更坏的结果（他会以为自己收紧了）。
+//
+// 而 repo 层的 Normalize 面向的是「库里的历史脏数据」与「省略该字段」，
+// 那两种情形下静默回落到默认档才是对的。
+func validPermissionModeInput(w http.ResponseWriter, mode string) bool {
+	if mode == "" || models.ValidPermissionMode(mode) {
+		return true
+	}
+	Error(w, http.StatusBadRequest,
+		"permission_mode 非法："+mode+"（应为 plan / workspace / full）")
+	return false
+}