fix: defer automatic uploads while device synchronization is pending

pigway_frame_flow/api/app.py

@@ -126,7 +126,7 @@ def create_app(settings=None, start_worker=True):
     app = FastAPI(
         title="PIGWay Frame Flow API",
         docs_url=None,
-        version="0.1.22",
+        version="0.1.23",
         lifespan=lifespan,
         responses=error_responses,
     )
@@ -1040,7 +1040,7 @@ def create_app(settings=None, start_worker=True):
                     supports_upload=True,
                 ),
             ],
-            version="0.1.22",
+            version="0.1.23",
             mock=settings.mock,
             write_enabled=settings.write_enabled,
             api_key_configured=bool(settings.api_key)

pigway_frame_flow/display/recovery.py

@@ -74,6 +74,51 @@ class RecoveryMonitor:
             row["requires_manual_review"] = row["state"] == "manual_review"
         return row
 
+    def observe_device(self, op, *, device=None, error=None):
+        row = self.db.one("SELECT result FROM operations WHERE id=?", (op["id"],))
+        result = json.loads(row["result"] or "{}")
+        observation = {"checked_at": now_iso()}
+        if device is not None:
+            observation.update(
+                image_id=device.current_content.id,
+                synced=device.current_content.synced,
+                online=device.status == "online",
+                heartbeat=device.last_seen_at,
+            )
+        else:
+            observation["read_error"] = {
+                "code": error.code,
+                **{
+                    k: v
+                    for k, v in error.details.items()
+                    if k
+                    in ("transport_error", "http_status", "attempts", "retry_exhausted")
+                },
+            }
+        samples = result.get("sync_observations", [])
+        if samples:
+            old = samples[-1]
+            changed = {k: v for k, v in old.items() if k != "checked_at"} != {
+                k: v for k, v in observation.items() if k != "checked_at"
+            }
+            if (
+                not changed
+                and (
+                    datetime.now(UTC) - datetime.fromisoformat(old["checked_at"])
+                ).total_seconds()
+                < 60
+            ):
+                return observation
+        samples.append(observation)
+        result["sync_observations"] = (
+            [samples[0], *samples[-11:]] if len(samples) > 12 else samples
+        )
+        # Evidence must not reset updated_at: that is the sync timeout's clock.
+        self.db.execute(
+            "UPDATE operations SET result=? WHERE id=?", (encode(result), op["id"])
+        )
+        return observation
+
     def close_superseded_displays(self):
         for op in self.db.all(
             "SELECT * FROM operations WHERE action='display' AND write_started=1 "

pigway_frame_flow/display/service.py

@@ -174,7 +174,7 @@ class DisplayService:
         if result:
             row = self.db.one("SELECT result FROM operations WHERE id=?", (id,))
             previous = json.loads(row["result"]) if row and row["result"] else {}
-            for key in ("photo_attempts", "upload_intent"):
+            for key in ("photo_attempts", "upload_intent", "sync_observations"):
                 if key in previous:
                     result = {**result, key: previous[key]}
         self.db.execute(
@@ -519,6 +519,23 @@ class DisplayService:
                     continue
                 payload = json.loads(op["payload"])
                 if op["action"] == "display":
+                    if op["client_id"] in (
+                        "scheduler",
+                        "scheduler-retry",
+                    ) and self.db.one(
+                        "SELECT id FROM operations WHERE device_id=? AND action='display' "
+                        "AND status='SYNCING' AND write_started=1 AND updated_at>? LIMIT 1",
+                        (
+                            op["device_id"],
+                            (
+                                datetime.now(UTC)
+                                - timedelta(seconds=self.settings.sync_timeout)
+                            ).isoformat(),
+                        ),
+                    ):
+                        # Upload activates a new image upstream. Give the prior
+                        # image its existing confirmation window before replacing it.
+                        continue
                     priority = payload["options"]["priority"]
                     top = self.top(op["device_id"])
                     if top and priority < top["priority"]:
@@ -823,6 +840,7 @@ class DisplayService:
             try:
                 driver = self.registry.get(op["device_id"])
                 device = driver.device(refresh=True)
+                self.recovery.observe_device(op, device=device)
                 if intent:
                     expected = self.upload_reconciliation.check(op, driver, device)
                     if (
@@ -850,7 +868,8 @@ class DisplayService:
                         if device.current_content.id == expected
                         else "target_mismatch",
                     )
-            except FlowError:
+            except FlowError as exc:
+                self.recovery.observe_device(op, error=exc)
                 self.recovery.observe(op, "read_unavailable")
             except Exception:
                 # Bad vendor metadata for one operation must not stop the worker.
@@ -858,6 +877,7 @@ class DisplayService:
         for op in self.db.all("SELECT * FROM operations WHERE status='SYNCING'"):
             try:
                 device = self.registry.get(op["device_id"]).device()
+                observation = self.recovery.observe_device(op, device=device)
                 target = json.loads(op["result"])["image_id"]
                 if (
                     device.current_content.id == target
@@ -878,11 +898,11 @@ class DisplayService:
                             "code": E.WRITE_RESULT_UNKNOWN,
                             "message": "Frame refresh was not confirmed",
                             "request_id": op["request_id"],
-                            "details": {},
+                            "details": {"last_device_observation": observation},
                         },
                     )
-            except FlowError:
-                pass
+            except FlowError as exc:
+                self.recovery.observe_device(op, error=exc)
 
         self.recovery.close_superseded_displays()
 

pigway_frame_flow/models.py

@@ -366,7 +366,7 @@ class SettingsView(BaseModel):
 
 class Health(BaseModel):
     status: str
-    version: str = "0.1.22"
+    version: str = "0.1.23"
 
 
 class Readiness(BaseModel):
@@ -397,7 +397,7 @@ class RestoreRequest(StrictModel):
 
 class Version(BaseModel):
     product: str = "PIGWay Frame Flow"
-    version: str = "0.1.22"
+    version: str = "0.1.23"
     api_version: str = "v1"
     commit: str = "development"
     build_time: str = "unknown"

pigway_frame_flow/web/index.html

@@ -1,3 +1,3 @@
 <!doctype html>
 <html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover"><meta name="color-scheme" content="light dark"><title>PIGWay Frame Flow</title><link rel="stylesheet" href="/ui/style.css"></head>
-<body><aside class="sidebar"><a class="brand" href="/"><span>PIGWay Frame Flow<small>Smart Frame Automation</small></span></a><nav id="nav"></nav><div class="sidebar-bottom"><small>Version 0.1.22</small></div></aside><div class="workspace"><header><div><span class="eyebrow">PIGWay Frame Flow</span><h1 id="page-title"></h1></div><div class="toolbar"><select id="device" aria-label="Device"></select><button id="lang" class="icon-button" aria-label="Change language">EN</button><button id="theme" class="icon-button" aria-label="Change theme">◐</button></div></header><main id="main"></main><footer id="footer"></footer></div><div id="toast" role="status" aria-live="polite"></div><dialog id="modal"><div id="modal-content"></div></dialog><script src="/ui/i18n.js?v=0.1.22"></script><script src="/ui/features.js?v=0.1.22"></script><script src="/ui/extensions.js?v=0.1.22"></script><script src="/ui/app.js?v=0.1.22"></script></body></html>
+<body><aside class="sidebar"><a class="brand" href="/"><span>PIGWay Frame Flow<small>Smart Frame Automation</small></span></a><nav id="nav"></nav><div class="sidebar-bottom"><small>Version 0.1.23</small></div></aside><div class="workspace"><header><div><span class="eyebrow">PIGWay Frame Flow</span><h1 id="page-title"></h1></div><div class="toolbar"><select id="device" aria-label="Device"></select><button id="lang" class="icon-button" aria-label="Change language">EN</button><button id="theme" class="icon-button" aria-label="Change theme">◐</button></div></header><main id="main"></main><footer id="footer"></footer></div><div id="toast" role="status" aria-live="polite"></div><dialog id="modal"><div id="modal-content"></div></dialog><script src="/ui/i18n.js?v=0.1.23"></script><script src="/ui/features.js?v=0.1.23"></script><script src="/ui/extensions.js?v=0.1.23"></script><script src="/ui/app.js?v=0.1.23"></script></body></html>