Skip Vestaboard/TRMNL pushes when WSDOT data is unavailable

When WSDOT's terminalsailingspace feed times out or returns empty, both the
next-departure time and the drive-up space count go missing (they come from
that one endpoint), so a scheduled push would flip the board to
"BAIN-SEA --" / "SPACES: N/A" — or a blank "--" TRMNL screen.

push_vestaboard_target() and push_trmnl_target() now detect this blackout via
_ferry_data_is_stale() and return {"skipped": reason} without sending. The
scheduler leaves last_push untouched on a skip, so the device keeps its last
good content and retries next tick; the WSDOT fetch is cached (~5 min) so
retries don't hammer the API, and it pushes again as soon as real data
returns. "Stale" means BOTH the departure time and spaces are missing — a real
departure with an unknown space count still pushes. A manual "Push now" during
an outage reports "Skipped — WSDOT data unavailable" instead of blanking the
display. ferry_merge_variables() is left unguarded so the polling/JSON API
still returns data.

Verified against a live WSDOT blackout (the feed was empty at the time): the
push skipped with send called 0 times, and a good read still sends. 28 tests
pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: cdibona

CLAUDE.md

@@ -99,6 +99,19 @@ minutes (default 3) *before* our quiet window's start time, and ferry pushes sto
 same early moment so nothing overwrites the goodnight. `_in_quiet_hours()` implements the
 shift; the wake time is not shifted.
 
+When WSDOT glitches, the `terminalsailingspace` fetch times out or returns empty, and since
+both the departure list and the space counts come from that one endpoint, the board would
+flip to `BAIN-SEA --` / `SPACES: N/A`. `push_vestaboard_target()` guards against this with
+`_ferry_data_is_stale()` and returns `{"skipped": reason}` instead of sending; the scheduler
+then leaves `last_push` untouched so the board keeps its last good message and retries next
+tick (fetch is cached ~5 min, so retries don't hammer WSDOT). "Stale" for a routed board
+means **both** the next departure and the spaces count are missing — a real departure with an
+unknown space count still pushes. Note `fetch_ferry_status` caches even a partial (space-fetch
+-failed) read, so a glitch persists in-app for up to the cache TTL after WSDOT recovers.
+`push_trmnl_target()` has the same guard (a blackout would push a blank `--` TRMNL screen);
+`ferry_merge_variables()` itself is left unguarded because the polling/JSON API should still
+return data.
+
 A board can override the built-in layout with `board['template']` — a sandboxed Jinja
 template, one rendered line per board row (`LEFT | RIGHT` splits a row, anything else
 centers). Two gotchas: the env uses `trim_blocks`/`lstrip_blocks` so an `{% if %}` on its

README.md

@@ -114,6 +114,13 @@ the exact start time can be swallowed and leave the ferry layout up all night. F
 pushes stop at the same early moment, so nothing overwrites the goodnight. Set the lead
 to 0 to fire exactly at the start time.
 
+**Glitch-resistant pushes.** If a WSDOT read comes back empty (its data feed drops out
+briefly), a scheduled push would otherwise flip the display to `-- / SPACES: N/A` (or a blank
+`--` TRMNL screen). Instead the push is skipped and the device keeps its last good content;
+the scheduler retries on the next tick and updates as soon as real data returns. This covers
+both Vestaboard and TRMNL. A manual **Push now** during an outage reports "Skipped — WSDOT
+data unavailable" rather than blanking the display.
+
 **Custom board layouts.** Under **Advanced** in the board editor, a template can replace
 the built-in Vestaboard layout without touching the code. One rendered line per board row;
 a line containing `|` splits into left- and right-aligned halves, everything else is

web/app.py

@@ -1452,7 +1452,8 @@ def _trmnl_mk(template: str) -> str:
             try {
                 const r = await fetch(siteBase() + '/api/push/vestaboard/' + encodeURIComponent(id), { method: 'POST' });
                 const d = await r.json();
-                setStatus('vbDot', 'vbStatus', 'vbTime', d.error ? 'error' : 'success', d.error || 'Pushed to ' + b.name);
+                if (d.skipped) setStatus('vbDot', 'vbStatus', 'vbTime', 'error', 'Skipped — ' + d.skipped + ' (board unchanged)');
+                else setStatus('vbDot', 'vbStatus', 'vbTime', d.error ? 'error' : 'success', d.error || 'Pushed to ' + b.name);
             } catch (e) { setStatus('vbDot', 'vbStatus', 'vbTime', 'error', 'Error: ' + e.message); }
             finally { btn.disabled = false; loadScheduleStatus(); }
         }
