parse static method
Decodes raw capture bytes, normalises encoding, and validates the
schema. Returns the parsed sleuthMetadata object for convenient
downstream access; the full JSON root is recoverable via
json['sleuthMetadata']'s container.
Throws FormatException with a precise message on any violation.
The inverse-ratio half of the trace-vs-observed cross-check is
skipped when the capture's sleuthMetadata.role is 'below'.
Below-leg semantics intentionally pair a tiny expectedMagnitude.observed
(sub-threshold workload, e.g. 0.5 ms) with a normal-sized scenario
span (~250 ms including flushTimelineNow + dwell), producing
inverse-ratios well above the 100× ceiling that would otherwise
rightly catch fabricated at/above captures. Sub-threshold roles
have no markers-bracket-the-work invariant; the
_requireNoIssueTraceRecord check protects below-leg honesty.
Implementation
static Map<String, Object?> parse(List<int> rawBytes) {
final decoded = _decodeUtf8(rawBytes);
final normalised = _stripBomAndNormaliseLineEndings(decoded);
// Duplicate JSON keys are rejected before jsonDecode collapses them.
// RFC 8259 §4 permits duplicates; Dart's `jsonDecode` silently takes
// the last write. Without this check an attacker (or a well-meaning
// contributor with an editor glitch) can craft a fixture that shows
// one value to a person reading the file and certifies a different
// value to the schema validator.
_detectDuplicateKeys(normalised);
final Object? root;
try {
root = jsonDecode(normalised);
} on FormatException catch (e) {
throw FormatException('Capture is not valid JSON: ${e.message}');
}
if (root is! Map<String, Object?>) {
throw const FormatException(
'Capture root must be a JSON object, not an array or primitive.',
);
}
for (final key in requiredTopLevel) {
if (!root.containsKey(key)) {
throw FormatException(
'Missing required top-level key: "$key". '
'Expected: ${requiredTopLevel.toList()..sort()}.',
);
}
}
_validateTraceEvents(root['traceEvents']);
final sleuthMetadata = root['sleuthMetadata'];
if (sleuthMetadata is! Map<String, Object?>) {
throw const FormatException('"sleuthMetadata" must be a JSON object.');
}
for (final key in requiredMetadata) {
if (!sleuthMetadata.containsKey(key)) {
throw FormatException(
'Missing required sleuthMetadata key: "$key". '
'Expected: ${requiredMetadata.toList()..sort()}.',
);
}
}
_validateDevicePolicy(sleuthMetadata);
_validateFlutterVersion(sleuthMetadata);
_validateCaptureCommandAndScenario(sleuthMetadata);
_validateExpectedMagnitude(sleuthMetadata);
_validateCaptureDate(sleuthMetadata);
final role = sleuthMetadata['role'];
if (role is! String || !allowedRoles.contains(role)) {
throw FormatException(
'Invalid `sleuthMetadata.role`: ${role == null ? 'null' : '"$role"'}. '
'Must be exactly one of ${allowedRoles.toList()..sort()} '
'(case-sensitive). This field drives the below-leg inverse-ratio '
'bypass. A typo falls back to enforcement and shows up as a '
'false-positive failure.',
);
}
// Below-leg semantics: sub-threshold workload paired with normal-
// sized scenario span (workload + flushTimelineNow + dwell). The
// inverse-ratio half false-positives on this shape — its 100×
// ceiling is meant to catch fabricated at/above captures
// (markers bracketing unrelated work). _requireNoIssueTraceRecord
// is the actual contract for below-role honesty.
final isBelowRole = role == 'below';
_crossCheckTraceVsObserved(
root['traceEvents'] as List,
sleuthMetadata,
skipInverseRatio: isBelowRole,
);
return sleuthMetadata;
}