pkg/dart_runtime_service/lib/src/devtools/handler.dart - sdk.git - Git at Google

 // Copyright (c) 2026, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.

 import 'dart:async';
 import 'dart:convert';
 import 'dart:io';
 import 'dart:typed_data';

 import 'package:devtools_shared/devtools_deeplink_io.dart';
 import 'package:devtools_shared/devtools_extensions.dart';
 import 'package:devtools_shared/devtools_extensions_io.dart';
 import 'package:devtools_shared/devtools_server.dart';
 import 'package:devtools_shared/devtools_shared.dart';
 import 'package:mime/mime.dart';
 import 'package:path/path.dart' as path;
 import 'package:shelf/shelf.dart';
 import 'package:shelf_static/shelf_static.dart';
 import 'package:sse/server/sse_handler.dart';

 import 'client.dart';

 const sseKeepAlive = Duration(seconds: 30);

 /// Returns a [Handler] which handles serving DevTools and the DevTools server
 /// API.
 ///
 /// [buildDir] is the path to the pre-compiled DevTools instance to be served.
 ///
 /// [notFoundHandler] is a [Handler] to which requests that could not be handled
 /// by the DevTools handler are forwarded (e.g., a proxy to the VM
 /// service).
 ///
 /// If [appRoot] is `/` (or null), DevTools is not being served by a DDS instance
 /// and is served by a standalone server (see `package:dds/devtools_server.dart`).
 ///
 /// If DTD or its URI is null, the Dart Tooling Daemon is not available for
 /// this DevTools server connection.
 ///
 /// If DTD URI is non-null, but secret is null, then DTD was started by a
 /// client that is not the DevTools server (e.g. an IDE).
 FutureOr<Handler> defaultHandler({
   String? buildDir,
   DevToolsClientManager? clientManager,
   Handler? notFoundHandler,
   DtdInfo? dtd,
   required ExtensionsManager devtoolsExtensionsManager,
   String? appRoot,
   bool enableLogging = false,
 }) {
   appRoot ??= '/';
   if (!appRoot.endsWith('/')) {
     appRoot = '$appRoot/';
   }

   /// A wrapper around [devtoolsStaticAssetHandler] that handles serving
   /// index.html up for / and non-file requests like /memory, /inspector, etc.
   /// with the correct base href for the DevTools root.
   FutureOr<Response> devtoolsAssetHandler(Request request) {
     // To avoid hard-coding a set of page names here (or needing access to one
     // from DevTools), assume any single-segment path with no extension is a
     // DevTools page that needs to serve up index.html.
     final pathSegments = request.url.pathSegments;

     // Matches extension requests of the form
     // /devtools_extensions/<extension_identifier>/<asset_path> where
     // <extension_identifier> is the extension name and version
     // (e.g. foo_1.0.0).
     if (pathSegments case [
       extensionRequestPath,
       final extensionIdentifier,
       ...final rest,
     ]) {
       // This identifier should be the extension name appended with its version.
       final extensionAssetsLocation = devtoolsExtensionsManager
           .lookupLocationFor(extensionIdentifier);
       if (extensionAssetsLocation != null) {
         final relativePathToExtensionAsset = path.joinAll(rest);
         final assetPath = path.normalize(
           path.join(extensionAssetsLocation, relativePathToExtensionAsset),
         );
         // Ensure the normalized path is still within the expected
         // [extensionAssetsLocation] to protect against directory traversal.
         if (path.isWithin(extensionAssetsLocation, assetPath)) {
           final contentType = lookupMimeType(assetPath) ?? 'text/html';
           final baseHref =
               '$appRoot$extensionRequestPath/$extensionIdentifier/';
           return _serveStaticFile(
             request,
             File(assetPath),
             contentType,
             baseHref: baseHref,
           );
         }
         return Response.notFound(
           'Asset path is outside of extension assets location: $assetPath',
         );
       }
     }

     if (buildDir == null) {
       return Response.notFound('No build directory was specified.');
     }

     const defaultDocument = 'index.html';
     final indexFile = File(path.join(buildDir, defaultDocument));
     final isValidRootPage =
         pathSegments.isEmpty ||
         (pathSegments.length == 1 && !pathSegments[0].contains('.'));

     if (isValidRootPage) {
       return _serveStaticFile(
         request,
         indexFile,
         'text/html',
         baseHref: appRoot,
       );
     }

     // Serves the static web assets for DevTools.
     final devtoolsStaticAssetHandler = createStaticHandler(
       buildDir,
       defaultDocument: defaultDocument,
     );
     return devtoolsStaticAssetHandler(request);
   }

   // Support DevTools client-server interface via SSE.
   // Note: the handler path needs to match the full *original* path, not the
   // current request URL (we remove '/devtools' in the initial router but we
   // need to include it here).
   final devToolsSseHandlerPath = '${appRoot}api/sse';
   final devToolsApiHandler = SseHandler(
     Uri.parse(devToolsSseHandlerPath),
     keepAlive: sseKeepAlive,
   );

   clientManager ??= DevToolsClientManager(
     requestNotificationPermissions: false,
   );

   devToolsApiHandler.connections.rest.listen((sseConnection) {
     clientManager!.acceptClient(sseConnection, enableLogging: enableLogging);
   });

   FutureOr<Response> devtoolsHandler(Request request) {
     // If the request isn't of the form api/<method> assume it's a request for
     // DevTools assets.
     if (request.url.pathSegments case ['api', final method, ...]) {
       if (method == 'ping') {
         // Note: we have an 'OK' body response, otherwise the response has an
         // incorrect status code (204 instead of 200).
         return Response.ok('OK');
       }
       if (method == 'sse') {
         print('DevTools server handling SSE request: ${request.url}');
         return devToolsApiHandler.handler(request);
       }
       if (!ServerApi.canHandle(request)) {
         return Response.notFound('$method is not a valid API');
       }
       return ServerApi.handle(
         request,
         extensionsManager: devtoolsExtensionsManager,
         deeplinkManager: DeeplinkManager(),
         dtd: dtd,
       );
     }
     return devtoolsAssetHandler(request);
   }

   return (Request request) {
     if (notFoundHandler != null) {
       if (request.url.pathSegments case ['devtools', ...]) {
         // Forward all requests to /devtools/* to the DevTools handler.
         request = request.change(path: 'devtools');
       } else {
         return notFoundHandler(request);
       }
     }
     return devtoolsHandler(request);
   };
 }

 /// Serves [file] for all requests.
 ///
 /// For files with [contentType] 'text/html' and a provided [baseHref] value,
 /// any existing `<base href="">` tag will be rewritten with the provided path.
 Future<Response> _serveStaticFile(
   Request request,
   File file,
   String contentType, {
   String? baseHref,
 }) async {
   final headers = {HttpHeaders.contentTypeHeader: contentType};

   if (contentType != 'text/html') {
     late final Uint8List fileBytes;
     try {
       fileBytes = file.readAsBytesSync();
     } on PathNotFoundException catch (_) {
       // Wait a short delay, and then retry in case we have hit a race condition
       // between a static file being served and accessed. See
       // https://github.com/flutter/devtools/issues/6365.
       await Future<void>.delayed(const Duration(milliseconds: 500));
       try {
         fileBytes = file.readAsBytesSync();
       } catch (e) {
         return Response.notFound(
           'could not read file as bytes: ${request.url.path}',
         );
       }
     }
     return Response.ok(fileBytes, headers: headers);
   }

   late String contents;
   try {
     contents = file.readAsStringSync();
   } catch (e) {
     return Response.notFound(
       'could not read file as String: ${request.url.path}',
     );
   }

   if (baseHref != null) {
     assert(baseHref.startsWith('/'));
     assert(baseHref.endsWith('/'));

     // Always use a relative base href to support going through proxies that
     // rewrite paths. For example if the server thinks we are hosting at
     // `http://localhost/devtools/` but a frontend proxy means the client app
     // is at `http://localhost/proxy/1234/devtools/` then we need the base href
     // to effectively be `/proxy/1234/devtools/`, however we have no knowledge
     // of `/proxy/1234` because it was stripped by the proxy on its way to us.
     baseHref = computeRelativeBaseHref(baseHref, request.requestedUri);

     // Replace the base href to match where the app is being served from.
     final baseHrefPattern = RegExp(r'<base href="\/"\s?\/?>');
     contents = contents.replaceFirst(
       baseHrefPattern,
       '<base href="${htmlEscape.convert(baseHref)}">',
     );
   }
   return Response.ok(contents, headers: headers);
 }

 /// Computes a relative "base href" that can be used in place of
 /// [absoluteBaseHref] for a request served at [requestUri].
 String computeRelativeBaseHref(String absoluteBaseHref, Uri requestUri) {
   // path.relative will always treat `from` as if it's a directory, but for
   // URIs that's not correct. If the request is /foo/bar then `.` is `/foo` and
   // not `/foo/bar`. To handle this, trim the last segment if the request does
   // not end with a slash.
   final requestFolderPath = requestUri.path.endsWith('/')
       ? requestUri.path
       : path.posix.dirname(requestUri.path);
   return path.posix.relative(absoluteBaseHref, from: requestFolderPath);
 }
	// Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file
	// for details. All rights reserved. Use of this source code is governed by a
	// BSD-style license that can be found in the LICENSE file.

	import 'dart:async';
	import 'dart:convert';
	import 'dart:io';
	import 'dart:typed_data';

	import 'package:devtools_shared/devtools_deeplink_io.dart';
	import 'package:devtools_shared/devtools_extensions.dart';
	import 'package:devtools_shared/devtools_extensions_io.dart';
	import 'package:devtools_shared/devtools_server.dart';
	import 'package:devtools_shared/devtools_shared.dart';
	import 'package:mime/mime.dart';
	import 'package:path/path.dart' as path;
	import 'package:shelf/shelf.dart';
	import 'package:shelf_static/shelf_static.dart';
	import 'package:sse/server/sse_handler.dart';

	import 'client.dart';

	const sseKeepAlive = Duration(seconds: 30);

	/// Returns a [Handler] which handles serving DevTools and the DevTools server
	/// API.
	///
	/// [buildDir] is the path to the pre-compiled DevTools instance to be served.
	///
	/// [notFoundHandler] is a [Handler] to which requests that could not be handled
	/// by the DevTools handler are forwarded (e.g., a proxy to the VM
	/// service).
	///
	/// If [appRoot] is `/` (or null), DevTools is not being served by a DDS instance
	/// and is served by a standalone server (see `package:dds/devtools_server.dart`).
	///
	/// If DTD or its URI is null, the Dart Tooling Daemon is not available for
	/// this DevTools server connection.
	///
	/// If DTD URI is non-null, but secret is null, then DTD was started by a
	/// client that is not the DevTools server (e.g. an IDE).
	FutureOr<Handler> defaultHandler({
	String? buildDir,
	DevToolsClientManager? clientManager,
	Handler? notFoundHandler,
	DtdInfo? dtd,
	required ExtensionsManager devtoolsExtensionsManager,
	String? appRoot,
	bool enableLogging = false,
	}) {
	appRoot ??= '/';
	if (!appRoot.endsWith('/')) {
	appRoot = '$appRoot/';
	}

	/// A wrapper around [devtoolsStaticAssetHandler] that handles serving
	/// index.html up for / and non-file requests like /memory, /inspector, etc.
	/// with the correct base href for the DevTools root.
	FutureOr<Response> devtoolsAssetHandler(Request request) {
	// To avoid hard-coding a set of page names here (or needing access to one
	// from DevTools), assume any single-segment path with no extension is a
	// DevTools page that needs to serve up index.html.
	final pathSegments = request.url.pathSegments;

	// Matches extension requests of the form
	// /devtools_extensions/<extension_identifier>/<asset_path> where
	// <extension_identifier> is the extension name and version
	// (e.g. foo_1.0.0).
	if (pathSegments case [
	extensionRequestPath,
	final extensionIdentifier,
	...final rest,
	]) {
	// This identifier should be the extension name appended with its version.
	final extensionAssetsLocation = devtoolsExtensionsManager
	.lookupLocationFor(extensionIdentifier);
	if (extensionAssetsLocation != null) {
	final relativePathToExtensionAsset = path.joinAll(rest);
	final assetPath = path.normalize(
	path.join(extensionAssetsLocation, relativePathToExtensionAsset),
	);
	// Ensure the normalized path is still within the expected
	// [extensionAssetsLocation] to protect against directory traversal.
	if (path.isWithin(extensionAssetsLocation, assetPath)) {
	final contentType = lookupMimeType(assetPath) ?? 'text/html';
	final baseHref =
	'$appRoot$extensionRequestPath/$extensionIdentifier/';
	return _serveStaticFile(
	request,
	File(assetPath),
	contentType,
	baseHref: baseHref,
	);
	}
	return Response.notFound(
	'Asset path is outside of extension assets location: $assetPath',
	);
	}
	}

	if (buildDir == null) {
	return Response.notFound('No build directory was specified.');
	}

	const defaultDocument = 'index.html';
	final indexFile = File(path.join(buildDir, defaultDocument));
	final isValidRootPage =
	pathSegments.isEmpty \|\|
	(pathSegments.length == 1 && !pathSegments[0].contains('.'));

	if (isValidRootPage) {
	return _serveStaticFile(
	request,
	indexFile,
	'text/html',
	baseHref: appRoot,
	);
	}

	// Serves the static web assets for DevTools.
	final devtoolsStaticAssetHandler = createStaticHandler(
	buildDir,
	defaultDocument: defaultDocument,
	);
	return devtoolsStaticAssetHandler(request);
	}

	// Support DevTools client-server interface via SSE.
	// Note: the handler path needs to match the full original path, not the
	// current request URL (we remove '/devtools' in the initial router but we
	// need to include it here).
	final devToolsSseHandlerPath = '${appRoot}api/sse';
	final devToolsApiHandler = SseHandler(
	Uri.parse(devToolsSseHandlerPath),
	keepAlive: sseKeepAlive,
	);

	clientManager ??= DevToolsClientManager(
	requestNotificationPermissions: false,
	);

	devToolsApiHandler.connections.rest.listen((sseConnection) {
	clientManager!.acceptClient(sseConnection, enableLogging: enableLogging);
	});

	FutureOr<Response> devtoolsHandler(Request request) {
	// If the request isn't of the form api/<method> assume it's a request for
	// DevTools assets.
	if (request.url.pathSegments case ['api', final method, ...]) {
	if (method == 'ping') {
	// Note: we have an 'OK' body response, otherwise the response has an
	// incorrect status code (204 instead of 200).
	return Response.ok('OK');
	}
	if (method == 'sse') {
	print('DevTools server handling SSE request: ${request.url}');
	return devToolsApiHandler.handler(request);
	}
	if (!ServerApi.canHandle(request)) {
	return Response.notFound('$method is not a valid API');
	}
	return ServerApi.handle(
	request,
	extensionsManager: devtoolsExtensionsManager,
	deeplinkManager: DeeplinkManager(),
	dtd: dtd,
	);
	}
	return devtoolsAssetHandler(request);
	}

	return (Request request) {
	if (notFoundHandler != null) {
	if (request.url.pathSegments case ['devtools', ...]) {
	// Forward all requests to /devtools/* to the DevTools handler.
	request = request.change(path: 'devtools');
	} else {
	return notFoundHandler(request);
	}
	}
	return devtoolsHandler(request);
	};
	}

	/// Serves [file] for all requests.
	///
	/// For files with [contentType] 'text/html' and a provided [baseHref] value,
	/// any existing `<base href="">` tag will be rewritten with the provided path.
	Future<Response> _serveStaticFile(
	Request request,
	File file,
	String contentType, {
	String? baseHref,
	}) async {
	final headers = {HttpHeaders.contentTypeHeader: contentType};

	if (contentType != 'text/html') {
	late final Uint8List fileBytes;
	try {
	fileBytes = file.readAsBytesSync();
	} on PathNotFoundException catch (_) {
	// Wait a short delay, and then retry in case we have hit a race condition
	// between a static file being served and accessed. See
	// https://github.com/flutter/devtools/issues/6365.
	await Future<void>.delayed(const Duration(milliseconds: 500));
	try {
	fileBytes = file.readAsBytesSync();
	} catch (e) {
	return Response.notFound(
	'could not read file as bytes: ${request.url.path}',
	);
	}
	}
	return Response.ok(fileBytes, headers: headers);
	}

	late String contents;
	try {
	contents = file.readAsStringSync();
	} catch (e) {
	return Response.notFound(
	'could not read file as String: ${request.url.path}',
	);
	}

	if (baseHref != null) {
	assert(baseHref.startsWith('/'));
	assert(baseHref.endsWith('/'));

	// Always use a relative base href to support going through proxies that
	// rewrite paths. For example if the server thinks we are hosting at
	// `http://localhost/devtools/` but a frontend proxy means the client app
	// is at `http://localhost/proxy/1234/devtools/` then we need the base href
	// to effectively be `/proxy/1234/devtools/`, however we have no knowledge
	// of `/proxy/1234` because it was stripped by the proxy on its way to us.
	baseHref = computeRelativeBaseHref(baseHref, request.requestedUri);

	// Replace the base href to match where the app is being served from.
	final baseHrefPattern = RegExp(r'<base href="\/"\s?\/?>');
	contents = contents.replaceFirst(
	baseHrefPattern,
	'<base href="${htmlEscape.convert(baseHref)}">',
	);
	}
	return Response.ok(contents, headers: headers);
	}

	/// Computes a relative "base href" that can be used in place of
	/// [absoluteBaseHref] for a request served at [requestUri].
	String computeRelativeBaseHref(String absoluteBaseHref, Uri requestUri) {
	// path.relative will always treat `from` as if it's a directory, but for
	// URIs that's not correct. If the request is /foo/bar then `.` is `/foo` and
	// not `/foo/bar`. To handle this, trim the last segment if the request does
	// not end with a slash.
	final requestFolderPath = requestUri.path.endsWith('/')
	? requestUri.path
	: path.posix.dirname(requestUri.path);
	return path.posix.relative(absoluteBaseHref, from: requestFolderPath);
	}