dockerfile-language-server-nodejs

Dockerfile language server

This is a language server for Dockerfiles powered by Node.js written in TypeScript. To build or to install this language server, you will need to have Node.js installed on your computer.

Supported features:

• code actions
• code completion
• definition
• diagnostics
• document highlight
• document symbols
• formatting
• hovers
• rename

Development Instructions

To build and compile this language server, please run the following commands after cloning the repository with Git.

npm install
npm run build
npm test

If you are planning to change the code, use npm run watch to get the TypeScript files transpiled on-the-fly as they are modified.

Once the code has finished compiling, you can connect a language server client to the server via Node IPC, stdio, or sockets.

Installation Instructions

To install this language server onto your computer, please install the dockerfile-language-server-nodejs npm module. The -g flag will install the npm module globally onto your computer.

npm install -g dockerfile-language-server-nodejs

After the installation has completed, you can start the language server with the docker-langserver binary. You should specify the desired method of communciating with the language server via one of the three arguments shown below.

docker-langserver --node-ipc
docker-langserver --stdio
docker-langserver --socket=<port>

Settings

Clients may send a workspace/didChangeConfiguration notification to notify the server of settings changes.

The settings object that will be included with the notification must conform to the following specification.

interface Settings {
  docker: {
    languageserver: {
      diagnostics?: {
        // string values must be equal to "ignore", "warning", or "error"
        deprecatedMaintainer?: string,
        directiveCasing?: string,
        instructionCasing?: string,
        instructionCmdMultiple?: string,
        instructionEntrypointMultiple?: string
        instructionHealthcheckMultiple?: string
      }
    }
  }
}

Node IPC

With the child_process API, you can fork() a new Node.js process running the language server and communicate with it using send(message) and on('message', ...).

import * as child_process from "child_process";

let lspProcess = child_process.fork("out/src/server.js", [ "--node-ipc" ]);
let messageId = 1;

function send(method: string, params: object) {
    let message = {
        jsonrpc: "2.0",
        id: messageId++,
        method: method,
        params: params
    };
    lspProcess.send(message);
}

function initialize() {
    send("initialize", {
        rootPath: process.cwd(),
        processId: process.pid,
        capabilities: {
            /* ... */
        }
    });
}


lspProcess.on('message', function (json) {
    console.log(json);
});
initialize();

Standard Input/Output

When writing directly to the process's stdin, the additional Content-Length header must be included. Similarly, when reading from the process's stdout, the header will be included in the response message.

import * as child_process from "child_process";

let lspProcess = child_process.spawn("node", [ "out/src/server.js", "--stdio" ]);
let messageId = 1;

function send(method: string, params: object) {
    let message = {
        jsonrpc: "2.0",
        id: messageId++,
        method: method,
        params: params
    };
    let json = JSON.stringify(message);
    let headers = "Content-Length: " + json.length + "\r\n\r\n";
    lspProcess.stdin.write(headers, "ASCII");
    lspProcess.stdin.write(json, "UTF-8");
}

function initialize() {
    send("initialize", {
        rootPath: process.cwd(),
        processId: process.pid,
        capabilities: {
            /* ... */
        }
    });
}

lspProcess.stdout.on("data", (message) => {
    // "Content-Length: ...\r\n\r\n\" will be included here
    console.log(message.toString());
});

initialize();

vscode-jsonrpc

The StreamMessageReader and StreamMessageWriter classes from the vscode-jsonrpc module will handle the Content-Length headers for you so you only have to worry about the actual request and response.

import * as child_process from "child_process";
import { StreamMessageReader, StreamMessageWriter } from "vscode-jsonrpc";

let lspProcess = child_process.spawn("node", [ "out/src/server.js", "--stdio" ]);
let messageId = 1;

const reader = new StreamMessageReader(lspProcess.stdout);
const writer = new StreamMessageWriter(lspProcess.stdin);

function send(method: string, params: object) {
    let message = {
        jsonrpc: "2.0",
        id: messageId++,
        method: method,
        params: params
    };
    writer.write(message);
}

function initialize() {
    send("initialize", {
        rootPath: process.cwd(),
        processId: process.pid,
        capabilities: {
            /* ... */
        }
    });
}

reader.listen((data) => {
    console.log(data);
})

initialize();

Changelog

[0.0.3] - 2017-08-06

Added

• created a docker-langserver binary for launching the server (#134)
• textDocument/codeAction
  • created docker.command.convertToLowercase for directives not written in lowercase (#128)
• textDocument/onTypeFormatting
  • format the next line if an escape character is inserted (#130)
• textDocument/publishDiagnostics
  • validate the syntax of LABEL instructions (#100)
  • warn if invalid ONBUILD trigger instructions are used (#117)
  • warn if ENV/LABEL instructions have a blank name (#122)
  • EXPOSE
    • warn if an invalid protocol is specified (#126)
  • SHELL
    • check that SHELL instructions are written as a JSON array (#92)
    • warn if SHELL's JSON array is empty (#122)
• workspace/executeCommand
  • handle docker.command.convertToLowercase and convert the string in the range to lowercase (#128)

Fixed

• fixed parsing of escaped whitespace values in ENV instructions (#115)
• prevent undeclared variables from being suggested as completion items (#118)
• prevent completion items from being suggested in multiline instructions (#125)
• handle TCP and UDP in an EXPOSE instruction's argument (#123)
• only search for parser directives at the top of a Dockerfile (#129)
• fix handling of escape characters nested in an instruction (#131)