target_remote

Home >> Targets >> remote

Remote machines like other VS Code instances

Deploys to a remote machine over a TCP connection.

If you want to receive files from a remote machine, you have to setup your VS Code as host.

{
    "deploy": {
        "targets": [
            {
                "type": "remote",
                "name": "My remote target",
                "description": "Some remote VS Code instances to deploy to",

                "hosts": ["localhost", "192.168.0.101", "192.168.0.102:5979"]
            }
        ]
    }
}

Name	Description
hosts	One or more host to deploy to.
messageTransformer*	The optional path to the script that transforms the data of a whole message BEFORE it is send. s. Transform data
messageTransformerOptions	The data for the "message data transformation", if needed.
password	An optional password to use for encrypting the data to send.
passwordAlgorithm	The algorithm for the password to use (s. crypto.createCipher). Default: aes-256-ctr
tag	An optional value that also should be submitted with each JSON file message.
transformer*	The optional path to the script that transforms the data of a file BEFORE it is send. s. Transform data
transformerOptions	The data for the "file data transformation", if needed.

^{* supports placeholders}

How it works

Files are send and received as UTF-8 encoded JSON strings with the following interface:

interface RemoteFile {
    /**
     * The Base64 encoded data.
     */
    data?: string;
    /**
     * Is 'data' compressed with GZIP or not?
     */
    isCompressed?: boolean;
    /**
     * Indicates if that file is the first one or not.
     */
    isFirst?: boolean;
    /**
     * Indicates if that file is the last one or not.
     */
    isLast?: boolean;
    /**
     * The name / relative path of the file to send.
     */
    name: string;
    /**
     * The number / index of the file (beginning at 1).
     */
    nr?: number;
    /**
     * The ID of the session / transaction.
     */
    session?: string;
    /**
     * A custom value for the remote machine from the settings of the sending client.
     */
    tag?: any;
    /**
     * The total number of files that will be send.
     */
    totalCount?: number;
}

Send file

The following TypeScript code shows how to create the binary package, that has to be send over the network:

import * as ZLIB from 'zlib';

// loading the file content into 'fileData'
// as Buffer...

let fileToSend: RemoteFile = {
    data: ZLIB.gzipSync(fileData)
              .toString('base64'),
    isCompressed: true,
    name: '/the/path/to/the/file.txt',
};

// UTF-8 encoded JSON of 'fileToSend'
let jsonToSend = new Buffer(JSON.stringify(fileToSend),
                            'utf8');

Now a binary package is build from 'jsonToSend':

// [0-3] jsonToSend.length
//  [4+] jsonToSend
let binaryPackage = Buffer.alloc(4 +
                                 jsonToSend.length);

// first the length of 'jsonToSend' is send
binaryPackage.writeUInt32LE(jsonToSend.length, 0);

// then the data of 'jsonToSend' itself
jsonToSend.copy(binaryPackage, 4);

Receive file

The following TypeScript code shows how to create the JSON object from the data, that has been received from the network:

import * as ZLIB from 'zlib';

// received the binary package into 'binaryPackage'
// as Buffer...

// the first 4 bytes are the length of the JSON
let jsonLength = binaryPackage.readUInt32LE(0);

// at the 5th byte (offset 4)
// there is our json data
let json = Buffer.alloc(jsonLength);
binaryPackage.copy(json, 0, 4);

// create an object from it
let receivedFile: RemoteFile = JSON.parse(json.toString('utf8'));

let fileData = new Buffer(receivedFile.data, 'base64');
if (receivedFile.isCompressed) {
    fileData = ZLIB.gunzipSync(fileData);  // before we can use it
                                           // we have to decompress it
}

Passwords

If the password setting is defined, the extension uses crypto library to encrypt

// store data to send in 'jsonToSend'
// store 'password' setting in 'pwd'
// store 'passwordAlgorithm' setting in 'pwdAlgo'

import * as Crypto from 'crypto';

let cipher = Crypto.createCipher(pwdAlgo, pwd);

let a = cipher.update(jsonToSend);
let b = cipher.final();

let encryptedJson = Buffer.concat([a, b]);

and decrypt

// store received data in 'encryptedJson'
// store 'password' setting in 'pwd'
// store 'passwordAlgorithm' setting in 'pwdAlgo'

import * as Crypto from 'crypto';

let decipher = Crypto.createDecipher(pwdAlgo, pwd);

let a = decipher.update(encryptedJson);
let b = decipher.final();

let receivedFile = Buffer.concat([a, b]);

the whole JSON data, by using aes-256-ctr algorithm as default.

Security hint

Data is send uncrypted by default!

If you have sensitive code that is being to be transfered, you should use things like a proxy, a VPN connection, a data transformer (s. messageTransformer and transformer target settings) or, what is the easiest way, a (strong) password.