feat(api): support optional systemInfo in submissions

Extend the submission contract to accept a `systemInfo` object and persist it with each submission, including deep-copy support for `extra` metadata. Also update client-facing docs and HTTP examples (JSON and multipart) and document that the schema is available at `GET /api/schema`, so clients can reliably implement the updated payload format.feat(api): support optional systemInfo in submissions Extend the submission contract to accept a `systemInfo` object and persist it with each submission, including deep-copy support for `extra` metadata. Also update client-facing docs and HTTP examples (JSON and multipart) and document that the schema is available at `GET /api/schema`, so clients can reliably implement the updated payload format.
2026-04-17 13:57:55 +03:00
parent d2be2276ec
commit 03b4b55927
8 changed files with 630 additions and 23 deletions
--- a/lib/model/submission.go
+++ b/lib/model/submission.go
@@ -39,6 +39,30 @@ type CPUCoreDescriptor struct {
 	Type       int `json:"Type"`
 }

+type SystemInfo struct {
+	Hostname      string         `json:"hostname,omitempty"`
+	OSName        string         `json:"osName,omitempty"`
+	OSVersion     string         `json:"osVersion,omitempty"`
+	Distro        string         `json:"distro,omitempty"`
+	KernelVersion string         `json:"kernelVersion,omitempty"`
+	KernelArch    string         `json:"kernelArch,omitempty"`
+	Architecture  string         `json:"architecture,omitempty"`
+	Locale        string         `json:"locale,omitempty"`
+	Timezone      string         `json:"timezone,omitempty"`
+	Region        string         `json:"region,omitempty"`
+	Country       string         `json:"country,omitempty"`
+	City          string         `json:"city,omitempty"`
+	ISP           string         `json:"isp,omitempty"`
+	SessionID     string         `json:"sessionID,omitempty"`
+	UserID        string         `json:"userID,omitempty"`
+	ClientVersion string         `json:"clientVersion,omitempty"`
+	AppVersion    string         `json:"appVersion,omitempty"`
+	IPAddress     string         `json:"ipAddress,omitempty"`
+	ForwardedFor  string         `json:"forwardedFor,omitempty"`
+	UserAgent     string         `json:"userAgent,omitempty"`
+	Extra         map[string]any `json:"extra,omitempty"`
+}
+
 type CoreResult struct {
 	LogicalID  int     `json:"logicalID"`
 	CoreType   string  `json:"coreType"`
@@ -58,10 +82,11 @@ type BenchmarkResult struct {
 }

 type Submission struct {
-	SubmissionID string    `json:"submissionID"`
-	Submitter    string    `json:"submitter"`
-	Platform     string    `json:"platform"`
-	SubmittedAt  time.Time `json:"submittedAt"`
+	SubmissionID string      `json:"submissionID"`
+	Submitter    string      `json:"submitter"`
+	Platform     string      `json:"platform"`
+	SubmittedAt  time.Time   `json:"submittedAt"`
+	SystemInfo   *SystemInfo `json:"systemInfo,omitempty"`
 	BenchmarkResult
 }

@@ -158,6 +183,16 @@ func CloneSubmission(submission *Submission) *Submission {
 	if len(submission.CPUInfo.SupportedFeatures) > 0 {
 		copySubmission.CPUInfo.SupportedFeatures = append([]string(nil), submission.CPUInfo.SupportedFeatures...)
 	}
+	if submission.SystemInfo != nil {
+		copySystemInfo := *submission.SystemInfo
+		if len(submission.SystemInfo.Extra) > 0 {
+			copySystemInfo.Extra = make(map[string]any, len(submission.SystemInfo.Extra))
+			for key, value := range submission.SystemInfo.Extra {
+				copySystemInfo.Extra[key] = value
+			}
+		}
+		copySubmission.SystemInfo = &copySystemInfo
+	}

 	return &copySubmission
 }
--- a/lib/store/store.go
+++ b/lib/store/store.go
@@ -66,12 +66,13 @@ func (s *Store) Count() int {
 	return len(s.orderedIDs)
 }

-func (s *Store) SaveSubmission(result model.BenchmarkResult, submitter, platform string) (*model.Submission, error) {
+func (s *Store) SaveSubmission(result model.BenchmarkResult, submitter, platform string, systemInfo *model.SystemInfo) (*model.Submission, error) {
 	submission := &model.Submission{
 		SubmissionID:    uuid.NewString(),
 		Submitter:       model.NormalizeSubmitter(submitter),
 		Platform:        model.NormalizePlatform(platform),
 		SubmittedAt:     time.Now().UTC(),
+		SystemInfo:      cloneSystemInfo(systemInfo),
 		BenchmarkResult: result,
 	}

@@ -97,6 +98,22 @@ func (s *Store) SaveSubmission(result model.BenchmarkResult, submitter, platform
 	return model.CloneSubmission(submission), nil
 }

+func cloneSystemInfo(info *model.SystemInfo) *model.SystemInfo {
+	if info == nil {
+		return nil
+	}
+
+	copyInfo := *info
+	if len(info.Extra) > 0 {
+		copyInfo.Extra = make(map[string]any, len(info.Extra))
+		for key, value := range info.Extra {
+			copyInfo.Extra[key] = value
+		}
+	}
+
+	return &copyInfo
+}
+
 func (s *Store) ListSubmissions(page, pageSize int) ([]model.Submission, int) {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
--- a/lib/web/app.go
+++ b/lib/web/app.go
@@ -7,6 +7,7 @@ import (
 	"io"
 	"log"
 	"mime"
+	"net"
 	"net/http"
 	"net/url"
 	"os"
@@ -59,8 +60,9 @@ type jsonSubmissionEnvelope struct {
 }

 type flatSubmissionEnvelope struct {
-	Submitter string `json:"submitter"`
-	Platform  string `json:"platform"`
+	Submitter  string            `json:"submitter"`
+	Platform   string            `json:"platform"`
+	SystemInfo *model.SystemInfo `json:"systemInfo,omitempty"`
 	model.BenchmarkResult
 }

@@ -105,6 +107,7 @@ func (a *App) Routes() http.Handler {

 	router.Get("/", a.handleIndex)
 	router.Get("/healthz", a.handleHealth)
+	router.Get("/api/schema", a.handleSubmitSchema)
 	router.Get("/api/search", a.handleSearch)
 	router.Post("/api/submit", a.handleSubmit)

@@ -328,6 +331,10 @@ func (a *App) handleHealth(w http.ResponseWriter, _ *http.Request) {
 	})
 }

+func (a *App) handleSubmitSchema(w http.ResponseWriter, r *http.Request) {
+	http.ServeFileFS(w, r, os.DirFS("."), "docs/submit-schema.json")
+}
+
 func (a *App) handleSearch(w http.ResponseWriter, r *http.Request) {
 	results := a.store.SearchSubmissions(
 		r.URL.Query().Get("text"),
@@ -344,7 +351,7 @@ func (a *App) handleSearch(w http.ResponseWriter, r *http.Request) {
 func (a *App) handleSubmit(w http.ResponseWriter, r *http.Request) {
 	r.Body = http.MaxBytesReader(w, r.Body, maxSubmissionBytes)

-	result, submitter, platform, err := parseSubmissionRequest(r)
+	result, submitter, platform, systemInfo, err := parseSubmissionRequest(r)
 	if err != nil {
 		writeJSON(w, http.StatusBadRequest, errorResponse{Error: err.Error()})
 		return
@@ -361,7 +368,9 @@ func (a *App) handleSubmit(w http.ResponseWriter, r *http.Request) {
 		return
 	}

-	submission, err := a.store.SaveSubmission(result, submitter, platform)
+	systemInfo = enrichSystemInfo(systemInfo, r)
+
+	submission, err := a.store.SaveSubmission(result, submitter, platform, systemInfo)
 	if err != nil {
 		writeJSON(w, http.StatusInternalServerError, errorResponse{Error: fmt.Sprintf("store submission: %v", err)})
 		return
@@ -376,11 +385,11 @@ func (a *App) handleSubmit(w http.ResponseWriter, r *http.Request) {
 	})
 }

-func parseSubmissionRequest(r *http.Request) (model.BenchmarkResult, string, string, error) {
+func parseSubmissionRequest(r *http.Request) (model.BenchmarkResult, string, string, *model.SystemInfo, error) {
 	contentType := r.Header.Get("Content-Type")
 	mediaType, _, err := mime.ParseMediaType(contentType)
 	if err != nil && contentType != "" {
-		return model.BenchmarkResult{}, "", "", fmt.Errorf("parse content type: %w", err)
+		return model.BenchmarkResult{}, "", "", nil, fmt.Errorf("parse content type: %w", err)
 	}

 	switch mediaType {
@@ -389,14 +398,14 @@ func parseSubmissionRequest(r *http.Request) (model.BenchmarkResult, string, str
 	case "multipart/form-data":
 		return parseMultipartSubmission(r)
 	default:
-		return model.BenchmarkResult{}, "", "", fmt.Errorf("unsupported content type %q", mediaType)
+		return model.BenchmarkResult{}, "", "", nil, fmt.Errorf("unsupported content type %q", mediaType)
 	}
 }

-func parseJSONSubmission(r *http.Request) (model.BenchmarkResult, string, string, error) {
+func parseJSONSubmission(r *http.Request) (model.BenchmarkResult, string, string, *model.SystemInfo, error) {
 	body, err := io.ReadAll(r.Body)
 	if err != nil {
-		return model.BenchmarkResult{}, "", "", fmt.Errorf("read request body: %w", err)
+		return model.BenchmarkResult{}, "", "", nil, fmt.Errorf("read request body: %w", err)
 	}

 	submitter := firstNonEmpty(
@@ -412,6 +421,10 @@ func parseJSONSubmission(r *http.Request) (model.BenchmarkResult, string, string
 	if err := json.Unmarshal(body, &nested); err == nil {
 		submitter = firstNonEmpty(nested.Submitter, submitter)
 		platform = firstNonEmpty(nested.Platform, platform)
+		systemInfo, err := extractSystemInfo(body)
+		if err != nil {
+			return model.BenchmarkResult{}, "", "", nil, err
+		}
 		for _, candidate := range []struct {
 			name    string
 			payload json.RawMessage
@@ -426,37 +439,42 @@ func parseJSONSubmission(r *http.Request) (model.BenchmarkResult, string, string

 			var result model.BenchmarkResult
 			if err := json.Unmarshal(candidate.payload, &result); err != nil {
-				return model.BenchmarkResult{}, "", "", fmt.Errorf("decode %s JSON: %w", candidate.name, err)
+				return model.BenchmarkResult{}, "", "", nil, fmt.Errorf("decode %s JSON: %w", candidate.name, err)
 			}

-			return result, submitter, platform, nil
+			return result, submitter, platform, systemInfo, nil
 		}
 	}

 	var flat flatSubmissionEnvelope
 	if err := json.Unmarshal(body, &flat); err != nil {
-		return model.BenchmarkResult{}, "", "", fmt.Errorf("decode benchmark JSON: %w", err)
+		return model.BenchmarkResult{}, "", "", nil, fmt.Errorf("decode benchmark JSON: %w", err)
 	}

-	return flat.BenchmarkResult, firstNonEmpty(flat.Submitter, submitter), firstNonEmpty(flat.Platform, platform, "windows"), nil
+	return flat.BenchmarkResult, firstNonEmpty(flat.Submitter, submitter), firstNonEmpty(flat.Platform, platform, "windows"), cloneSystemInfo(flat.SystemInfo), nil
 }

-func parseMultipartSubmission(r *http.Request) (model.BenchmarkResult, string, string, error) {
+func parseMultipartSubmission(r *http.Request) (model.BenchmarkResult, string, string, *model.SystemInfo, error) {
 	if err := r.ParseMultipartForm(maxSubmissionBytes); err != nil {
-		return model.BenchmarkResult{}, "", "", fmt.Errorf("parse multipart form: %w", err)
+		return model.BenchmarkResult{}, "", "", nil, fmt.Errorf("parse multipart form: %w", err)
 	}

 	payload, err := readMultipartPayload(r)
 	if err != nil {
-		return model.BenchmarkResult{}, "", "", err
+		return model.BenchmarkResult{}, "", "", nil, err
 	}

 	var result model.BenchmarkResult
 	if err := json.Unmarshal(payload, &result); err != nil {
-		return model.BenchmarkResult{}, "", "", fmt.Errorf("decode benchmark JSON: %w", err)
+		return model.BenchmarkResult{}, "", "", nil, fmt.Errorf("decode benchmark JSON: %w", err)
 	}

-	return result, r.FormValue("submitter"), firstNonEmpty(r.FormValue("platform"), "windows"), nil
+	systemInfo, err := parseMultipartSystemInfo(r)
+	if err != nil {
+		return model.BenchmarkResult{}, "", "", nil, err
+	}
+
+	return result, r.FormValue("submitter"), firstNonEmpty(r.FormValue("platform"), "windows"), systemInfo, nil
 }

 func readMultipartPayload(r *http.Request) ([]byte, error) {
@@ -486,6 +504,99 @@ func readMultipartPayload(r *http.Request) ([]byte, error) {
 	return nil, fmt.Errorf("multipart request must include benchmark JSON in a file field or text field named benchmark")
 }

+func extractSystemInfo(body []byte) (*model.SystemInfo, error) {
+	var envelope struct {
+		SystemInfo *model.SystemInfo `json:"systemInfo"`
+	}
+	if err := json.Unmarshal(body, &envelope); err != nil {
+		return nil, fmt.Errorf("decode systemInfo JSON: %w", err)
+	}
+
+	return cloneSystemInfo(envelope.SystemInfo), nil
+}
+
+func parseMultipartSystemInfo(r *http.Request) (*model.SystemInfo, error) {
+	raw := strings.TrimSpace(r.FormValue("systemInfo"))
+	if raw == "" {
+		return nil, nil
+	}
+
+	var info model.SystemInfo
+	if err := json.Unmarshal([]byte(raw), &info); err != nil {
+		return nil, fmt.Errorf("decode systemInfo JSON: %w", err)
+	}
+
+	return &info, nil
+}
+
+func enrichSystemInfo(info *model.SystemInfo, r *http.Request) *model.SystemInfo {
+	if info == nil {
+		info = &model.SystemInfo{}
+	} else {
+		info = cloneSystemInfo(info)
+	}
+
+	if host, _, err := net.SplitHostPort(r.RemoteAddr); err == nil {
+		info.IPAddress = firstNonEmpty(info.IPAddress, host)
+	} else {
+		info.IPAddress = firstNonEmpty(info.IPAddress, r.RemoteAddr)
+	}
+
+	info.ForwardedFor = firstNonEmpty(info.ForwardedFor, r.Header.Get("X-Forwarded-For"))
+	info.UserAgent = firstNonEmpty(info.UserAgent, r.UserAgent())
+	info.Locale = firstNonEmpty(info.Locale, r.Header.Get("Accept-Language"))
+
+	if isEmptySystemInfo(info) {
+		return nil
+	}
+
+	return info
+}
+
+func isEmptySystemInfo(info *model.SystemInfo) bool {
+	if info == nil {
+		return true
+	}
+
+	return strings.TrimSpace(info.Hostname) == "" &&
+		strings.TrimSpace(info.OSName) == "" &&
+		strings.TrimSpace(info.OSVersion) == "" &&
+		strings.TrimSpace(info.Distro) == "" &&
+		strings.TrimSpace(info.KernelVersion) == "" &&
+		strings.TrimSpace(info.KernelArch) == "" &&
+		strings.TrimSpace(info.Architecture) == "" &&
+		strings.TrimSpace(info.Locale) == "" &&
+		strings.TrimSpace(info.Timezone) == "" &&
+		strings.TrimSpace(info.Region) == "" &&
+		strings.TrimSpace(info.Country) == "" &&
+		strings.TrimSpace(info.City) == "" &&
+		strings.TrimSpace(info.ISP) == "" &&
+		strings.TrimSpace(info.SessionID) == "" &&
+		strings.TrimSpace(info.UserID) == "" &&
+		strings.TrimSpace(info.ClientVersion) == "" &&
+		strings.TrimSpace(info.AppVersion) == "" &&
+		strings.TrimSpace(info.IPAddress) == "" &&
+		strings.TrimSpace(info.ForwardedFor) == "" &&
+		strings.TrimSpace(info.UserAgent) == "" &&
+		len(info.Extra) == 0
+}
+
+func cloneSystemInfo(info *model.SystemInfo) *model.SystemInfo {
+	if info == nil {
+		return nil
+	}
+
+	copyInfo := *info
+	if len(info.Extra) > 0 {
+		copyInfo.Extra = make(map[string]any, len(info.Extra))
+		for key, value := range info.Extra {
+			copyInfo.Extra[key] = value
+		}
+	}
+
+	return &copyInfo
+}
+
 func parsePositiveInt(raw string, fallback int) int {
 	if raw == "" {
 		return fallback