@@ -1543,7 +1544,8 @@ def _trmnl_mk(template: str) -> str:
             try {
                 const r = await fetch(siteBase() + '/api/push/trmnl/' + encodeURIComponent(id), { method: 'POST' });
                 const j = await r.json();
-                setStatus('trmnlDot', 'trmnlStatus', 'trmnlTime', j.error ? 'error' : 'success', j.error || 'Pushed to ' + d.name);
+                if (j.skipped) setStatus('trmnlDot', 'trmnlStatus', 'trmnlTime', 'error', 'Skipped — ' + j.skipped + ' (screen unchanged)');
+                else setStatus('trmnlDot', 'trmnlStatus', 'trmnlTime', j.error ? 'error' : 'success', j.error || 'Pushed to ' + d.name);
             } catch (e) { setStatus('trmnlDot', 'trmnlStatus', 'trmnlTime', 'error', 'Error: ' + e.message); }
             finally { btn.disabled = false; loadScheduleStatus(); }
         }
@@ -2569,11 +2571,40 @@ def send_to_trmnl(webhook_url: str, merge_variables: Dict[str, Any]) -> Dict[str
         return {"error": f"Failed to send to TRMNL: {str(e)}"}
 
 
+def _ferry_data_is_stale(data: Dict[str, Any], status: Optional[Dict[str, Any]]) -> bool:
+    """
+    True when a WSDOT read came back with nothing worth showing, so a push
+    would just flip the board to a blank "-- / SPACES: N/A" state.
+
+    This happens when the ``terminalsailingspace`` fetch times out or returns
+    empty (both the departure list and the space counts come from that one
+    endpoint), or on a hard fetch error. Callers skip the push and leave the
+    board's last good message sitting until WSDOT recovers.
+    """
+    if data is None or data.get("error"):
+        return True
+    if status is not None:
+        # Routed board: only stale when BOTH the next departure and the space
+        # count are missing — the exact "BAIN-SEA --" + "SPACES: N/A" blackout.
+        # A real departure with an unknown space count still pushes.
+        return status.get("departure_time") is None and status.get("spaces") is None
+    # Route-less board (vessel-list layout): need a vessel or a space count.
+    has_vessel = any(v.get("VesselName") for v in data.get("vessels", []))
+    return not (has_vessel or data.get("terminal_spaces"))
+
+
 def push_vestaboard_target(board: Dict[str, Any], wsdot_key: Optional[str] = None) -> Dict[str, Any]:
-    """Fetch ferry data for a saved board's route/direction and push to it."""
+    """
+    Fetch ferry data for a saved board's route/direction and push to it.
+
+    Returns ``{"skipped": reason}`` without sending when WSDOT data is
+    unavailable, so a glitchy read never overwrites the board's last update.
+    """
     route = board.get("route") or None
     data = fetch_ferry_status(route, api_key=wsdot_key)
     status = compute_direction_status(data, route, board.get("direction")) if route else None
+    if _ferry_data_is_stale(data, status):
+        return {"skipped": data.get("error") or "WSDOT data unavailable"}
     formatted = format_ferry_data(data)
     characters = format_vestaboard_message(formatted, status, model=board.get("model", "flagship"),
                                            template=board.get("template"))
@@ -2605,8 +2636,20 @@ def push_sleep_message(board: Dict[str, Any]) -> Dict[str, Any]:
 
 
 def push_trmnl_target(device: Dict[str, Any], wsdot_key: Optional[str] = None) -> Dict[str, Any]:
-    """Fetch ferry data for a TRMNL device's route/direction and push via webhook."""
-    mv = ferry_merge_variables(device.get("route") or None, device.get("direction"), wsdot_key)
+    """
+    Fetch ferry data for a TRMNL device's route/direction and push via webhook.
+
+    Like the Vestaboard path, returns ``{"skipped": reason}`` without sending
+    when WSDOT data is unavailable, so a glitch doesn't push a blank "--" screen.
+    (The fetch is cached, so the read here and inside ferry_merge_variables share
+    one WSDOT call.)
+    """
+    route = device.get("route") or None
+    data = fetch_ferry_status(route, api_key=wsdot_key)
+    status = compute_direction_status(data, route, device.get("direction")) if route else None
+    if _ferry_data_is_stale(data, status):
+        return {"skipped": data.get("error") or "WSDOT data unavailable"}
+    mv = ferry_merge_variables(route, device.get("direction"), wsdot_key)
     return send_to_trmnl(device.get("webhook_url"), mv)
 
 
@@ -3243,13 +3286,20 @@ def _save_state(state: Dict[str, Any]) -> None:
             logger.warning(f"Could not persist schedule state: {e}")
 
 
+def _result_message(result: Dict[str, Any]) -> str:
+    """Human-readable one-liner for a push result (error / skipped / sent)."""
+    if result.get("skipped"):
+        return f"skipped: {result['skipped']}"
+    return result.get("error") or result.get("status") or "sent"
+
+
 def _record_push(kind: str, target_id: str, result: Dict[str, Any]) -> None:
     """Record the outcome of a push for the admin status view (UTC timestamp)."""
     state = _load_state()
     state.setdefault(kind, {})[target_id] = {
         "last_push": datetime.now(timezone.utc).isoformat(),
         "ok": "error" not in result,
-        "message": result.get("error") or result.get("status") or "sent",
+        "message": _result_message(result),
     }
     _save_state(state)
 
@@ -3360,7 +3410,7 @@ def _scheduler_tick() -> None:
     def _finish_push(entry, result):
         entry["last_push"] = now.isoformat()
         entry["ok"] = "error" not in result
-        entry["message"] = result.get("error") or result.get("status") or "sent"
+        entry["message"] = _result_message(result)
 
     for board in settings["vestaboard"]["boards"]:
         sch = board.get("schedule") or {}
@@ -3414,11 +3464,19 @@ def _finish_push(entry, result):
             reasons = (reasons or []) + ["wake"]
 
         if do_push:
-            logger.info(f"Scheduled push -> Vestaboard '{board['name']}' ({mode}{': ' + ','.join(reasons) if reasons else ''})")
-            _finish_push(entry, push_vestaboard_target(board, wsdot))
-            if observed is not None:
-                entry["pushed_spaces"] = observed["spaces"]
-                entry["observed_docked"] = observed["docked"]
+            result = push_vestaboard_target(board, wsdot)
+            if result.get("skipped"):
+                # WSDOT data unavailable: leave the board's last message sitting
+                # and don't advance last_push, so we retry and push once it's back.
+                logger.info(f"Skipped Vestaboard '{board['name']}' — {result['skipped']}; keeping last message")
+                entry["ok"] = True
+                entry["message"] = _result_message(result)
+            else:
+                logger.info(f"Scheduled push -> Vestaboard '{board['name']}' ({mode}{': ' + ','.join(reasons) if reasons else ''})")
+                _finish_push(entry, result)
+                if observed is not None:
+                    entry["pushed_spaces"] = observed["spaces"]
+                    entry["observed_docked"] = observed["docked"]
             dirty = True
 
     for dev in settings["trmnl"]["devices"]:
@@ -3432,8 +3490,14 @@ def _finish_push(entry, result):
         else:
             do_push = _interval_due(entry, sch.get("interval_min", 15), TRMNL_MIN_INTERVAL_MIN, now)
         if do_push:
-            logger.info(f"Scheduled push -> TRMNL '{dev['name']}' ({mode})")
-            _finish_push(entry, push_trmnl_target(dev, wsdot))
+            result = push_trmnl_target(dev, wsdot)
+            if result.get("skipped"):
+                logger.info(f"Skipped TRMNL '{dev['name']}' — {result['skipped']}; keeping last screen")
+                entry["ok"] = True
+                entry["message"] = _result_message(result)
+            else:
+                logger.info(f"Scheduled push -> TRMNL '{dev['name']}' ({mode})")
+                _finish_push(entry, result)
             dirty = True
 
     if dirty:

web/test_app.py

@@ -480,8 +480,26 @@ def test_scheduler_pushes_due_targets(tmp_path):
                                    'webhook_url': 'https://usetrmnl.com/api/custom_plugins/x',
                                    'schedule': {'enabled': True, 'interval_min': 15}}]},
         })
