merge(app): land the search target model

This commit is contained in:
2026-10-22 02:33:31 +01:00
2 changed files with 528 additions and 0 deletions
@@ -0,0 +1,310 @@
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:<id>`, `pipeline:<id>:v<version>`,
/// `run:<id>`, `run:<id>:<sequence>`, `run:<id>:<sequence>:<field>` 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/<run>/<step>/<name>`); 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<String, dynamic>? _payload(JsonMap hit, String key) {
final value = hit[key];
return value is Map ? Map<String, dynamic>.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;
}
@@ -0,0 +1,218 @@
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/core/api_gateway.dart';
import 'package:pipelines_app/features/search/domain/search_target.dart';
JsonMap pipelineHit([JsonMap overrides = const {}]) => {
'kind': 'pipeline',
'target': 'pipeline:7',
'pipeline': {
'id': 7,
'name': 'release',
'version': 3,
'stages': 4,
...overrides,
},
};
JsonMap versionHit([JsonMap overrides = const {}]) => {
'kind': 'version',
'target': 'pipeline:9:v2',
'version': {
'pipeline_id': 9,
'version': 2,
'content_hash': 'abc',
'created_at': '2026-01-01T00:00:00Z',
...overrides,
},
};
JsonMap runHit([JsonMap overrides = const {}]) => {
'kind': 'run',
'target': 'run:11',
'run': {
'id': 11,
'pipeline_name': 'release',
'status': 'succeeded',
...overrides,
},
};
JsonMap stepHit([JsonMap overrides = const {}]) => {
'kind': 'step',
'target': 'run:11:4',
'step': {
'run_id': 11,
'sequence': 4,
'stage': 'builder',
'visit': 2,
'outcome': 'success',
...overrides,
},
};
JsonMap fieldHit([JsonMap overrides = const {}]) => {
'kind': 'field',
'target': 'run:11:4:output',
'matched_field': 'output',
'field': {
'run_id': 11,
'sequence': 4,
'field': 'output',
'snippet': 'the release is ready',
...overrides,
},
};
JsonMap artifactHit([JsonMap overrides = const {}]) => {
'kind': 'artifact',
'target': '/artifacts/11/4/notes.md',
'artifact': {
'run_id': 11,
'sequence': 4,
'name': 'notes.md',
'content_type': 'text/markdown',
'size_bytes': 2048,
'url': '/artifacts/11/4/notes.md',
...overrides,
},
};
SearchTarget resolved(JsonMap hit) {
final resolution = searchTargetFor(hit);
expect(resolution, isA<ResolvedSearchTarget>(), reason: '$hit');
return (resolution as ResolvedSearchTarget).target;
}
UnresolvedSearchTarget unresolved(JsonMap hit) {
final resolution = searchTargetFor(hit);
expect(resolution, isA<UnresolvedSearchTarget>(), reason: '$hit');
return resolution as UnresolvedSearchTarget;
}
void main() {
test('every recorded hit kind serialises back to its server token', () {
final pipeline = resolved(pipelineHit());
expect(pipeline, isA<SearchPipelineTarget>());
expect((pipeline as SearchPipelineTarget).pipelineId, 7);
expect(pipeline.kind, SearchTargetKind.pipeline);
expect(pipeline.wire, pipelineHit()['target']);
final version = resolved(versionHit());
expect(version, isA<SearchVersionTarget>());
expect((version as SearchVersionTarget).pipelineId, 9);
expect(version.version, 2);
expect(version.wire, versionHit()['target']);
final run = resolved(runHit());
expect(run, isA<SearchRunTarget>());
expect((run as SearchRunTarget).runId, 11);
expect(run.wire, runHit()['target']);
final step = resolved(stepHit());
expect(step, isA<SearchStepTarget>());
expect((step as SearchStepTarget).runId, 11);
expect(step.sequence, 4);
expect(step.stage, 'builder');
expect(step.visit, 2);
expect(step.wire, stepHit()['target']);
final field = resolved(fieldHit());
expect(field, isA<SearchFieldTarget>());
expect((field as SearchFieldTarget).runId, 11);
expect(field.sequence, 4);
expect(field.field, 'output');
expect(field.wire, fieldHit()['target']);
final artifact = resolved(artifactHit());
expect(artifact, isA<SearchArtifactTarget>());
expect((artifact as SearchArtifactTarget).url, '/artifacts/11/4/notes.md');
expect(artifact.runId, 11);
expect(artifact.sequence, 4);
expect(artifact.wire, artifactHit()['target']);
});
test('a payload without its identity is reported as unresolvable', () {
expect(unresolved({}).reason, 'no recorded target payload');
expect(unresolved(pipelineHit({'id': null})).reason, contains('pipeline'));
expect(
unresolved(versionHit({'pipeline_id': 9, 'version': 0})).reason,
contains('version'),
);
expect(unresolved(runHit({'id': 0})).reason, contains('run'));
expect(
unresolved(stepHit({'run_id': 11, 'sequence': 0})).reason,
contains('step'),
);
expect(
unresolved(fieldHit({'run_id': 11, 'sequence': 4, 'field': ' '})).reason,
contains('field'),
);
expect(unresolved(artifactHit({'url': ' '})).reason, contains('artifact'));
expect(
unresolved({'kind': 'future_kind', 'target': 'widget:7'}).reason,
'no recorded target payload',
);
});
test('a hit without a matching recorded token is unresolvable', () {
expect(
unresolved({
'kind': 'run',
'run': {'id': 11},
}).reason,
'recorded target is missing',
);
expect(
unresolved({...pipelineHit(), 'target': 'pipeline:8'}).reason,
contains('does not match'),
);
expect(
unresolved({...stepHit(), 'target': 'run:11:5'}).reason,
contains('does not match'),
);
});
test('a serialised target parses back to the same identity', () {
final targets = <SearchTarget>[
resolved(pipelineHit()),
resolved(versionHit()),
resolved(runHit()),
resolved(stepHit()),
resolved(fieldHit()),
resolved(artifactHit()),
];
for (final target in targets) {
final parsed = SearchTarget.fromWire(target.wire);
expect(parsed, target, reason: target.wire);
expect(parsed!.wire, target.wire, reason: target.wire);
}
// The token names the visit's run and sequence, not its stage/visit facts.
final step = resolved(stepHit()) as SearchStepTarget;
final parsed = SearchTarget.fromWire(step.wire) as SearchStepTarget;
expect(parsed, step);
expect(parsed.stage, isNull);
expect(parsed.visit, isNull);
});
test('a token outside the server vocabulary names no target', () {
for (final token in const [
'',
' ',
'widget:7',
'pipeline:0',
'pipeline:7:v0',
'run:11:0',
'run:11:4:',
'http://example.test/not-an-artifact',
]) {
expect(SearchTarget.fromWire(token), isNull, reason: token);
}
expect(SearchTarget.fromWire('run:11'), const SearchRunTarget(11));
expect(
SearchTarget.fromWire('pipeline:7:v2'),
const SearchVersionTarget(7, 2),
);
expect(SearchTarget.fromWire('pipeline:7'), const SearchPipelineTarget(7));
});
}