import '../../../core/api_gateway.dart'; /// The kind of recorded entity a resolved target names. enum SearchTargetKind { pipeline, version, run, step, field, artifact } /// The exact identity behind a recorded search hit. /// /// [wire] is the server's own stable target token /// (`internal/protocol/search.go`): `pipeline:`, `pipeline::v`, /// `run:`, `run::`, `run:::` or the /// recorded artifact URL. It is derived from the typed payload, never copied /// from the hit, and [SearchTarget.fromWire] accepts it back. /// /// The token is the identity: two targets that serialise to the same token are /// the same target even when one of them also carries recorded visit facts the /// token does not encode. A hit without an identity in its payload is reported /// as [UnresolvedSearchTarget] by [searchTargetFor]; the client never guesses. sealed class SearchTarget { const SearchTarget(); SearchTargetKind get kind; /// The server's target token for this identity. String get wire; /// Parses a server target token, or null when it names no known target. /// /// A token carries only identity, so a parsed step or artifact target has no /// recorded stage/visit facts; those are payload extras, not identity. static SearchTarget? fromWire(String wire) { final token = wire.trim(); if (token.isEmpty) return null; final pipeline = RegExp( r'^pipeline:([0-9]+)(?::v([0-9]+))?$', ).firstMatch(token); if (pipeline != null) { final id = _positive(pipeline.group(1)); if (id == null) return null; final version = pipeline.group(2); if (version == null) return SearchPipelineTarget(id); final parsed = _positive(version); return parsed == null ? null : SearchVersionTarget(id, parsed); } final run = RegExp(r'^run:([0-9]+)(?::(.+))?$').firstMatch(token); if (run != null) { final runId = _positive(run.group(1)); if (runId == null) return null; final rest = run.group(2); if (rest == null) return SearchRunTarget(runId); final parts = rest.split(':'); if (parts.length > 2) return null; final sequence = _positive(parts.first); if (sequence == null) return null; if (parts.length == 1) return SearchStepTarget(runId, sequence); final field = parts.last; return field.trim().isEmpty ? null : SearchFieldTarget(runId, sequence, field); } // The server's artifact target is its own relative file URL // (`/artifacts///`); an absolute form is accepted only when // it carries that same path. if (token.startsWith('/artifacts/')) return SearchArtifactTarget(token); if (token.startsWith('http://') || token.startsWith('https://')) { final uri = Uri.tryParse(token); if (uri != null && uri.path.startsWith('/artifacts/')) { return SearchArtifactTarget(token); } } return null; } @override bool operator ==(Object other) => other is SearchTarget && other.wire == wire; @override int get hashCode => wire.hashCode; @override String toString() => wire; } /// A pipeline identity hit: the pipeline's detail, always at its latest version. final class SearchPipelineTarget extends SearchTarget { const SearchPipelineTarget(this.pipelineId); final int pipelineId; @override SearchTargetKind get kind => SearchTargetKind.pipeline; @override String get wire => 'pipeline:$pipelineId'; } /// A pipeline version hit: one exact recorded definition. final class SearchVersionTarget extends SearchTarget { const SearchVersionTarget(this.pipelineId, this.version); final int pipelineId; final int version; @override SearchTargetKind get kind => SearchTargetKind.version; @override String get wire => 'pipeline:$pipelineId:v$version'; } /// A run identity hit. final class SearchRunTarget extends SearchTarget { const SearchRunTarget(this.runId); final int runId; @override SearchTargetKind get kind => SearchTargetKind.run; @override String get wire => 'run:$runId'; } /// A recorded step/visit hit. [stage] and [visit] are the visit facts the /// payload records ([visit] is the server's visit number, not the zero-based /// pane index); the server's token only names the run and sequence. final class SearchStepTarget extends SearchTarget { const SearchStepTarget(this.runId, this.sequence, {this.stage, this.visit}); final int runId; final int sequence; final String? stage; final int? visit; @override SearchTargetKind get kind => SearchTargetKind.step; @override String get wire => 'run:$runId:$sequence'; } /// A text hit inside one recorded step field. final class SearchFieldTarget extends SearchTarget { const SearchFieldTarget(this.runId, this.sequence, this.field); final int runId; final int sequence; final String field; @override SearchTargetKind get kind => SearchTargetKind.field; @override String get wire => 'run:$runId:$sequence:$field'; } /// A recorded artifact hit. The recorded URL is the identity; [runId] and /// [sequence] locate the visit that produced it. final class SearchArtifactTarget extends SearchTarget { const SearchArtifactTarget(this.url, {this.runId, this.sequence}); final String url; final int? runId; final int? sequence; @override SearchTargetKind get kind => SearchTargetKind.artifact; @override String get wire => url; } /// Either the exact [SearchTarget] a hit names, or the reason it names none. sealed class SearchTargetResolution { const SearchTargetResolution(); } final class ResolvedSearchTarget extends SearchTargetResolution { const ResolvedSearchTarget(this.target); final SearchTarget target; } final class UnresolvedSearchTarget extends SearchTargetResolution { const UnresolvedSearchTarget(this.reason); /// Why the hit cannot be resolved, for the caller's own reporting. It is not /// operator-facing copy. final String reason; } /// Maps the typed payload of one recorded search hit to its exact identity. /// /// Payload keys are checked in the same order as the landed row model, so a hit /// resolves to the target its visible row describes. The server's recorded /// token must also be present and equal the serialised identity: a hit without /// a token is unresolvable, consistent with the landed row model marking such a /// row read-only, and a token that disagrees with its payload is refused rather /// than guessed. Unknown payloads, and a payload missing any part of its /// identity (an id, a sequence, a field name or an artifact URL), are /// [UnresolvedSearchTarget]. SearchTargetResolution searchTargetFor(JsonMap hit) { final identity = _identityFor(hit); if (identity is UnresolvedSearchTarget) return identity; final target = (identity as ResolvedSearchTarget).target; final recorded = _text(hit['target']); if (recorded == null) { return const UnresolvedSearchTarget('recorded target is missing'); } if (recorded != target.wire) { return const UnresolvedSearchTarget( 'recorded target does not match its payload', ); } return ResolvedSearchTarget(target); } SearchTargetResolution _identityFor(JsonMap hit) { final pipeline = _payload(hit, 'pipeline'); if (pipeline != null) { final id = _positive(pipeline['id']); if (id == null) { return const UnresolvedSearchTarget('pipeline identity is missing'); } return ResolvedSearchTarget(SearchPipelineTarget(id)); } final version = _payload(hit, 'version'); if (version != null) { final pipelineId = _positive(version['pipeline_id']); final number = _positive(version['version']); if (pipelineId == null || number == null) { return const UnresolvedSearchTarget('version identity is incomplete'); } return ResolvedSearchTarget(SearchVersionTarget(pipelineId, number)); } final run = _payload(hit, 'run'); if (run != null) { final id = _positive(run['id']); if (id == null) { return const UnresolvedSearchTarget('run identity is missing'); } return ResolvedSearchTarget(SearchRunTarget(id)); } final step = _payload(hit, 'step'); if (step != null) { final runId = _positive(step['run_id']); final sequence = _positive(step['sequence']); if (runId == null || sequence == null) { return const UnresolvedSearchTarget('step identity is incomplete'); } final visit = _positive(step['visit']); final stage = _text(step['stage']); return ResolvedSearchTarget( SearchStepTarget(runId, sequence, stage: stage, visit: visit), ); } final field = _payload(hit, 'field'); if (field != null) { final runId = _positive(field['run_id']); final sequence = _positive(field['sequence']); final name = _text(field['field']); if (runId == null || sequence == null || name == null) { return const UnresolvedSearchTarget('field identity is incomplete'); } return ResolvedSearchTarget(SearchFieldTarget(runId, sequence, name)); } final artifact = _payload(hit, 'artifact'); if (artifact != null) { final url = _text(artifact['url']); if (url == null) { return const UnresolvedSearchTarget('artifact url is missing'); } return ResolvedSearchTarget( SearchArtifactTarget( url, runId: _positive(artifact['run_id']), sequence: _positive(artifact['sequence']), ), ); } return const UnresolvedSearchTarget('no recorded target payload'); } Map? _payload(JsonMap hit, String key) { final value = hit[key]; return value is Map ? Map.from(value) : null; } int? _positive(Object? value) { final number = value is int ? value : value is num ? value.toInt() : int.tryParse('${value ?? ''}'); return number != null && number > 0 ? number : null; } String? _text(Object? value) { final text = '${value ?? ''}'; return text.trim().isEmpty ? null : text; }