sftp-promises

    1.8.0 • Public • Published

    sftp-promises

    NPM versionCoverage StatusBuild StatusGitpod ready-to-code

    SFTP Promise Wrapper for ssh2

    Support basic SFTP transaction with promises, specifically for fronting SFTP with a web based API using something like Koa

    Warning

    By default each request will create a new conneciton and close it when finished, this is by design as its intended to be used in stateless web applications. As such care should exercised when using on high traffic systems to avoid too many connections to SFTP server and general connection overhead.

    Usage

    One connection per call

    var config = {host: 'localhost', username: 'user', password: 'pass' };
    var SFTPClient = require('sftp-promises');
    var sftp = new SFTPClient(config);
         
    sftp.ls('.').then(function(list) { console.log(list) })

    Persistent Session calls (Experimental)

    var config = {host: 'localhost', username: 'user', password: 'pass' };
    var SFTPClient = require('sftp-promises');
    var sftp = new SFTPClient();
    
    // get session
    var session = sftp.session(config).then(function(ftpSession) { session = ftpSession })
    ...code to ensure session is ready...  
    sftp.ls('.', session).then(function(list) { console.log(list) })
    
    // close socket
    session.end()

    config options are the same as ssh2 config options.

    Supported calls

    All calls take an optional ssh2 Connction object as the final arguement for using persistent session.

    sftp.stat(<string>remote_path, [ssh2.Connection]session) returns a promise with on object containing path attributes
    sftp.ls(<string>remote_path, [ssh2.Connection]session) returns a promise with an object descibing the path
    sftp.getBuffer(<string>remote_path, [ssh2.Connection]session) returns a promise with a buffer containing the file contents
    sftp.putBuffer(<Buffer>data, <string>remote_path, [ssh2.Connection]session) returns a promise with a boolean, true if successful
    sftp.get(<string>remote_path, <string>local_path, [ssh2.Connection]session) returns a promise with a boolean, true if successful
    sftp.put(<string>local_path, <string>remote_path, [ssh2.Connection]session) returns a promise with a boolean, true if successful
    sftp.rm(<string>location, [ssh2.Connection]session) returns a promise with a boolean, true if successful
    sftp.mv(<string>src, <string>dest, [ssh2.Connection]session) returns a promise with a boolean, true if successful sftp.mkdir(<string>path, [ssh2.Connection]session) returns a promise with a boolean, true if successful sftp.rmdir(<string>path, [ssh2.Connection]session) returns a promise with a boolean, true if successful sftp.getStream(<string>path, writableStream, [ssh2.Connection]session) returns a promise with a boolean, true if stream write completed
    sftp.putStream(<string>path, writableStream, [ssh2.Connection]session) returns a promise with a boolean, true is stream write completed
    sftp.createReadStream(<string>path, [ssh2.Connection]session) returns a promise with a readStream (ssh session will terminate on streams events close and error)
    sftp.createWriteStream(<string>path, [ssh2.Connection]session) returns a promise with a writeStream (ssh session will terminate on streams events close and error)

    ToDo

    • better testing of sessions
    • validate sftp session is actually a valid ssh session
    • mkdir recursive
    • rmdir recursive
    • ability to add options to be passed to underlying ssh2 connections
    • better documentation

    Install

    npm i sftp-promises

    DownloadsWeekly Downloads

    3,338

    Version

    1.8.0

    License

    BSD-3-Clause

    Unpacked Size

    2.54 MB

    Total Files

    68

    Last publish

    Collaborators

    • brokenbot