jsftp-mlst

Adds MLST/MLSD support to JSFtp for ftp servers that support the 'MSLT' feature.

Reference:

JSFtp Homepage

RFC 3659 - Extensions to FTP

Be sure to check that the Ftp server supports MLST/MLSD feature before using this. See How To below. MLST support by the server implies MLSD support as well.

If the Create and Modify facts are present in the MLST/MLSD server response, they are parsed and the attributes create_dt and modify_dt, respectively, are added to the entry object. create_dt and modify_dt are ISO 8601 combined date and time strings in UTC. If Create and/or Modify cannot be parsed, create_error and/or modify_error messages, as appropriate, will added to the Entry object.

Fact names are normalized to lower case in the entry objects.

Added Methods

Ftp.mlst(pathname, callback)

With the mlst method you can retrieve the MLST entry for pathname. The method accepts a callback with the signature err, entry, in which err is the error response coming from the server (usually a 4xx or 5xx error code), or an error indicating the MLST response couldn't be parsed as expected, and entry is an object containing the entry facts returned by the server.

Pathname is optional. If omitted, the server is expected to return an MLST entry for the current working directory.

"use strict";

/**
 * Example using mlst
 */

const jsftp = require("jsftp");
require("jsftp-mlst")(jsftp);

const Ftp = new jsftp({
  host: "your.ftpserver.com",
  user: "ftpusername",
  pass: "ftppassword",
});


Ftp.on("connect", function() {
  Ftp.mlst("myfile.txt", (err, result) => {
    if (err) {
      console.log(err);
    } else {
      console.log(result);
    // Prints something like
    // { pathname: '/myfile.txt',
    //   create_dt: '2017-06-14T20:06:11+00:00',
    //   create: '20170614200611',
    //   modify_dt: '2017-06-14T20:06:11+00:00',
    //   modify: '20170614200611',
    //   perm: 'adfrw',
    //   size: '2291365',
    //   type: 'file',
    //   unique: 'ca032380be1',
    //   'unix.group': '501',
    //   'unix.mode': '0644',
    //  'unix.owner': '501' }
    }

    Ftp.destroy();
  });
});

Ftp.mlsd(pathname, callback)

With the mlsd method you can retrieve the contents of the directory specified with pathname. The mlsd method accepts a callback with the signature err, entries where err is the error response coming from the server or error processing the server response, and entries is an array of entry objects containing the facts returned by the server for each item in the directory (usually includes the dir itself).

pathname is optional. If omitted, the server is expected to return the contents of the current working directory.

"use strict";

/**
 * Example using mlsd
 */

const jsftp = require("jsftp");
require("jsftp-mlst")(jsftp);

const Ftp = new jsftp({
  host: "your.ftpserver.com",
  user: "ftpusername",
  pass: "ftppassword",
});


Ftp.on("connect", function() {
  Ftp.mlsd("/", (err, entries) => {
    if (err) {
      console.log(err);
    } else {
      console.log(entries);
          // Prints something like
          // [{ pathname: 'myfile.txt',
          //   modify_dt: '2017-06-14T20:06:11+00:00',
          //   modify: '20170614200611',
          //   perm: 'adfrw',
          //   size: '2291365',
          //   type: 'file',
          //   unique: 'ca032380be1',
          //   'unix.group': '501',
          //   'unix.mode': '0644',
          //  'unix.owner': '501' },
          // { pathname: '..',
          //   modify_dt: '2017-06-14T20:06:19+00:00',
          //   modify: '20170614200619',
          //   perm: 'flcdmpe',
          //   type: 'pdir',
          //   unique: 'ca01u82148',
          //   'unix.group': '501',
          //   'unix.mode': '0700',
          //   'unix.owner': '501' },
          // { pathname: '.',
          //   modify_dt: '2017-06-14T20:06:19+00:00',
          //   modify: '20170614200619',
          //   perm: 'flcdmpe',
          //   type: 'cdir',
          //   unique: 'ca01u82148',
          //   'unix.group': '501',
          //   'unix.mode': '0700',
          //   'unix.owner': '501' }]
    }
    Ftp.destroy();
  });
});

Other Notes

OS Dependent Facts have a '.' in their names (see 'unix.xxx' facts in examples above). If you need to read them you'll have to do something like: entry['unix.mode']

MLSD/MLST implementation specifics vary across Ftp servers. The facts you receive may be quite different than the examples above.

I tried to stick to the language support and eslint config of the jsftp project for consistency.

How To Test For MLST Feature Support

The MLST feature has an extended format in the FEAT ftp command response so the hasFeat method from JsFTP doesn't properly detect it. Here's an example of my current recommendation for how to detect it:

"use strict";

/**
 * Example checking for MLST support
 */

const jsftp = require("jsftp");
require("jsftp-mlst")(jsftp);

const Ftp = new jsftp({
  host: "your.ftpserver.com",
  user: "ftpusername",
  pass: "ftppassword",
});


Ftp.on("connect", function() {
  Ftp.getFeatures((err, features) => {
    // ... IRL handle err from getFeatures here!
    if (features.some(feat => feat.startsWith("mlst"))) { // mlst needs to be lowercase here
      // server has MLST/MLSD support!
      Ftp.mlst("/", (err, entries) => {
        if (err) {
          console.log(err);
        } else {
          console.log(entries);
        }
      });
    } else {
      // server does not support MLST/MLSD
      console.log('server does not support MLST/MLSD');
    }
  });
});

Of course, you could also just call mlst or mlsd and handle the error that is passed to your callback if the server doesn't support it.