JavaScriptServices/src/Microsoft.AspNetCore.NodeServices/HostingModels/OutOfProcessNodeInstance.cs at 3ff44479241b3f76d32a3b3fe78872677282516c · JavaScriptExpert/JavaScriptServices

Repository navigation

History

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

using System;

using System.Collections.Generic;

using System.Diagnostics;

using System.IO;

using System.Linq;

using System.Threading;

using System.Threading.Tasks;

using Microsoft.Extensions.Logging;

namespace Microsoft.AspNetCore.NodeServices.HostingModels

{

/// <summary>

/// Class responsible for launching a Node child process on the local machine, determining when it is ready to

/// accept invocations, detecting if it dies on its own, and finally terminating it on disposal.

///

/// This abstract base class uses the input/output streams of the child process to perform a simple handshake

/// to determine when the child process is ready to accept invocations. This is agnostic to the mechanism that

/// derived classes use to actually perform the invocations (e.g., they could use HTTP-RPC, or a binary TCP

/// protocol, or any other RPC-type mechanism).

/// </summary>

/// <seealso cref="Microsoft.AspNetCore.NodeServices.HostingModels.INodeInstance" />

public abstract class OutOfProcessNodeInstance : INodeInstance

{

/// <summary>

/// The <see cref="ILogger"/> to which the Node.js instance's stdout/stderr is being redirected.

/// </summary>

protected readonly ILogger OutputLogger;

private const string ConnectionEstablishedMessage = "[Microsoft.AspNetCore.NodeServices:Listening]";

private const string DebuggingStartedMessageFormat = @"-----

*** Node.js debugging is enabled ***

{0}

To debug, run:

node-inspector{1}

If you haven't yet installed node-inspector, you can do so as follows:

npm install -g node-inspector

-----";

private readonly TaskCompletionSource<object> _connectionIsReadySource = new TaskCompletionSource<object>();

private bool _disposed;

private readonly StringAsTempFile _entryPointScript;

private FileSystemWatcher _fileSystemWatcher;

private int _invocationTimeoutMilliseconds;

private readonly Process _nodeProcess;

private int? _nodeDebuggingPort;

private bool _nodeProcessNeedsRestart;

private readonly string[] _watchFileExtensions;

/// <summary>

/// Creates a new instance of <see cref="OutOfProcessNodeInstance"/>.

/// </summary>

/// <param name="entryPointScript">The path to the entry point script that the Node instance should load and execute.</param>

/// <param name="projectPath">The root path of the current project. This is used when resolving Node.js module paths relative to the project root.</param>

/// <param name="watchFileExtensions">The filename extensions that should be watched within the project root. The Node instance will automatically shut itself down if any matching file changes.</param>

/// <param name="commandLineArguments">Additional command-line arguments to be passed to the Node.js instance.</param>

/// <param name="nodeOutputLogger">The <see cref="ILogger"/> to which the Node.js instance's stdout/stderr (and other log information) should be written.</param>

/// <param name="environmentVars">Environment variables to be set on the Node.js process.</param>

/// <param name="invocationTimeoutMilliseconds">The maximum duration, in milliseconds, to wait for RPC calls to complete.</param>

/// <param name="launchWithDebugging">If true, passes a flag to the Node.js process telling it to accept V8 debugger connections.</param>

/// <param name="debuggingPort">If debugging is enabled, the Node.js process should listen for V8 debugger connections on this port.</param>

public OutOfProcessNodeInstance(

string entryPointScript,

string projectPath,

string[] watchFileExtensions,

string commandLineArguments,

ILogger nodeOutputLogger,

IDictionary<string, string> environmentVars,

int invocationTimeoutMilliseconds,

bool launchWithDebugging,

int debuggingPort)

{

if (nodeOutputLogger == null)

{

throw new ArgumentNullException(nameof(nodeOutputLogger));

}

OutputLogger = nodeOutputLogger;

_entryPointScript = new StringAsTempFile(entryPointScript);

_invocationTimeoutMilliseconds = invocationTimeoutMilliseconds;

var startInfo = PrepareNodeProcessStartInfo(_entryPointScript.FileName, projectPath, commandLineArguments,

environmentVars, launchWithDebugging, debuggingPort);

_nodeProcess = LaunchNodeProcess(startInfo);

_watchFileExtensions = watchFileExtensions;

_fileSystemWatcher = BeginFileWatcher(projectPath);

ConnectToInputOutputStreams();

}

/// <summary>

/// Asynchronously invokes code in the Node.js instance.

/// </summary>

/// <typeparam name="T">The JSON-serializable data type that the Node.js code will asynchronously return.</typeparam>

/// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the invocation.</param>

/// <param name="moduleName">The path to the Node.js module (i.e., JavaScript file) relative to your project root that contains the code to be invoked.</param>

/// <param name="exportNameOrNull">If set, specifies the CommonJS export to be invoked. If not set, the module's default CommonJS export itself must be a function to be invoked.</param>

/// <param name="args">Any sequence of JSON-serializable arguments to be passed to the Node.js function.</param>

/// <returns>A <see cref="Task{TResult}"/> representing the completion of the RPC call.</returns>

public async Task<T> InvokeExportAsync<T>(

CancellationToken cancellationToken, string moduleName, string exportNameOrNull, params object[] args)

{

if (_nodeProcess.HasExited || _nodeProcessNeedsRestart)

{

// This special kind of exception triggers a transparent retry - NodeServicesImpl will launch

// a new Node instance and pass the invocation to that one instead.

var message = _nodeProcess.HasExited

? "The Node process has exited"

: "The Node process needs to restart";

throw new NodeInvocationException(message, null, nodeInstanceUnavailable: true);

}

// Construct a new cancellation token that combines the supplied token with the configured invocation

// timeout. Technically we could avoid wrapping the cancellationToken if no timeout is configured,

// but that's not really a major use case, since timeouts are enabled by default.

using (var timeoutSource = new CancellationTokenSource())

using (var combinedCancellationTokenSource = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken, timeoutSource.Token))

{

if (_invocationTimeoutMilliseconds > 0)

{

timeoutSource.CancelAfter(_invocationTimeoutMilliseconds);

}

// By overwriting the supplied cancellation token, we ensure that it isn't accidentally used

// below. We only want to pass through the token that respects timeouts.

cancellationToken = combinedCancellationTokenSource.Token;

var connectionDidSucceed = false;

try

{

// Wait until the connection is established. This will throw if the connection fails to initialize,

// or if cancellation is requested first. Note that we can't really cancel the "establishing connection"

// task because that's shared with all callers, but we can stop waiting for it if this call is cancelled.

await _connectionIsReadySource.Task.OrThrowOnCancellation(cancellationToken);

connectionDidSucceed = true;

return await InvokeExportAsync<T>(new NodeInvocationInfo

{

ModuleName = moduleName,

ExportedFunctionName = exportNameOrNull,

Args = args

}, cancellationToken);

}

catch (TaskCanceledException)

{

if (timeoutSource.IsCancellationRequested)

{

// It was very common for developers to report 'TaskCanceledException' when encountering almost any

// trouble when using NodeServices. Now we have a default invocation timeout, and attempt to give

// a more descriptive exception message if it happens.

if (!connectionDidSucceed)

{

// This is very unlikely, but for debugging, it's still useful to differentiate it from the

// case below.

throw new NodeInvocationException(

$"Attempt to connect to Node timed out after {_invocationTimeoutMilliseconds}ms.",

string.Empty);

}

else

{

// Developers encounter this fairly often (if their Node code fails without invoking the callback,

// all that the .NET side knows is that the invocation eventually times out). Previously, this surfaced

// as a TaskCanceledException, but this led to a lot of issue reports. Now we throw the following

// descriptive error.

throw new NodeInvocationException(

$"The Node invocation timed out after {_invocationTimeoutMilliseconds}ms.",

$"You can change the timeout duration by setting the {NodeServicesOptions.TimeoutConfigPropertyName} "

+ $"property on {nameof(NodeServicesOptions)}.\n\n"

+ "The first debugging step is to ensure that your Node.js function always invokes the supplied "

+ "callback (or throws an exception synchronously), even if it encounters an error. Otherwise, "

+ "the .NET code has no way to know that it is finished or has failed."

);

}

else

{

throw;

}

/// <summary>

/// Disposes this instance.

/// </summary>

public void Dispose()

{

Dispose(true);

GC.SuppressFinalize(this);

}

/// <summary>

/// Asynchronously invokes code in the Node.js instance.

/// </summary>

/// <typeparam name="T">The JSON-serializable data type that the Node.js code will asynchronously return.</typeparam>

/// <param name="invocationInfo">Specifies the Node.js function to be invoked and arguments to be passed to it.</param>

/// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the invocation.</param>

/// <returns>A <see cref="Task{TResult}"/> representing the completion of the RPC call.</returns>

protected abstract Task<T> InvokeExportAsync<T>(

NodeInvocationInfo invocationInfo,

CancellationToken cancellationToken);

/// <summary>

/// Configures a <see cref="ProcessStartInfo"/> instance describing how to launch the Node.js process.

/// </summary>

/// <param name="entryPointFilename">The entrypoint JavaScript file that the Node.js process should execute.</param>

/// <param name="projectPath">The root path of the project. This is used when locating Node.js modules relative to the project root.</param>

/// <param name="commandLineArguments">Command-line arguments to be passed to the Node.js process.</param>

/// <param name="environmentVars">Environment variables to be set on the Node.js process.</param>

/// <param name="launchWithDebugging">If true, passes a flag to the Node.js process telling it to accept V8 debugger connections.</param>

/// <param name="debuggingPort">If debugging is enabled, the Node.js process should listen for V8 debugger connections on this port.</param>

/// <returns></returns>

protected virtual ProcessStartInfo PrepareNodeProcessStartInfo(

string entryPointFilename, string projectPath, string commandLineArguments,

IDictionary<string, string> environmentVars, bool launchWithDebugging, int debuggingPort)

{

// This method is virtual, as it provides a way to override the NODE_PATH or the path to node.exe

string debuggingArgs;

if (launchWithDebugging)

{

debuggingArgs = debuggingPort != default(int) ? $"--debug={debuggingPort} " : "--debug ";

_nodeDebuggingPort = debuggingPort;

}

else

{

debuggingArgs = string.Empty;

}

var thisProcessPid = Process.GetCurrentProcess().Id;

var startInfo = new ProcessStartInfo("node")

{

Arguments = $"{debuggingArgs}\"{entryPointFilename}\" --parentPid {thisProcessPid} {commandLineArguments ?? string.Empty}",

UseShellExecute = false,

RedirectStandardInput = true,

RedirectStandardOutput = true,

RedirectStandardError = true,

WorkingDirectory = projectPath

};

// Append environment vars

if (environmentVars != null)

{

foreach (var envVarKey in environmentVars.Keys)

{

var envVarValue = environmentVars[envVarKey];

if (envVarValue != null)

{

SetEnvironmentVariable(startInfo, envVarKey, envVarValue);

}

// Append projectPath to NODE_PATH so it can locate node_modules

var existingNodePath = Environment.GetEnvironmentVariable("NODE_PATH") ?? string.Empty;

if (existingNodePath != string.Empty)

{

existingNodePath += Path.PathSeparator;

}

var nodePathValue = existingNodePath + Path.Combine(projectPath, "node_modules");

SetEnvironmentVariable(startInfo, "NODE_PATH", nodePathValue);

return startInfo;

}

/// <summary>

/// Virtual method invoked whenever the Node.js process emits a line to its stdout.

/// </summary>

/// <param name="outputData">The line emitted to the Node.js process's stdout.</param>

protected virtual void OnOutputDataReceived(string outputData)

{

OutputLogger.LogInformation(outputData);

}

/// <summary>

/// Virtual method invoked whenever the Node.js process emits a line to its stderr.

/// </summary>

/// <param name="errorData">The line emitted to the Node.js process's stderr.</param>

protected virtual void OnErrorDataReceived(string errorData)

{

OutputLogger.LogError(errorData);

}

/// <summary>

/// Disposes the instance.

/// </summary>

/// <param name="disposing">True if the object is disposing or false if it is finalizing.</param>

protected virtual void Dispose(bool disposing)

{

if (!_disposed)

{

if (disposing)

{

_entryPointScript.Dispose();

EnsureFileSystemWatcherIsDisposed();

}

// Make sure the Node process is finished

// TODO: Is there a more graceful way to end it? Or does this still let it perform any cleanup?

if (!_nodeProcess.HasExited)

{

_nodeProcess.Kill();

}

_disposed = true;

}

private void EnsureFileSystemWatcherIsDisposed()

{

if (_fileSystemWatcher != null)

{

_fileSystemWatcher.Dispose();

_fileSystemWatcher = null;

}

private static void SetEnvironmentVariable(ProcessStartInfo startInfo, string name, string value)

{

#if NET451

startInfo.EnvironmentVariables[name] = value;

#else

startInfo.Environment[name] = value;

#endif

}

private static Process LaunchNodeProcess(ProcessStartInfo startInfo)

{

var process = Process.Start(startInfo);

// On Mac at least, a killed child process is left open as a zombie until the parent

// captures its exit code. We don't need the exit code for this process, and don't want

// to use process.WaitForExit() explicitly (we'd have to block the thread until it really

// has exited), but we don't want to leave zombies lying around either. It's sufficient

// to use process.EnableRaisingEvents so that .NET will grab the exit code and let the

// zombie be cleaned away without having to block our thread.

process.EnableRaisingEvents = true;

return process;

}

private static string UnencodeNewlines(string str)

{

if (str != null)

{

// The token here needs to match the const in OverrideStdOutputs.ts.

// See the comment there for why we're doing this.

str = str.Replace("__ns_newline__", Environment.NewLine);

}

return str;

}

private void ConnectToInputOutputStreams()

{

var initializationIsCompleted = false;

_nodeProcess.OutputDataReceived += (sender, evt) =>

{

if (evt.Data == ConnectionEstablishedMessage && !initializationIsCompleted)

{

_connectionIsReadySource.SetResult(null);

initializationIsCompleted = true;

}

else if (evt.Data != null)

{

OnOutputDataReceived(UnencodeNewlines(evt.Data));

}

};

_nodeProcess.ErrorDataReceived += (sender, evt) =>

{

if (evt.Data != null)

{

if (IsDebuggerListeningMessage(evt.Data))

{

var debugPortArg = _nodeDebuggingPort.HasValue ? $" --debug-port={_nodeDebuggingPort.Value}" : string.Empty;

OutputLogger.LogWarning(string.Format(DebuggingStartedMessageFormat, evt.Data, debugPortArg));

}

else if (!initializationIsCompleted)

{

_connectionIsReadySource.SetException(

new InvalidOperationException("The Node.js process failed to initialize: " + evt.Data));

initializationIsCompleted = true;

}

else

{

OnErrorDataReceived(UnencodeNewlines(evt.Data));

}

};

_nodeProcess.BeginOutputReadLine();

_nodeProcess.BeginErrorReadLine();

}

private static bool IsDebuggerListeningMessage(string message)

{

return message.StartsWith("Debugger listening ", StringComparison.OrdinalIgnoreCase);

}

private FileSystemWatcher BeginFileWatcher(string rootDir)

{

if (_watchFileExtensions == null || _watchFileExtensions.Length == 0)

{

// Nothing to watch

return null;

}

var watcher = new FileSystemWatcher(rootDir)

{

IncludeSubdirectories = true,

NotifyFilter = NotifyFilters.LastWrite | NotifyFilters.FileName | NotifyFilters.DirectoryName

};

watcher.Changed += OnFileChanged;

watcher.Created += OnFileChanged;

watcher.Deleted += OnFileChanged;

watcher.Renamed += OnFileRenamed;

watcher.EnableRaisingEvents = true;

return watcher;

}

private void OnFileChanged(object source, FileSystemEventArgs e)

{

if (IsFilenameBeingWatched(e.FullPath))

{

RestartDueToFileChange(e.FullPath);

}

private void OnFileRenamed(object source, RenamedEventArgs e)

{

if (IsFilenameBeingWatched(e.OldFullPath) || IsFilenameBeingWatched(e.FullPath))

{

RestartDueToFileChange(e.OldFullPath);

}

private bool IsFilenameBeingWatched(string fullPath)

{

if (string.IsNullOrEmpty(fullPath))

{

return false;

}

else

{

var actualExtension = Path.GetExtension(fullPath) ?? string.Empty;

return _watchFileExtensions.Any(actualExtension.Equals);

}

private void RestartDueToFileChange(string fullPath)

{

OutputLogger.LogInformation($"Node will restart because file changed: {fullPath}");

_nodeProcessNeedsRestart = true;

// There's no need to watch for any more changes, since we're already restarting, and if the

// restart takes some time (e.g., due to connection draining), we could end up getting duplicate

// notifications.

EnsureFileSystemWatcherIsDisposed();

}

/// <summary>

/// Implements the finalization part of the IDisposable pattern by calling Dispose(false).

/// </summary>

~OutOfProcessNodeInstance()

{

Dispose(false);

}

FilesExpand file tree

OutOfProcessNodeInstance.cs

Latest commit

History

OutOfProcessNodeInstance.cs

File metadata and controls