still-raw-2

server/api/openapi.yaml

@@ -2356,6 +2356,59 @@ paths:
         "426":
           $ref: "#/components/responses/UpgradeRequired"
 
+  /sync/conflicts:
+    parameters:
+      - $ref: "#/components/parameters/ClientVersion"
+    get:
+      operationId: listSyncConflicts
+      tags: [sync]
+      summary: Page the caller's group's conflict log, newest first (FR-093, FR-124, D4.6, A182). Member-readable.
+      security:
+        - SessionCookie: []
+        - DeviceToken: []
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 200
+            default: 50
+        - name: after
+          in: query
+          required: false
+          schema:
+            type: string
+      responses:
+        "200":
+          description: "One page of the caller's group's conflict log, newest first. An empty log is `conflicts: []`."
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SyncConflictLogResponse"
+              example:
+                conflicts:
+                  - id: 0a6f1c2e-5d0b-4b1e-9a55-3c0f6b7e2d11
+                    mutation_id: 5f0d3b5e-7a4c-4e0e-8a53-1c2b9d6e4f70
+                    entity_type: item
+                    entity_id: 9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f
+                    field_name: name
+                    server_value: "\"Cordless drill\""
+                    losing_client_value: "\"Drill (18V)\""
+                    detected_at: 1788000000000
+                next_cursor: null
+        "400":
+          description: ''
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/Problem"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "426":
+          $ref: "#/components/responses/UpgradeRequired"
+
   /backup:
     parameters:
       - $ref: "#/components/parameters/ClientVersion"
@@ -4601,6 +4654,47 @@ components:
           type: integer
           format: int64
 
+    SyncConflictLogEntry:
+      type: object
+      required: [id, mutation_id, entity_type, entity_id, field_name, server_value, losing_client_value, detected_at]
+      properties:
+        id:
+          type: string
+          description: The conflict log entry's own opaque id; unique, stable, and safe as a client-side upsert key.
+        mutation_id:
+          type: [string, "null"]
+        entity_type:
+          type: string
+          description: The closed-sync-entity-set member (A7) the conflict concerns, as `SyncMutation.entity_type`.
+        entity_id:
+          type: string
+        field_name:
+          type: string
+          description: The conflicting field, or the sentinel `"_entity"` for a whole-entity conflict (A151).
+        server_value:
+          type: [string, "null"]
+        losing_client_value:
+          type: [string, "null"]
+          description: JSON text of the value the losing mutation tried to write; `null` when no snapshot was recorded.
+        detected_at:
+          type: integer
+          format: int64
+          description: Unix milliseconds (A51) at which the conflict was detected.
+
+    SyncConflictLogResponse:
+      type: object
+      description: One page of `GET /sync/conflicts`.
+      required: [conflicts, next_cursor]
+      properties:
+        conflicts:
+          type: array
+          description: Newest first. `[]` when the page is empty, never `null`.
+          items:
+            $ref: "#/components/schemas/SyncConflictLogEntry"
+        next_cursor:
+          type: [string, "null"]
+          description: Opaque cursor for the next (older) page — pass as `after` verbatim. `null` when no further page remains.
+
     ImportUploadResponse:
       type: object
       description: "`POST /import/native/upload`'s `201` body (T148c, FR-051)."

server/internal/httpapi/router.go

@@ -277,6 +277,7 @@ func mountV1(r chi.Router, cfg Config) {
 		r.Route("/sync", func(r chi.Router) {
 			r.Post("/pull", middleware.Scoped(syncPullHandler(cfg)))
 			r.Post("/push", middleware.Scoped(syncPushHandler(cfg)))
+			r.Get("/conflicts", middleware.Scoped(syncConflictsHandler(cfg)))
 		})
 	})
 

server/internal/httpapi/sync_conflicts.go

@@ -0,0 +1,89 @@
+package httpapi
+
+import (
+	"errors"
+	"github.com/ankek/Household-Objects-Dev/server/internal/httpapi/middleware"
+	"github.com/ankek/Household-Objects-Dev/server/internal/httpapi/problem"
+	"github.com/ankek/Household-Objects-Dev/server/internal/httpapi/requestid"
+	"github.com/ankek/Household-Objects-Dev/server/internal/storage"
+	"log/slog"
+	"net/http"
+	"strconv"
+)
+
+const defaultSyncConflictsLimit = 50
+
+type syncConflictLogEntryBody struct {
+	ID                string  `json:"id"`
+	MutationID        *string `json:"mutation_id"`
+	EntityType        string  `json:"entity_type"`
+	EntityID          string  `json:"entity_id"`
+	FieldName         string  `json:"field_name"`
+	ServerValue       *string `json:"server_value"`
+	LosingClientValue *string `json:"losing_client_value"`
+	DetectedAt        int64   `json:"detected_at"`
+}
+
+type syncConflictLogResponseBody struct {
+	Conflicts  []syncConflictLogEntryBody `json:"conflicts"`
+	NextCursor *string                    `json:"next_cursor"`
+}
+
+var syncConflictRepositoryFor = func(cfg Config, scope storage.Scope) (storage.PushRepository, error) {
+	if cfg.Store == nil {
+		return nil, errors.New("httpapi: sync: no storage configured")
+	}
+	return cfg.Store.ForGroupPush(scope.GroupID())
+}
+
+func syncConflictsHandler(cfg Config) middleware.ScopedHandler {
+	return func(w http.ResponseWriter, r *http.Request, scope storage.Scope) {
+		q := r.URL.Query()
+
+		limit := defaultSyncConflictsLimit
+		if v := q.Get("limit"); v != "" {
+			n, err := strconv.Atoi(v)
+			if err != nil || n < 1 || n > storage.MaxConflictPageLimit {
+				problem.Write(w, r, problem.BadRequest("limit must be an integer between 1 and "+
+					strconv.Itoa(storage.MaxConflictPageLimit)))
+				return
+			}
+			limit = n
+		}
+
+		var after *storage.ConflictCursor
+		if v := q.Get("after"); v != "" {
+			c, err := storage.DecodeConflictCursor(v)
+			if err != nil {
+				problem.Write(w, r, problem.BadRequest("after is not a valid cursor"))
+				return
+			}
+			after = &c
+		}
+
+		repo, err := syncConflictRepositoryFor(cfg, scope)
+		if err == nil {
+			var page storage.ConflictPage
+			page, err = repo.ListConflicts(r.Context(), after, limit)
+			if err == nil {
+				body := syncConflictLogResponseBody{
+					Conflicts: make([]syncConflictLogEntryBody, 0, len(page.Entries)),
+				}
+				for _, e := range page.Entries {
+					body.Conflicts = append(body.Conflicts, syncConflictLogEntryBody(e))
+				}
+				if page.Next != nil {
+					s := storage.EncodeConflictCursor(*page.Next)
+					body.NextCursor = &s
+				}
+				writeJSON(w, r, http.StatusOK, body)
+				return
+			}
+		}
+		cfg.Logger.LogAttrs(r.Context(), slog.LevelError, "sync: list conflicts failed",
+			slog.String("request_id", requestid.FromContext(r.Context())),
+			slog.String("error", err.Error()),
+		)
+		problem.Write(w, r, problem.Internal())
+	}
+}