models: parse both shapes of user_failures

[myleshorton]

What's wrong

lantern-box #286 (b2c28bb, 2026-07-09, first tagged v0.0.101) changed TagHistory.UserFailures from []time.Time to []UserFailure:

// v0.0.100 — adapter/autoselect_history.go:31
UserFailures []time.Time    `json:"user_failures,omitempty"`
// v0.0.101 — adapter/autoselect_history.go:81
UserFailures []UserFailure  `json:"user_failures,omitempty"`   // {"at": ..., "kind": ...}

So user_failures went from ["2026-07-06T12:00:00Z"] to [{"at":"2026-07-06T12:00:00Z","kind":"stall"}]. Go got back-compat for its own reads (UserFailure.UnmarshalJSON accepts both forms) — the Dart consumer didn't, and nothing tests the cross-language contract. available_servers.dart:261 still did DateTime.parse(e as String).

AvailableServers.fromJson maps over the whole list with no per-entry isolation, so one server carrying a recorded user failure throws out of the entire parse and the client is left with no server list at all.

How it reached users

The Dart cast came first and was correct when written — fc84cbe45 (#8833, 2026-06-18) added user_failures parsing three weeks before the Go side changed shape.

What broke it was the dep bump: 6d2c05c8b (#8912, 2026-07-17) moved lantern-box v0.0.100 → v0.0.103, crossing the v0.0.101 boundary. It touched go.mod and go.sum and nothing else — zero Dart files — which is exactly why nobody noticed: the breaking change is invisible in the diff, and no test covers the Go↔Dart contract.

release	lantern-box	parses?
v9.1.15-beta2 (07-13)	v0.0.100	✅
v9.1.16-beta (07-17)	v0.0.104	❌
v9.1.17-beta (07-22)	v0.0.104	❌

So 9.1.16 is affected too, not just 9.1.17. The ticket only shows 9.1.17 because that user's upgrade history goes 9.1.15 → 9.1.17 — they skipped 9.1.16 entirely.

sequenceDiagram
    autonumber
    participant UI as VPN screen<br/>available_servers_notifier.dart
    participant Svc as platform service<br/>lantern_platform_service.dart
    participant LB as lantern-box v0.0.104<br/>adapter/autoselect_history.go
    participant Model as model<br/>available_servers.dart

    Note over LB: autoselect_history.go:81 ⚠️<br/>UserFailures is []UserFailure<br/>(was []time.Time in v0.0.100)
    UI->>Svc: available_servers_notifier.dart:37<br/>getLanternAvailableServers()
    Svc->>LB: lantern_platform_service.dart:1436<br/>MethodChannel getLanternAvailableServers
    LB-->>Svc: JSON string — user_failures entries<br/>are now objects (at + kind)
    Svc->>Model: lantern_platform_service.dart:1439<br/>AvailableServers.fromJson(jsonDecode(result))
    Model->>Model: available_servers.dart:6<br/>map over all 55 servers, no per-entry isolation
    Model->>Model: available_servers.dart:138<br/>SelectionHistory.fromJson(selection_history)
    rect rgba(255, 200, 200, 0.3)
        Note over Model: available_servers.dart:261 🐛<br/>DateTime.parse(e as String)<br/>the entry is a Map, not a String
    end
    Model-->>Svc: throws — _Map is not a subtype of String in type cast
    Svc-->>UI: lantern_platform_service.dart:1446<br/>Left(Failure) — all 55 servers lost
    Note over UI: available_servers_notifier.dart:46<br/>logs and returns, so state stays stale<br/>(build() at :25 throws outright)

Loading

Evidence

Freshdesk #180591 — China, Android, 9.1.17. From that user's flutter.log:

• 9.1.17 first appears at 11:28:11.225; the first parse failure is at 11:29:43.937 — 92 seconds later, as soon as radiance recorded its first user-traffic failure.
• 339 occurrences of type '_Map<String, dynamic>' is not a subtype of type 'String' in type cast, from 11:29:43 through 16:35:40, with the stack trace naming available_servers.dart:261.
• 2329 Servers JSON: [ lines, all well-formed — the payload was fine, only the parse wasn't.

Downstream: 130 updateServerLocation: type=auto, 58 "falling back to auto", ~23 churned tags. The UI can't learn which servers exist, so it keeps re-resolving against a stale list.

Why this escaped testing: user_failures is omitempty, so a fresh upgrade parses fine; and defaultUserFailureWindow is 5 minutes, so the window empties again after five failure-free minutes. On a clean network the bug is invisible. In China it never clears.

Reproduction

The model has no imports beyond dart:core, so it runs standalone against the payload the ticket's log captured verbatim (55 servers, 2 carrying user_failures):

A  v0.0.104 shape (as shipped in 9.1.17)
    THREW — type '_Map<String, dynamic>' is not a subtype of type 'String' in type cast
B  v0.0.100 shape (list of timestamp strings)
    OK — parsed 55 servers, 33 locations
C  no user_failures recorded yet
    OK — parsed 55 servers, 33 locations

Mutating only user_failures flips the outcome, which is what makes the dependency bump causal rather than correlated. One poisoned server out of 55 is enough.

The fix

Accept both shapes, and drop entries we can't read instead of throwing:

static DateTime? _userFailureAt(dynamic entry) {
  final at = entry is Map ? entry["at"] : entry;
  return at is String ? DateTime.tryParse(at) : null;
}

entry is Map rather than Map<String, dynamic> on purpose — this has to hold if the payload ever arrives via StandardMessageCodec rather than jsonDecode, which yields Map<Object?, Object?>.

Dropping rather than throwing is the load-bearing half. userFailures has no readers anywhere in lib/ — it is parsed, defaulted, and re-serialized, nothing else. A field nobody consumes should not be able to cost the client its server list, whatever shape a future lantern-box gives it.

Tests

This model had zero fromJson coverage before now. Seven new tests; five fail without the fix:

test	fails pre-fix
parses the object form	✅
parses an object form with no kind	✅
parses a window holding both forms at once	✅
drops entries with no readable timestamp	✅
parses a list where only one server carries user_failures	✅
parses the legacy bare-timestamp form	— (guards against over-correcting)
an absent window parses as empty	— (guards the omitempty path)

The list-level test round-trips its fixture through jsonEncode/jsonDecode so element types match the platform channel's, and pre-fix it reproduces the ticket's error string exactly: type '_Map<String, dynamic>' is not a subtype of type 'String' in type cast.

Deliberately out of scope

• Per-entry isolation in AvailableServers.fromJson:6. One bad server still takes down the list for any other parse failure. Worth fixing, but it's a behavior change (partial lists) that deserves its own review.
• last_outcome_at / updated_at are never null. Go's omitempty doesn't apply to structs, so a zero time.Time marshals as 0001-01-01T00:00:00Z. The json[...] == null ? null : ... guards are dead code and toJson's if (lastOutcomeAt != null) never trips.
• A test that actually pins the Go↔Dart contract. Nothing here catches the next shape change on the Go side; that needs a fixture generated from lantern-box.

Note

test/widget_test.dart ("Counter increments smoke test") fails on origin/main as well — verified by stashing these two files and re-running. Pre-existing, untouched here.

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

User failure deserialization

Layer / File(s)	Summary
Tolerant user failure parser lib/core/models/available_servers.dart	SelectionHistory accepts legacy timestamp strings and object entries with an at field, drops unreadable entries, and documents its serialized format.
Deserialization coverage test/core/models/available_servers_test.dart	Tests cover supported formats, mixed and missing windows, invalid timestamps, and server-list parsing when only one server includes failures.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: copilot, atavism

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: supporting both legacy and new user_failures formats in the models.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fisk/fix-user-failures-parse

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Updates the Flutter/Dart AvailableServers model layer to be backward-compatible with a lantern-box JSON schema change where selection_history.user_failures entries changed from timestamp strings to {at, kind} objects, preventing a single malformed/unknown entry from breaking parsing of the entire server list.

Changes:

• Make SelectionHistory.fromJson accept both legacy string entries and the new object form for user_failures, dropping unreadable entries instead of throwing.
• Keep toJson() emitting the legacy “bare timestamp” shape for user_failures.
• Add focused unit tests covering both shapes, mixed windows, invalid entries, and a multi-server payload where only one server has user_failures.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
lib/core/models/available_servers.dart	Adds tolerant parsing for both user_failures shapes and filters invalid entries to avoid poisoning full server-list parsing.
test/core/models/available_servers_test.dart	Adds regression/unit tests for user_failures parsing across legacy/new/mixed/invalid cases and multi-server payload behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.