Expose DotSlash prefetching as unstable_prepareDebuggerShell (#53434)

Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/53434

Changelog: [Internal]

The React Native DevTools standalone shell is distributed as a DotSlash file that downloads the required binaries lazily. This diff gives integrations a mechanism for kicking off the download early (but without slowing down `npm install react-native`). This will be integrated into dev-middleware in an upcoming diff.

Reviewed By: huntie

Differential Revision: D78413091

fbshipit-source-id: caf2010edd1bcdd139d37d7849212cd1cbb64f46

packages/debugger-shell/src/node/index.flow.js

@@ -8,6 +8,11 @@
  * @format
  */
 
+import {
+  prepareDebuggerShellFromDotSlashFile,
+  spawnAndGetStderr,
+} from './private/LaunchUtils';
+
 const {spawn} = require('cross-spawn');
 const path = require('path');
 
@@ -15,6 +20,11 @@ const path = require('path');
 // The 'dev' flavor will use a stock Electron binary and run the shell code from the `electron/` directory.
 type DebuggerShellFlavor = 'prebuilt' | 'dev';
 
+const DEVTOOLS_BINARY_DOTSLASH_FILE = path.join(
+  __dirname,
+  '../../bin/react-native-devtools',
+);
+
 async function unstable_spawnDebuggerShellWithArgs(
   args: string[],
   {
@@ -74,6 +84,68 @@ async function unstable_spawnDebuggerShellWithArgs(
   });
 }
 
+export type DebuggerShellPreparationResult = $ReadOnly<{
+  code:
+    | 'success'
+    | 'likely_offline'
+    | 'platform_not_supported'
+    | 'possible_corruption'
+    | 'unexpected_error',
+  humanReadableMessage?: string,
+  verboseInfo?: string,
+}>;
+
+/**
+ * Attempts to prepare the debugger shell for use and returns a coded result
+ * that can be used to advise the user on how to proceed in case of failure.
+ * In particular, this function will attempt to download and extract an
+ * appropriate binary for the "prebuilt" flavor.
+ *
+ * This function should be called early during dev server startup, in parallel
+ * with other initialization steps, so that the debugger shell is ready to use
+ * instantly when the user tries to open it (and conversely, the user is
+ * informed ASAP if it is not ready to use).
+ */
+async function unstable_prepareDebuggerShell(
+  flavor: DebuggerShellFlavor,
+): Promise<DebuggerShellPreparationResult> {
+  const [binaryPath, baseArgs] = getShellBinaryAndArgs(flavor);
+
+  try {
+    switch (flavor) {
+      case 'prebuilt':
+        const prebuiltResult = await prepareDebuggerShellFromDotSlashFile(
+          DEVTOOLS_BINARY_DOTSLASH_FILE,
+        );
+        if (prebuiltResult.code !== 'success') {
+          return prebuiltResult;
+        }
+        break;
+      case 'dev':
+        break;
+      default:
+        flavor as empty;
+        throw new Error(`Unknown flavor: ${flavor}`);
+    }
+    const {code, stderr} = await spawnAndGetStderr(binaryPath, [
+      ...baseArgs,
+      '--version',
+    ]);
+    if (code !== 0) {
+      return {
+        code: 'unexpected_error',
+        verboseInfo: stderr,
+      };
+    }
+    return {code: 'success'};
+  } catch (e) {
+    return {
+      code: 'unexpected_error',
+      verboseInfo: e.message,
+    };
+  }
+}
+
 function getShellBinaryAndArgs(
   flavor: DebuggerShellFlavor,
 ): [string, Array<string>] {
@@ -82,7 +154,7 @@ function getShellBinaryAndArgs(
       return [
         // $FlowIssue[cannot-resolve-module] fb-dotslash includes Flow types but Flow does not pick them up
         require('fb-dotslash'),
-        [path.join(__dirname, '../../bin/react-native-devtools')],
+        [DEVTOOLS_BINARY_DOTSLASH_FILE],
       ];
     case 'dev':
       return [
@@ -98,4 +170,4 @@ function getShellBinaryAndArgs(
   }
 }
 
-export {unstable_spawnDebuggerShellWithArgs};
+export {unstable_spawnDebuggerShellWithArgs, unstable_prepareDebuggerShell};

packages/debugger-shell/src/node/private/LaunchUtils.js

@@ -0,0 +1,98 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+import type {DebuggerShellPreparationResult} from '../';
+
+const {spawn} = require('cross-spawn');
+
+async function spawnAndGetStderr(
+  command: string,
+  args: string[],
+): Promise<{
+  code: number,
+  stderr: string,
+}> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: ['ignore', 'ignore', 'pipe'],
+      encoding: 'utf8',
+      windowsHide: true,
+    });
+    let stderr = '';
+    child.stderr.on('data', data => {
+      stderr += data;
+    });
+    child.on('error', error => {
+      reject(error);
+    });
+    child.on('close', (code, signal) => {
+      resolve({
+        code,
+        stderr,
+      });
+    });
+  });
+}
+
+async function prepareDebuggerShellFromDotSlashFile(
+  filePath: string,
+): Promise<DebuggerShellPreparationResult> {
+  const {code, stderr} = await spawnAndGetStderr(
+    // $FlowIssue[cannot-resolve-module] fb-dotslash includes Flow types but Flow does not pick them up
+    require('fb-dotslash'),
+    ['--', 'fetch', filePath],
+  );
+  if (code === 0) {
+    return {code: 'success'};
+  }
+  if (
+    stderr.includes('dotslash error') &&
+    stderr.includes('no providers succeeded')
+  ) {
+    if (stderr.includes('failed to verify artifact')) {
+      return {
+        code: 'possible_corruption',
+        humanReadableMessage:
+          'Failed to verify the latest version of React Native DevTools. ' +
+          'Using a fallback version instead. ',
+        verboseInfo: stderr,
+      };
+    }
+    return {
+      code: 'likely_offline',
+      humanReadableMessage:
+        'Failed to download the latest version of React Native DevTools. ' +
+        'Using a fallback version instead. ' +
+        'Connect to the internet or check your network settings.',
+      verboseInfo: stderr,
+    };
+  }
+  if (
+    stderr.includes('dotslash error') &&
+    stderr.includes('platform not supported')
+  ) {
+    return {
+      code: 'platform_not_supported',
+      humanReadableMessage:
+        'The latest version of React Native DevTools is not supported on this platform. ' +
+        'Using a fallback version instead.',
+      verboseInfo: stderr,
+    };
+  }
+  return {
+    code: 'unexpected_error',
+    humanReadableMessage:
+      'An unexpected error occured while installing the latest version of React Native DevTools. ' +
+      'Using a fallback version instead.',
+    verboseInfo: stderr,
+  };
+}
+
+export {spawnAndGetStderr, prepareDebuggerShellFromDotSlashFile};