-        with patch('app.requests.get') as mg, patch('app.requests.post') as mp:
-            gr = MagicMock(); gr.json.return_value = []; gr.raise_for_status = MagicMock(); mg.return_value = gr
+        # A real future Seattle->Bainbridge departure, so the push isn't skipped
+        # as a WSDOT blackout (see test_ferry_data_is_stale).
+        from datetime import datetime, timedelta
+        dep_ms = int((datetime.now() + timedelta(minutes=30)).timestamp() * 1000)
+        sailing_space = [{
+            "TerminalName": "Seattle",
+            "DepartingSpaces": [{
+                "Departure": f"/Date({dep_ms}-0800)/", "VesselName": "Tacoma",
+                "SpaceForArrivalTerminals": [{
+                    "TerminalName": "Bainbridge Island", "VesselName": "Tacoma",
+                    "DriveUpSpaceCount": 90, "MaxSpaceCount": 200}],
+            }],
+        }]
+
+        def _wsdot_get(url, *a, **k):
+            r = MagicMock(); r.raise_for_status = MagicMock()
+            r.json.return_value = sailing_space if "terminalsailingspace" in url else []
+            return r
+
+        with patch('app.requests.get', side_effect=_wsdot_get) as mg, patch('app.requests.post') as mp:
             pr = MagicMock(); pr.status_code = 200; pr.content = b'{}'; pr.json.return_value = {}; pr.raise_for_status = MagicMock(); mp.return_value = pr
             app._scheduler_tick()
             posts = [c.args[0] for c in mp.call_args_list]
