sftp-promises
Version:
SFTP Promise wrapper for ssh2 SFTP commands
106 lines (66 loc) • 5.62 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Home</title>
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>
<body>
<div id="main">
<h1 class="page-title">Home</h1>
<h3> </h3>
<section>
<article><h1>sftp-promises</h1><p><a href="https://npmjs.org/package/sftp-promises"><img src="http://img.shields.io/npm/v/sftp-promises.svg?style=flat" alt="NPM version"></a><a href="https://coveralls.io/github/brokenbot/sftp-promises?branch=master"><img src="https://coveralls.io/repos/brokenbot/sftp-promises/badge.svg?branch=master&service=github" alt="Coverage Status"></a><a href="https://travis-ci.org/brokenbot/sftp-promises"><img src="https://travis-ci.org/brokenbot/sftp-promises.svg?branch=master" alt="Build Status"></a></p>
<blockquote>
<p>SFTP Promise Wrapper for ssh2</p>
</blockquote>
<p>Support basic SFTP transaction with promises, specifically for fronting SFTP with a web based API using something like Koa</p>
<h3>Warning</h3><p>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. </p>
<h1>Usage</h1><p><em><strong>One connection per call</strong></em></p>
<pre class="prettyprint source lang-javascript"><code>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) })</code></pre><p><em><strong>Persistent Session calls (Experimental)</strong></em></p>
<pre class="prettyprint source lang-javascript"><code>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()</code></pre><p>config options are the same as <a href="https://github.com/mscdex/ssh2">ssh2</a> config options.</p>
<h1>Supported calls</h1><blockquote>
<p>All calls take an optional ssh2 Connction object as the final arguement for using persistent session.</p>
</blockquote>
<p><strong>sftp.stat(\<string>remote_path, [ssh2.Connection]session)</strong> returns a promise with on object containing path attributes<br><strong>sftp.ls(\<string>remote_path, [ssh2.Connection]session)</strong> returns a promise with an object descibing the path<br><strong>sftp.getBuffer(\<string>remote_path, [ssh2.Connection]session)</strong> returns a promise with a buffer containing the file contents<br><strong>sftp.putBuffer(\<Buffer>data, \<string>remote_path, [ssh2.Connection]session)</strong> returns a promise with a boolean, true if successful<br><strong>sftp.get(\<string>remote_path, \<string>local_path, [ssh2.Connection]session)</strong> returns a promise with a boolean, true if successful<br><strong>sftp.put(\<string>local_path, \<string>remote_path, [ssh2.Connection]session)</strong> returns a promise with a boolean, true if successful<br><strong>sftp.rm(\<string>location, [ssh2.Connection]session)</strong> returns a promise with a boolean, true if successful<br><strong>sftp.mv(\<string>src, \<string>dest, [ssh2.Connection]session)</strong> returns a promise with a boolean, true if successful
<strong>sftp.mkdir(\<string>path, [ssh2.Connection]session)</strong> returns a promise with a boolean, true if successful
<strong>sftp.rmdir(\<string>path, [ssh2.Connection]session)</strong> returns a promise with a boolean, true if successful
<strong>sftp.getStream(\<string>path, <writableStream>writableStream, [ssh2.Connection]session)</strong> returns a promise with a boolean, true if stream write completed<br><strong>sftp.putStream(\<string>path, <writableStream>writableStream, [ssh2.Connection]session)</strong> returns a promise with a boolean, true is stream write completed<br><strong>sftp.createReadStream(\<string>path, [ssh2.Connection]session)</strong> returns a promise with a readStream (ssh session will terminate on streams events close and error)<br><strong>sftp.createWriteStream(\<string>path, [ssh2.Connection]session)</strong> returns a promise with a writeStream (ssh session will terminate on streams events close and error) </p>
<h1>ToDo</h1><ul>
<li>better testing of sessions</li>
<li>validate sftp session is actually a valid ssh session</li>
<li>mkdir recursive</li>
<li>rmdir recursive</li>
<li>ability to add options to be passed to underlying ssh2 connections</li>
<li>better documentation</li>
</ul></article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="SFTPClient.html">SFTPClient</a></li></ul>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Thu May 24 2018 15:49:32 GMT-0600 (MDT)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>