Files
pipelines/app/lib/application/app_route.dart
T

224 lines
7.5 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,
}
/// 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,
});
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 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;
/// 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;
@override
int get hashCode => Object.hash(
kind,
runId,
chatSessionId,
pipelineId,
version,
stageKey,
visit,
decide,
templateKey,
);
@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);
}