merge(app): land the search target model
This commit is contained in:
@@ -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));
|
||||
});
|
||||
}
|
||||
Reference in New Issue
Block a user