// Package research serves the shared, public paper corpus. Account data and // private collections do not belong to these anonymous read-only endpoints. package research import ( "context" "database/sql" "encoding/json" "errors" "net/http" "net/url" "regexp" "strconv" "strings" "time" "unicode/utf8" ) // Source 描述公开来源链接及其外部标识,不含内部数据库记录 ID。 type Source struct { Label string `json:"label"` URL string `json:"url"` ExternalID string `json:"externalId"` } // Publication 是一次投稿的出版信息与最新决策证据;同一论文可对应多个投稿。 type Publication struct { Venue string `json:"venue"` Year int `json:"year"` Track string `json:"track"` Status string `json:"status"` EvidenceURL string `json:"evidenceUrl,omitempty"` } // Paper 是公开 API 的论文投影;可空字段保留源数据缺省语义,ID 用字符串避免前端整数精度丢失。 type Paper struct { ID string `json:"id"` Title string `json:"title"` Abstract *string `json:"abstract"` Authors []string `json:"authors"` PublishedAt *string `json:"publishedAt"` Topics []string `json:"topics"` Sources []Source `json:"sources"` Publications []Publication `json:"publications,omitempty"` DOI *string `json:"doi,omitempty"` Journal *string `json:"journal,omitempty"` Comments *string `json:"comments,omitempty"` } // Filters 由 parseFilters 验证;Cursor 是相同查询下的排序锚点,不是页码或 OFFSET。 type Filters struct { Query string SearchIn string Topic string Sort string Cursor string PageSize int } // Page 同时返回当前项、双向游标和语料主题列表;无后续页面的方向使用空字符串。 type Page struct { Items []Paper `json:"items"` NextCursor string `json:"nextCursor"` PreviousCursor string `json:"previousCursor"` Topics []string `json:"topics"` PageSize int `json:"pageSize"` } // Repository implementations must use a read-only transaction for each List, // so its metadata and page describe the same database snapshot. // Repository 将 HTTP 与存储解耦;List 的列表及元数据必须来自同一只读快照。 type Repository interface { List(context.Context, Filters) (Page, error) Get(context.Context, int64) (Paper, error) } // service 共享公开仓库和项目白名单,以 slots 对整个研究 API 限制并发数据库请求。 type service struct { repository Repository projects map[string]string slots chan struct{} timeout time.Duration } // Register adds only GET endpoints; no credentials or database errors are sent // to anonymous callers. A nil repository leaves the existing server unchanged. // Register 由 main 调用;没有研究库配置时不挂载路径,项目认证数据不参与公开语料查询。 func Register(mux *http.ServeMux, repository Repository, projects map[string]string) { if repository == nil { return } s := &service{repository: repository, projects: projects, slots: make(chan struct{}, 2), timeout: 8 * time.Second} mux.HandleFunc("GET /projects/{project}/research/papers", s.serve) mux.HandleFunc("GET /projects/{project}/research/papers/{id}", s.serve) } // reply 统一公开 JSON 的缓存和内容嗅探策略,写出后不再向调用方返回编码错误。 func reply(w http.ResponseWriter, status int, value any) { w.Header().Set("Content-Type", "application/json") w.Header().Set("Cache-Control", "no-store") w.Header().Set("X-Content-Type-Options", "nosniff") w.WriteHeader(status) _ = json.NewEncoder(w).Encode(value) } // reject 仅公开稳定错误码,数据库结构和底层错误内容不进入响应。 func reject(w http.ResponseWriter, status int, code string) { reply(w, status, map[string]string{"error": code}) } // 主题采用受限分类标识,正整数不接受符号或前导零,简化 ID 和页大小的解析。 var topicPattern = regexp.MustCompile(`^[A-Za-z][A-Za-z0-9.-]{0,79}$`) var positiveInteger = regexp.MustCompile(`^[1-9][0-9]*$`) // parseFilters 严格拒绝重复/未知参数;限制查询字数、词数和页大小后,再验证游标绑定。 func parseFilters(raw string) (Filters, error) { f := Filters{SearchIn: "text", Sort: "recent", PageSize: 8} values, err := url.ParseQuery(raw) if err != nil { return f, err } invalid := errors.New("invalid query") for key, value := range values { if len(value) != 1 { return f, invalid } switch key { case "q": if !utf8.ValidString(value[0]) || utf8.RuneCountInString(value[0]) > 200 || len(strings.Fields(value[0])) > 20 || strings.ContainsRune(value[0], 0) { return f, invalid } f.Query = strings.TrimSpace(value[0]) case "searchIn": if value[0] != "text" && value[0] != "author" { return f, invalid } f.SearchIn = value[0] case "topic": if value[0] != "" && !topicPattern.MatchString(value[0]) { return f, invalid } f.Topic = value[0] case "sort": if value[0] != "recent" && value[0] != "title" { return f, invalid } f.Sort = value[0] case "cursor": f.Cursor = value[0] case "pageSize": if !positiveInteger.MatchString(value[0]) { return f, invalid } n, err := strconv.Atoi(value[0]) if err != nil || n > 50 { return f, invalid } f.PageSize = n default: return f, invalid } } _, err = decodeCursor(f) return f, err } // serve 在昂贵查询前验证项目与参数;详情不接受筛选参数,列表使用统一 Filters。 func (s *service) serve(w http.ResponseWriter, r *http.Request) { if _, exists := s.projects[r.PathValue("project")]; !exists { reject(w, 404, "not_found") return } var filters Filters var id int64 var err error if value := r.PathValue("id"); value != "" { if !positiveInteger.MatchString(value) || r.URL.RawQuery != "" { reject(w, 400, "invalid_request") return } id, err = strconv.ParseInt(value, 10, 64) } else { filters, err = parseFilters(r.URL.RawQuery) } if err != nil { reject(w, 400, "invalid_request") return } // 无空闲槽位时立即返回 429,不排队积累匿名查询;defer 覆盖后续所有退出路径。 select { case s.slots <- struct{}{}: defer func() { <-s.slots }() default: w.Header().Set("Retry-After", "1") reject(w, 429, "research_busy") return } ctx, cancel := context.WithTimeout(r.Context(), s.timeout) defer cancel() var result any if id != 0 { result, err = s.repository.Get(ctx, id) } else { result, err = s.repository.List(ctx, filters) } if err == nil { reply(w, 200, result) return } // SQLSTATE 57014 是数据库取消查询;与请求超时统一映射 504,其余依赖故障为 503。 var state interface{ SQLState() string } switch { case errors.Is(err, sql.ErrNoRows): reject(w, 404, "not_found") case errors.Is(ctx.Err(), context.DeadlineExceeded), errors.Is(err, context.DeadlineExceeded), errors.As(err, &state) && state.SQLState() == "57014": reject(w, 504, "research_timeout") default: reject(w, 503, "research_unavailable") } }