@@ -618,6 +636,96 @@ def test_scheduler_sleeps_early_by_lead(tmp_path):
             assert sleep_m.call_count == 1 and ferry_m.call_count == 0
 
 
+@patch.dict(os.environ, {'WSDOT_API_KEY': 'test', 'FLASK_PORT': '5050'})
+def test_ferry_data_is_stale():
+    """Only the total 'no departure AND no spaces' blackout counts as stale."""
+    import app
+    routed = {'departure_time': '2026-08-02T11:30:00', 'spaces': 100}
+    assert app._ferry_data_is_stale({'terminal_departures': {'x': [1]}}, routed) is False
+    # a real departure with unknown spaces still pushes
+    assert app._ferry_data_is_stale({}, {'departure_time': '2026-08-02T11:30:00', 'spaces': None}) is False
+    # spaces known but no next departure still pushes
+    assert app._ferry_data_is_stale({}, {'departure_time': None, 'spaces': 42}) is False
+    # the blackout: both missing -> stale
+    assert app._ferry_data_is_stale({'terminal_spaces': {}}, {'departure_time': None, 'spaces': None}) is True
+    # hard fetch error -> stale
+    assert app._ferry_data_is_stale({'error': 'boom'}, routed) is True
+    # route-less board: vessels present -> not stale; nothing -> stale
+    assert app._ferry_data_is_stale({'vessels': [{'VesselName': 'Tacoma'}]}, None) is False
+    assert app._ferry_data_is_stale({'vessels': [], 'terminal_spaces': {}}, None) is True
+
+
+@patch.dict(os.environ, {'WSDOT_API_KEY': 'test', 'FLASK_PORT': '5050'})
+def test_push_skips_on_stale_wsdot():
+    """A blackout read returns skipped and never touches the board."""
+    import app
+    from datetime import datetime, timedelta
+    board = {'name': 'B', 'model': 'note', 'route': 'sea-bi', 'direction': 'Bainbridge Island', 'key': 'k'}
+    empty = {'route_id': 'sea-bi', 'vessels': [], 'terminal_spaces': {}, 'terminal_departures': {}, 'alerts': []}
+    with patch('app.fetch_ferry_status', return_value=empty), \
+         patch('app.send_to_vestaboard') as send_m:
+        result = app.push_vestaboard_target(board, 'wk')
+    assert result.get('skipped') and send_m.call_count == 0
+
+    # A good read still pushes: a real departure -> send is called, no skip.
+    good = dict(empty, terminal_departures={'Bainbridge Island': [
+        {'time': datetime.now() + timedelta(minutes=20), 'arrival': 'Seattle',
+         'vessel': 'Tacoma', 'drive_up': 90}]})
+    with patch('app.fetch_ferry_status', return_value=good), \
+         patch('app.send_to_vestaboard', return_value={'status': 'sent'}) as send_ok:
+        result = app.push_vestaboard_target(board, 'wk')
+    assert 'skipped' not in result and send_ok.call_count == 1
+
+
+@patch.dict(os.environ, {'WSDOT_API_KEY': 'test', 'FLASK_PORT': '5050'})
+def test_trmnl_push_skips_on_stale_wsdot():
+    """A blackout read skips the TRMNL webhook too, so the device keeps its screen."""
+    import app
+    dev = {'name': 'D', 'route': 'sea-bi', 'direction': 'Bainbridge Island',
+           'webhook_url': 'https://usetrmnl.com/api/custom_plugins/x'}
+    empty = {'route_id': 'sea-bi', 'vessels': [], 'terminal_spaces': {}, 'terminal_departures': {}, 'alerts': []}
+    with patch('app.fetch_ferry_status', return_value=empty), \
+         patch('app.send_to_trmnl') as send_m:
+        result = app.push_trmnl_target(dev, 'wk')
+    assert result.get('skipped') and send_m.call_count == 0
+
+
+@patch.dict(os.environ, {'WSDOT_API_KEY': 'test', 'FLASK_PORT': '5050'})
+def test_scheduler_skip_keeps_last_message_and_retries(tmp_path):
+    """When WSDOT is glitching the scheduler leaves the board and retries next tick."""
+    import app
+    from datetime import datetime, timezone, timedelta
+    with patch.object(app, 'SETTINGS_PATH', str(tmp_path / 's.json')), \
+         patch.object(app, 'SCHEDULE_STATE_PATH', str(tmp_path / 'st.json')):
+        client = app.app.test_client()
+        client.post('/api/settings', json={'wsdot_key': 'wk', 'vestaboard': {'boards': [{
+            'name': 'Hall', 'model': 'note', 'route': 'sea-bi', 'direction': 'Bainbridge Island', 'key': 'k',
+            'schedule': {'enabled': True, 'mode': 'interval', 'interval_min': 15}}]}})
+        bid = client.get('/api/settings').get_json()['vestaboard']['boards'][0]['id']
+
+        # Seed a real last push an interval ago (the scheduler's interval clock is
+        # wall-clock UTC, not _now()). This is the board's last good message.
+        first_push = (datetime.now(timezone.utc) - timedelta(hours=1)).isoformat()
+        st = app._load_state()
+        st['vestaboard'][bid] = {'last_push': first_push, 'ok': True, 'message': 'sent'}
+        app._save_state(st)
+
+        # Tick with WSDOT down: push returns skipped, board left alone.
+        with patch('app.push_vestaboard_target', return_value={'skipped': 'WSDOT data unavailable'}) as skip_m:
+            app._scheduler_tick()
+        assert skip_m.call_count == 1
+        entry = app._load_state()['vestaboard'][bid]
+        # last_push did NOT advance -> the last good message sits and it stays due.
+        assert entry['last_push'] == first_push
+        assert 'skipped' in entry['message'] and entry['ok'] is True
+
+        # Next tick: WSDOT recovers -> it pushes without waiting another interval.
+        with patch('app.push_vestaboard_target', return_value={'status': 'sent'}) as back_m:
+            app._scheduler_tick()
+        assert back_m.call_count == 1
+        assert app._load_state()['vestaboard'][bid]['last_push'] != first_push
+
+
 if __name__ == '__main__':
     print("Running basic tests...")