Files
pipelines/app/lib/application/app_route.dart
T
alan 988834ba37 feat(app): parse and emit the web client's route vocabulary
Widen AppRoute to the pipeline detail, definition stage pane, runs filter,
run stage pane, decision prompt and template detail the web client already
addresses, and canonicalise the /settings/templates aliases. The URL codec
moves to app_route_codec.dart as a part file to keep the route model and the
parser under the app's 250-line aim.
2026-10-22 03:35:43 +01:00

192 lines
6.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 }
/// 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);
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;
}
/// `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);
}