RGET-JSFTP

A client FTP module to download files or folders with a connection pool for manage the FTP access. This nodeJS module uses :

• jsftp to connect and to request the FTP server
• node-pool to manage the FTP connections

How do you use it

Step 1 - Import module

var rget = require('rget-jsftp');

Step 2 - Instantiate "rget"

A rget client instance can connect to only one FTP server, if you want to connect to two servers you must instantiate two clients.

ver rgetClient = rget.RGet({
    ... // params
});

All possible parameters are :

{
    'stepDataEvent': 5000000,
    'maxShortConnections': 4,
    'maxLongConnections': 4,
    'idleShortConnection': 30000,
    'idleLongConnection': 30000,
    'host': '',
    'port': 21,
    'username': '',
    'password': ''
}

Parameter name	Description
stepDataEvent	Indicate how often of data reception (in bytes) must be executed the event "dataReceived". The default value is 5000000 bytes, ie 5 MBytes.
maxShortConnections	Indicate how many short connections can be used in the same time. A short connection is used to browse the FTP server and to prepare the download files list. The default value is 4.
maxLongConnections	Indicate how many long connections can be used in the same time. A long connection is used to download file. The default value is 4.
idleShortConnection	Indicate how many time (in millisecond) an inactive connection stays in the short pool. The default value is 30000ms whether 30 seconds.
idleLongConnection	Indicate how many time (in millisecond) an inactive connection stays in the long pool. The default value is 30000ms, ie 30 seconds.
host	The FTP connection host. This value is mandatory.
port	The FTP connection port. The default value is 21.
username	The user name for the protected FTP connection. If the value is empty the FTP connection will be anonymous.
password	The user password for the protected FTP connection.

Step 3 - Create the download context

var ctx = rgetClient.generateDownloadContext('from', 'to');
// OR
var ctx = rgetClient.generateDownloadContext('from', function(relativeFtpPath, type, object){
    return 'to';
});
 

Parameter name	Type	Description
from	String	The FTP path where "rget" will read data.
to	String or Function	The filesystem path, relative or absolute, where "rget" will write data or the function generate this path for data.

The function 'to' can take 3 parameters :

• relativeFtpPath : the data ftp path
• type : 'file'|'folder'
• object : file or folder object This function musts return a string represent the data normalized filesystem path.

With the context you can get 'files' and 'folders' concerned by the download.

Context functions :

// All files
var filesArray = ctx.files;
 
// All folders
var foldersArray = ctx.folders;
 
//
var size = ctx.getTotalSize();
 
//
var size = ctx.getDownloadedSize();
 
//
var filesArray = ctx.getNotDownloadedFiles();
 
//
var filesArray = ctx.getDownloadedFiles();
 
//
var foldersArray = ctx.getNotExploredFolders();
 
//
var foldersArray = ctx.getExploredFolders();
 
//
var filePath = ctx.getFileSource(myFile);
 
// (on the file system)
var filePath = ctx.getFileDestination(myFile);
 
//
var folderPath = ctx.getFolderSource(myFolder);
 
// (on the file system)
var folderPath = ctx.getFolderDestination(myFolder);

File

Object structure :

function () {
    "use strict";
    this.name = '';
    this.relativePath = '';
    this.size = 0;
    this.complete = 0;
};

Folder

Object structure :

var FolderToDownload = function () {
    "use strict";
    this.name = '';
    this.relativePath = '';
    this.explored = false;
};

Step 4 - Bind context events (if you want)

Context object extends "EventEmitter". So you can bind the event with callback function.

ctx.on('evName', callback);

Context event

• initialized : emit when all folders are explored Callback function is :

function() {
    ...
}

• finished : emit when all files are downloaded Callback function is :

function() {
    ...
}

File or folder event

• fileAdded : emit when file is added to the context download list Callback function is :

function(folder) {
    ...
}

• folderExplored : emit when folder is added to the context explore list Callback function is :

function(folder) {
    ...
}

• downloadStart : emit when file download starting Callback function is :

function(file) {
    ...
}

• dataReceived : emit when data is received (see "stepDataEvent" parameter) Callback function is :

function(file) {
    ...
}

• downloadFinished : emit when file is downloaded Callback function is :

function(file) {
    ...
}

Error event

• error : on error in process Callback function is :

function(err) {
    ...
}

• errorWithFile : on error with file Callback function is :

function(err, file) {
    ...
}

• timeoutWithFile : on connection timeout during file download Callback function is :

function(file) {
    ...
}

Step 5 - Start download

rgetClient.download(ctx);

Exemple

var rget = require('rget-jsftp');
 
ver rgetClient = rget.RGet({
    host: 'host',
    username: 'user',
    password: '12345',
    port: 21
});
 
var ctx = rgetClient.generateDownloadContext('from', 'to');
 
rgetClient.download(ctx);