Merge pull request #124 from atom-community/spawn

Author: aminya

README.md

@@ -15,8 +15,8 @@ Provide integration support for adding Language Server Protocol servers to Atom.
 This npm package can be used by Atom package authors wanting to integrate LSP-compatible language servers with Atom. It provides:
 
 * Conversion routines between Atom and LSP types
-* A FlowTyped wrapper around JSON-RPC for **v3** of the LSP protocol
-* All necessary FlowTyped input and return structures for LSP, notifications etc.
+* A TypeScript wrapper around JSON-RPC for **v3** of the LSP protocol
+* All necessary TypeScript input and return structures for LSP, notifications etc.
 * A number of adapters to translate communication between Atom/Atom-IDE and the LSP's capabilities
 * Automatic wiring up of adapters based on the negotiated capabilities of the language server
 * Helper functions for downloading additional non-npm dependencies
@@ -59,9 +59,9 @@ The language server protocol consists of a number of capabilities. Some of these
 
 The underlying JSON-RPC communication is handled by the [vscode-jsonrpc npm module](https://www.npmjs.com/package/vscode-jsonrpc).
 
-### Minimal example
+### Minimal example (Nodejs-compatible LSP exe)
 
-A minimal implementation can be illustrated by the Omnisharp package here which has only npm-managed dependencies.  You simply provide the scope name, language name and server name as well as start your process and AutoLanguageClient takes care of interrogating your language server capabilities and wiring up the appropriate services within Atom to expose them.
+A minimal implementation can be illustrated by the Omnisharp package here which has only npm-managed dependencies, and the LSP is a JavaScript file.  You simply provide the scope name, language name and server name as well as start your process and `AutoLanguageClient` takes care of interrogating your language server capabilities and wiring up the appropriate services within Atom to expose them.
 
 ```javascript
 const {AutoLanguageClient} = require('atom-languageclient')
@@ -83,6 +83,32 @@ You can get this code packaged up with the necessary package.json etc. from the
 
 Note that you will also need to add various entries to the `providedServices` and `consumedServices` section of your package.json (for now).  You can [obtain these entries here](https://github.com/atom/ide-csharp/tree/master/package.json).
 
+### Minimal example (General LSP exe)
+
+If the LSP is a general executable (not a JavaScript file), you should use `spawn` inside `startServerProcess`.
+
+```javascript
+const {AutoLanguageClient} = require('atom-languageclient')
+
+class DLanguageClient extends AutoLanguageClient {
+  getGrammarScopes () { return [ 'source.d' ] }
+  getLanguageName () { return 'D' }
+  getServerName () { return 'serve-d' }
+
+  startServerProcess (projectPath) {
+    return super.spawn(
+      'serve-d',                // the `name` or `path` of the executable
+                                // if the `name` is provided it checks `bin/platform-arch/exeName` by default, and if doesn't exists uses the `exeName` on the PATH
+      [],                       // args passed to spawn the exe
+      { cwd: projectPath }      // child process spawn options
+    )
+  }
+}
+
+module.exports = new DLanguageClient()
+```
+
+
 ### Using other connection types
 
 The default connection type is *stdio* however both *ipc* and *sockets* are also available.

lib/auto-languageclient.ts

@@ -117,9 +117,9 @@ export default class AutoLanguageClient {
   }
 
   /** (Optional) Return the parameters used to initialize a client - you may want to extend capabilities */
-  protected getInitializeParams(projectPath: string, process: LanguageServerProcess): ls.InitializeParams {
+  protected getInitializeParams(projectPath: string, lsProcess: LanguageServerProcess): ls.InitializeParams {
     return {
-      processId: process.pid,
+      processId: lsProcess.pid,
       rootPath: projectPath,
       rootUri: Convert.pathToUri(projectPath),
       workspaceFolders: null,
@@ -279,7 +279,34 @@ export default class AutoLanguageClient {
     await this._serverManager.stopAllServers();
   }
 
-  protected spawnChildNode(args: string[], options: cp.SpawnOptions = {}): cp.ChildProcess {
+  /**
+   * Spawn a general language server.
+   * Use this inside the `startServerProcess` override if the language server is a general executable.
+   * Also see the `spawnChildNode` method.
+   * If the name is provided as the first argument, it checks `bin/platform-arch/exeName` by default, and if doesn't exists uses the exe on PATH.
+   * For example on Windows x64, by passing `serve-d`, `bin/win32-x64/exeName.exe` is spawned by default.
+   * @param exe the `name` or `path` of the executable
+   * @param args args passed to spawn the exe. Defaults to `[]`.
+   * @param options: child process spawn options. Defaults to `{}`.
+   * @param rootPath the path of the folder of the exe file. Defaults to `join("bin", `${process.platform}-${process.arch}`)`.
+   * @param exeExtention the extention of the exe file. Defaults to `process.platform === "win32" ? ".exe" : ""`
+   */
+  protected spawn(
+    exe: string,
+    args: string[] = [],
+    options: cp.SpawnOptions = {},
+    rootPath = Utils.rootPathDefault,
+    exeExtention = Utils.exeExtentionDefault
+  ): LanguageServerProcess {
+    this.logger.debug(`starting "${exe} ${args.join(' ')}"`);
+    return cp.spawn(Utils.getExePath(exe, rootPath, exeExtention), args, options);
+  }
+
+  /** Spawn a language server using Atom's Nodejs process
+   *  Use this inside the `startServerProcess` override if the language server is a JavaScript file.
+   *  Also see the `spawn` method
+   */
+  protected spawnChildNode(args: string[], options: cp.SpawnOptions = {}): LanguageServerProcess {
     this.logger.debug(`starting child Node "${args.join(' ')}"`);
     options.env = options.env || Object.create(process.env);
     if (options.env) {
@@ -299,14 +326,14 @@ export default class AutoLanguageClient {
 
   /** Starts the server by starting the process, then initializing the language server and starting adapters */
   private async startServer(projectPath: string): Promise<ActiveServer> {
-    const process = await this.reportBusyWhile(
+    const lsProcess = await this.reportBusyWhile(
       `Starting ${this.getServerName()} for ${path.basename(projectPath)}`,
       async () => this.startServerProcess(projectPath),
     );
-    this.captureServerErrors(process, projectPath);
-    const connection = new LanguageClientConnection(this.createRpcConnection(process), this.logger);
+    this.captureServerErrors(lsProcess, projectPath);
+    const connection = new LanguageClientConnection(this.createRpcConnection(lsProcess), this.logger);
     this.preInitialization(connection);
-    const initializeParams = this.getInitializeParams(projectPath, process);
+    const initializeParams = this.getInitializeParams(projectPath, lsProcess);
     const initialization = connection.initialize(initializeParams);
     this.reportBusyWhile(
       `${this.getServerName()} initializing for ${path.basename(projectPath)}`,
@@ -315,7 +342,7 @@ export default class AutoLanguageClient {
     const initializeResponse = await initialization;
     const newServer = {
       projectPath,
-      process,
+      process: lsProcess,
       connection,
       capabilities: initializeResponse.capabilities,
       disposable: new CompositeDisposable(),
@@ -353,22 +380,19 @@ export default class AutoLanguageClient {
     return newServer;
   }
 
-  private captureServerErrors(childProcess: LanguageServerProcess, projectPath: string): void {
-    childProcess.on('error', (err) => this.handleSpawnFailure(err));
-    childProcess.on('exit', (code, signal) => this.logger.debug(`exit: code ${code} signal ${signal}`));
-    childProcess.stderr.setEncoding('utf8');
-    childProcess.stderr.on('data', (chunk: Buffer) => {
-      const errorString = chunk.toString();
-      this.handleServerStderr(errorString, projectPath);
-      // Keep the last 5 lines for packages to use in messages
-      this.processStdErr = (this.processStdErr + errorString)
-        .split('\n')
-        .slice(-5)
-        .join('\n');
-    });
+  private captureServerErrors(lsProcess: LanguageServerProcess, projectPath: string): void {
+    lsProcess.on('error', (err) => this.onSpawnError(err));
+    lsProcess.on("close", (code, signal) => this.onSpawnClose(code, signal));
+    lsProcess.on("disconnect", () => this.onSpawnDisconnect());
+    lsProcess.on('exit', (code, signal) => this.onSpawnExit(code, signal));
+    lsProcess.stderr?.setEncoding('utf8');
+    lsProcess.stderr?.on('data', (chunk: Buffer) => this.onSpawnStdErrData(chunk, projectPath));
   }
 
-  private handleSpawnFailure(err: any): void {
+  /** The function called whenever the spawned server `error`s.
+   *  Extend (call super.onSpawnError) or override this if you need custom error handling
+   */
+  protected onSpawnError(err: Error): void {
     atom.notifications.addError(
       `${this.getServerName()} language server for ${this.getLanguageName()} unable to start`,
       {
@@ -378,23 +402,66 @@ export default class AutoLanguageClient {
     );
   }
 
+  /** The function called whenever the spawned server `close`s.
+   *  Extend (call super.onSpawnClose) or override this if you need custom close handling
+   */
+  protected onSpawnClose(code: number | null, signal: NodeJS.Signals | null): void {
+    if (code !== 0 && signal === null) {
+      atom.notifications.addError(
+        `${this.getServerName()} language server for ${this.getLanguageName()} was closed with code: ${code}.`
+      );
+    }
+  }
+
+  /** The function called whenever the spawned server `disconnect`s.
+   *  Extend (call super.onSpawnDisconnect) or override this if you need custom disconnect handling
+   */
+  protected onSpawnDisconnect(): void {
+    this.logger.debug(`${this.getServerName()} language server for ${this.getLanguageName()} got disconnected.`);
+  }
+
+  /** The function called whenever the spawned server `exit`s.
+   *  Extend (call super.onSpawnExit) or override this if you need custom exit handling
+   */
+  protected onSpawnExit(code: number | null, signal: NodeJS.Signals | null): void {
+    this.logger.debug(`exit: code ${code} signal ${signal}`);
+  }
+
+  /** The function called whenever the spawned server returns `data` in `stderr`
+   *  Extend (call super.onSpawnStdErrData) or override this if you need custom stderr data handling
+   */
+  protected onSpawnStdErrData(chunk: Buffer, projectPath: string): void {
+    const errorString = chunk.toString();
+    this.handleServerStderr(errorString, projectPath);
+    // Keep the last 5 lines for packages to use in messages
+    this.processStdErr = (this.processStdErr + errorString)
+      .split('\n')
+      .slice(-5)
+      .join('\n');
+  }
+
   /** Creates the RPC connection which can be ipc, socket or stdio */
-  private createRpcConnection(process: LanguageServerProcess): rpc.MessageConnection {
+  private createRpcConnection(lsProcess: LanguageServerProcess): rpc.MessageConnection {
     let reader: rpc.MessageReader;
     let writer: rpc.MessageWriter;
     const connectionType = this.getConnectionType();
     switch (connectionType) {
       case 'ipc':
-        reader = new rpc.IPCMessageReader(process as cp.ChildProcess);
-        writer = new rpc.IPCMessageWriter(process as cp.ChildProcess);
+        reader = new rpc.IPCMessageReader(lsProcess as cp.ChildProcess);
+        writer = new rpc.IPCMessageWriter(lsProcess as cp.ChildProcess);
         break;
       case 'socket':
         reader = new rpc.SocketMessageReader(this.socket);
         writer = new rpc.SocketMessageWriter(this.socket);
         break;
       case 'stdio':
-        reader = new rpc.StreamMessageReader(process.stdout);
-        writer = new rpc.StreamMessageWriter(process.stdin);
+        if (lsProcess.stdin !== null && lsProcess.stdout !== null) {
+          reader = new rpc.StreamMessageReader(lsProcess.stdout);
+          writer = new rpc.StreamMessageWriter(lsProcess.stdin);
+        } else {
+          this.logger.error(`The language server process for ${this.getLanguageName()} does not have a valid stdin and stdout`);
+          return Utils.assertUnreachable('stdio' as never)
+        }
         break;
       default:
         return Utils.assertUnreachable(connectionType);

lib/main.ts

@@ -9,6 +9,7 @@ import { Logger, ConsoleLogger, FilteredLogger } from './logger';
 import DownloadFile from './download-file';
 import LinterPushV2Adapter from './adapters/linter-push-v2-adapter';
 import CommandExecutionAdapter from './adapters/command-execution-adapter';
+export { getExePath } from "./utils"
 
 export * from './auto-languageclient';
 export {

lib/server-manager.ts

@@ -1,8 +1,7 @@
 import Convert from './convert';
 import * as path from 'path';
-import * as stream from 'stream';
 import * as ls from './languageclient';
-import { EventEmitter } from 'events';
+import { ChildProcess } from 'child_process'
 import { Logger } from './logger';
 import {
   CompositeDisposable,
@@ -11,22 +10,16 @@ import {
 } from 'atom';
 import { ReportBusyWhile } from './utils';
 
+
+type MinimalLanguageServerProcess = Pick<ChildProcess, 'stdin' | 'stdout' | 'stderr' | 'pid' | 'kill' | 'on'>
+
 /**
- * Public: Defines the minimum surface area for an object that resembles a
- * ChildProcess.  This is used so that language packages with alternative
- * language server process hosting strategies can return something compatible
- * with AutoLanguageClient.startServerProcess.
+ * Public: Defines a language server process which is either a ChildProcess, or it is a minimal object that resembles a
+ * ChildProcess.
+ * `MinimalLanguageServerProcess` is used so that language packages with alternative language server process hosting strategies
+ * can return something compatible with `AutoLanguageClient.startServerProcess`.
  */
-export interface LanguageServerProcess extends EventEmitter {
-  stdin: stream.Writable;
-  stdout: stream.Readable;
-  stderr: stream.Readable;
-  pid: number;
-
-  kill(signal?: NodeJS.Signals | number): void;
-  on(event: 'error', listener: (err: Error) => void): this;
-  on(event: 'exit', listener: (code: number, signal: NodeJS.Signals | number) => void): this;
-}
+export type LanguageServerProcess = ChildProcess | MinimalLanguageServerProcess
 
 /** The necessary elements for a server that has started or is starting. */
 export interface ActiveServer {

lib/utils.ts

@@ -1,3 +1,5 @@
+import { join, resolve } from 'path';
+import  { existsSync } from 'fs';
 import {
   Point,
   TextBuffer,
@@ -111,3 +113,24 @@ export function promiseWithTimeout<T>(ms: number, promise: Promise<T>): Promise<
     });
   });
 }
+
+
+export const rootPathDefault = join("bin", `${process.platform}-${process.arch}`);
+export const exeExtentionDefault = process.platform === "win32" ? ".exe" : "";
+
+/** Finds an exe file in the package assuming it is placed under `rootPath/platform-arch/exe`. If the exe file did not exist,
+ * the given name is returned.
+ * For example on Windows x64, if the `exeName` is `serve-d`, it returns the absolute path to `./bin/win32-x64/exeName.exe`, and
+ * if the file did not exist, `serve-d` is returned.
+ * @param exeName name of the exe file
+ * @param rootPath the path of the folder of the exe file. Defaults to 'join("bin", `${process.platform}-${process.arch}`)'
+ * @param exeExtention the extention of the exe file. Defaults to `process.platform === "win32" ? ".exe" : ""`
+ */
+export function getExePath(exeName: string, rootPath = rootPathDefault, exeExtention = exeExtentionDefault): string {
+ const exePath = resolve(join(rootPath, `${exeName}${exeExtention}`));
+ if (existsSync(exePath)) {
+   return exePath
+ } else {
+   return exeName
+ }
+}

test/utils.test.ts

@@ -2,6 +2,9 @@ import * as Utils from '../lib/utils';
 import { createFakeEditor } from './helpers';
 import { expect } from 'chai';
 import { Point } from 'atom';
+import { join } from 'path'
+import * as fs from 'fs'
+import * as sinon from 'sinon'
 
 describe('Utils', () => {
   describe('getWordAtPosition', () => {
@@ -30,4 +33,40 @@ describe('Utils', () => {
       expect(range.serialize()).eql([[0, 4], [0, 4]]);
     });
   });
+
+  describe('getExePath', () => {
+    it('returns the exe path under bin folder by default', () => {
+      let expectedExe = join(process.cwd(), 'bin', `${process.platform}-${process.arch}`, 'serve-d');
+      if (process.platform === 'win32') {
+        expectedExe = expectedExe + '.exe';
+      }
+
+      const fsMock = sinon.mock(fs);
+      fsMock.expects('existsSync').withArgs(expectedExe).returns(true);
+
+      const exePath = Utils.getExePath('serve-d');
+      expect(exePath).eq(expectedExe);
+
+      fsMock.restore();
+    })
+    it('returns the exe path for the given root', () => {
+      const rootPath = join(__dirname, `${process.platform}-${process.arch}`);
+      let expectedExe = join(rootPath, 'serve-d');
+      if (process.platform === 'win32') {
+        expectedExe = expectedExe + '.exe';
+      }
+
+      const fsMock = sinon.mock(fs);
+      fsMock.expects('existsSync').withArgs(expectedExe).returns(true);
+
+      const exePath = Utils.getExePath('serve-d', rootPath);
+      expect(exePath).eq(expectedExe);
+
+      fsMock.restore();
+    })
+    it('returns the exe name if the file does not exist under rootPath', () => {
+      const exePath = Utils.getExePath('python');
+      expect(exePath).eq('python');
+    })
+  })
 });