Files
pipelines/app/lib/application/app_route.dart
T
alan 767643d991 Open the run's artifact from notifications
Phone and browser notifications that carry an artifact open it full
screen in the artifact viewer, with an Open run action and the preview as
expanded text; pipelines://artifact deep links route to the viewer.
2026-11-12 18:56:26 +00:00

268 lines
8.7 KiB
Dart

part 'app_route_codec.dart';
/// The destinations the app has a URL for.
///
/// The set mirrors [AppDestination] but stays free of widget imports so the
/// parser and serialiser can be exercised without a Flutter host.
enum AppRouteKind {
pipelines,
runs,
chat,
search,
settings,
templates,
schedules,
artifact,
}
/// One page route: a destination plus the detail, pane and query it opens.
///
/// The URL vocabulary mirrors `web/src/routes.js`:
///
/// /pipelines Pipelines list
/// /pipelines/:id pipeline detail, latest version
/// /pipelines/:id/:version pipeline detail at a version
/// /pipelines/:id[/:version]/stage/:key definition stage pane
/// /runs Runs list (optional ?pipeline=)
/// /runs/:id run detail (optional ?action=decide)
/// /runs/:id/stage/:key[?visit=N] one visit's stage pane
/// /templates[/:key] template gallery / detail
/// /settings/templates[/:key] aliases for the template routes
/// /chat[/:id], /search, /settings unchanged destinations
///
/// Only the two stage panes are deep-linkable; other in-page state stays out
/// of the URL. Unknown query parameters are ignored, and an invalid `visit`,
/// `action` or `pipeline` value is dropped rather than failing the route.
///
/// Parsing is total: an unknown or malformed path resolves to the default
/// Pipelines list instead of throwing, and the serialiser is its inverse for
/// every route the app can produce.
class AppRoute {
const AppRoute(
this.kind, {
this.runId,
this.chatSessionId,
this.pipelineId,
this.version = 0,
this.stageKey,
this.visit,
this.decide = false,
this.templateKey,
this.artifactSequence,
this.artifactPath,
this.artifactPathEncoded,
this.artifactUrl,
this.artifactName,
this.artifactMediaType,
});
static const pipelines = AppRoute(AppRouteKind.pipelines);
static const runs = AppRoute(AppRouteKind.runs);
static const chat = AppRoute(AppRouteKind.chat);
static const search = AppRoute(AppRouteKind.search);
static const settings = AppRoute(AppRouteKind.settings);
/// The template gallery, reached from Settings. It is a Settings sub-page,
/// not a fifth tab, so Back returns to Settings.
static const templates = AppRoute(AppRouteKind.templates);
/// The saved-schedule list, a Settings sub-page on `/schedules`.
static const schedules = AppRoute(AppRouteKind.schedules);
static AppRoute artifact(
int runId,
int sequence,
String path, {
String? url,
String? name,
String? mediaType,
}) => _validId(runId) == null || sequence < 0 || path.isEmpty
? runs
: AppRoute(
AppRouteKind.artifact,
runId: runId,
artifactSequence: sequence,
artifactPath: path,
artifactPathEncoded: _encodeArtifactPath(path),
artifactUrl: url,
artifactName: name,
artifactMediaType: mediaType,
);
static const run = _RunRouteFactory();
/// One chat session, or the chat list when [id] is not a session id.
static AppRoute chatSession(String id) => isChatSessionId(id)
? AppRoute(AppRouteKind.chat, chatSessionId: id)
: chat;
/// A pipeline detail; [version] 0 is the latest published version.
static AppRoute pipeline(int id, {int version = 0}) => _validId(id) == null
? pipelines
: AppRoute(
AppRouteKind.pipelines,
pipelineId: id,
version: _latest(version),
);
/// The definition pane's stage [stageKey] for pipeline [id].
static AppRoute pipelineStage(int id, String stageKey, {int version = 0}) =>
_validId(id) == null || stageKey.isEmpty
? pipelines
: AppRoute(
AppRouteKind.pipelines,
pipelineId: id,
version: _latest(version),
stageKey: stageKey,
);
/// The Runs list filtered to one pipeline.
static AppRoute runsForPipeline(int pipelineId) =>
_validId(pipelineId) == null
? runs
: AppRoute(AppRouteKind.runs, pipelineId: pipelineId);
/// One template's detail page, or the gallery for an empty [key].
static AppRoute template(String key) => key.isEmpty
? templates
: AppRoute(AppRouteKind.templates, templateKey: key);
final AppRouteKind kind;
/// The run shown by the Runs destination, or null for the list. When
/// [stageKey] is also set, this is the run whose stage pane is open.
final int? runId;
/// The chat session shown by the Chat destination, or null for the list.
final String? chatSessionId;
/// The pipeline shown by the Pipelines destination, or the pipeline the Runs
/// list is filtered to. Null is the unfiltered list.
final int? pipelineId;
/// The pipeline version for [pipelineId]; 0 is the latest.
final int version;
/// The stage pane's key, for a pipeline definition or a run visit.
final String? stageKey;
/// The zero-based visit index for a run's [stageKey], or null when absent.
final int? visit;
/// Whether a run detail opens its decision prompt (`?action=decide`).
final bool decide;
/// The template whose detail page is open, or null for the gallery.
final String? templateKey;
final int? artifactSequence;
final String? artifactPath;
final String? artifactPathEncoded;
final String? artifactUrl;
final String? artifactName;
final String? artifactMediaType;
/// The path the app writes into history for this route.
String get path => _routePath(this);
/// Parses a browser pathname (or a full URL) into a route.
///
/// `/runs/abc`, `/pipelines/0` and other malformed details are the default
/// route, matching the web parser; `/pipelines/` and other trailing slashes
/// are normalised.
static AppRoute parse(String location) => _parseRoute(location);
/// A chat session id is nonempty, bounded and URL-safe, matching the web
/// parser. Anything else is malformed rather than a stale session the
/// destination has to guess about.
static bool isChatSessionId(String value) =>
value.isNotEmpty &&
value.length <= 200 &&
RegExp(r'^[A-Za-z0-9_-]+$').hasMatch(value);
@override
bool operator ==(Object other) =>
other is AppRoute &&
other.kind == kind &&
other.runId == runId &&
other.chatSessionId == chatSessionId &&
other.pipelineId == pipelineId &&
other.version == version &&
other.stageKey == stageKey &&
other.visit == visit &&
other.decide == decide &&
other.templateKey == templateKey &&
other.artifactSequence == artifactSequence &&
other.artifactPath == artifactPath &&
other.artifactUrl == artifactUrl &&
other.artifactName == artifactName &&
other.artifactMediaType == artifactMediaType;
@override
int get hashCode => Object.hash(
kind,
runId,
chatSessionId,
pipelineId,
version,
stageKey,
visit,
decide,
templateKey,
artifactSequence,
artifactPath,
artifactUrl,
artifactName,
artifactMediaType,
);
@override
String toString() => path;
}
/// Chooses what an already-selected Chats tab should show when it is tapped
/// again. A detail route is left alone; only the list can use the retained
/// workspace route, and an absent/invalid retained route stays at the list.
AppRoute? chatRouteForRetap(
AppRoute current,
AppRoute? retainedWorkspace, {
bool Function(String sessionId)? isValidSession,
}) {
if (current.kind != AppRouteKind.chat || current.chatSessionId != null) {
return current.kind == AppRouteKind.chat ? current : null;
}
final retained = retainedWorkspace;
return retained != null &&
retained.kind == AppRouteKind.chat &&
retained.chatSessionId != null &&
retained.chatSessionId!.isNotEmpty &&
(isValidSession == null || isValidSession(retained.chatSessionId!))
? retained
: null;
}
/// `AppRoute.run(3)` reads better than a constructor named after a field.
class _RunRouteFactory {
const _RunRouteFactory();
AppRoute call(int id) => _validId(id) == null
? AppRoute.runs
: AppRoute(AppRouteKind.runs, runId: id);
/// One visit's stage pane; [visit] is zero-based and omitted when null.
AppRoute stage(int id, String stageKey, {int? visit}) =>
_validId(id) == null || stageKey.isEmpty
? AppRoute.runs
: AppRoute(
AppRouteKind.runs,
runId: id,
stageKey: stageKey,
visit: _nonNegative(visit),
);
/// A run detail with its decision prompt open.
AppRoute decide(int id) => _validId(id) == null
? AppRoute.runs
: AppRoute(AppRouteKind.runs, runId: id, decide: true);
}