Skip to content

SFTPStream.md

Latest commit

 

History

History
276 lines (144 loc) · 17.8 KB

SFTPStream.md

File metadata and controls

276 lines (144 loc) · 17.8 KB

SFTPStream events

Client/Server events

  • ready() - Emitted after initial protocol version check has passed.

Server-only events

  • OPEN(< integer >reqID, < string >filename, < integer >flags, < ATTRS>attrs)

  • READ(< integer >reqID, < Buffer >handle, < integer >offset, < integer >length)

  • WRITE(< integer >reqID, < Buffer >handle, < integer >offset, < Buffer >data)

  • FSTAT(< integer >reqID, < Buffer >handle)

  • FSETSTAT(< integer >reqID, < Buffer >handle, < ATTRS >attrs)

  • CLOSE(< integer >reqID, < Buffer >handle)

  • OPENDIR(< integer >reqID, < string >path)

  • READDIR(< integer >reqID, < Buffer >handle)

  • LSTAT(< integer >reqID, < string >path)

  • STAT(< integer >reqID, < string >path)

  • REMOVE(< integer >reqID, < string >path)

  • RMDIR(< integer >reqID, < string >path)

  • REALPATH(< integer >reqID, < string >path)

  • READLINK(< integer >reqID, < string >path)

  • SETSTAT(< integer >reqID, < string >path, < ATTRS >attrs)

  • MKDIR(< integer >reqID, < string >path, < ATTRS >attrs)

  • RENAME(< integer >reqID, < string >oldPath, < string >newPath)

  • SYMLINK(< integer >reqID, < string >linkPath, < string >targetPath)

SFTPStream static constants

  • SFTPStream.STATUS_CODE - object - Contains the various status codes (for use especially with status()):

    • OK

    • EOF

    • NO_SUCH_FILE

    • PERMISSION_DENIED

    • FAILURE

    • BAD_MESSAGE

    • OP_UNSUPPORTED

  • SFTPStream.OPEN_MODE - object - Contains the various open file flags:

    • READ

    • WRITE

    • APPEND

    • CREAT

    • TRUNC

    • EXCL

SFTPStream static constants

  • stringToFlags(< string >flagsStr) - integer - Converts string flags (e.g. 'r', 'a+', etc.) to the appropriate SFTPStream.OPEN_MODE flag mask. Returns null if conversion failed.

  • flagsToString(< integer >flagsMask) - string - Converts flag mask (e.g. number containing SFTPStream.OPEN_MODE values) to the appropriate string value. Returns null if conversion failed.

SFTPStream methods

  • (constructor)(< object >config[, < string >remoteIdentRaw]) - Creates and returns a new SFTPStream instance. SFTPStream instances are Duplex streams. remoteIdentRaw can be the raw SSH identification string of the remote party. This is used to change internal behavior based on particular SFTP implementations. config can contain:

    • server - boolean - Set to true to create an instance in server mode. Default: false

    • highWaterMark - integer - This is the highWaterMark to use for the stream. Default: 32 * 1024

    • debug - function - Set this to a function that receives a single string argument to get detailed (local) debug information. Default: (none)

Client-only methods

  • fastGet(< string >remotePath, < string >localPath[, < object >options], < function >callback) - (void) - Downloads a file at remotePath to localPath using parallel reads for faster throughput. options can have the following properties:

    • concurrency - integer - Number of concurrent reads Default: 25

    • chunkSize - integer - Size of each read in bytes Default: 32768

    • step - function(< integer >total_transferred, < integer >chunk, < integer >total) - Called every time a part of a file was transferred

    callback has 1 parameter: < Error >err.

  • fastPut(< string >localPath, < string >remotePath[, < object >options], < function >callback) - (void) - Uploads a file from localPath to remotePath using parallel reads for faster throughput. options can have the following properties:

    • concurrency - integer - Number of concurrent reads Default: 25

    • chunkSize - integer - Size of each read in bytes Default: 32768

    • step - function(< integer >total_transferred, < integer >chunk, < integer >total) - Called every time a part of a file was transferred

    callback has 1 parameter: < Error >err.

  • createReadStream(< string >path[, < object >options]) - ReadStream - Returns a new readable stream for path. options has the following defaults:

    { flags: 'r',
  encoding: null,
  handle: null,
  mode: 0666,
  autoClose: true
}

    options can include start and end values to read a range of bytes from the file instead of the entire file. Both start and end are inclusive and start at 0. The encoding can be 'utf8', 'ascii', or 'base64'.

    If autoClose is false, then the file handle won't be closed, even if there's an error. It is your responsiblity to close it and make sure there's no file handle leak. If autoClose is set to true (default behavior), on error or end the file handle will be closed automatically.

    An example to read the last 10 bytes of a file which is 100 bytes long:

    sftp.createReadStream('sample.txt', {start: 90, end: 99});

  • createWriteStream(< string >path[, < object >options]) - WriteStream - Returns a new writable stream for path. options has the following defaults:

    { flags: 'w',
  encoding: null,
  mode: 0666 }

    options may also include a start option to allow writing data at some position past the beginning of the file. Modifying a file rather than replacing it may require a flags mode of 'r+' rather than the default mode 'w'.

    If 'autoClose' is set to false and you pipe to this stream, this stream will not automatically close after there is no more data upstream -- allowing future pipes and/or manual writes.

  • open(< string >filename, < string >mode, [< ATTRS >attributes, ]< function >callback) - boolean - Opens a file filename for mode with optional attributes. mode is any of the modes supported by fs.open (except sync mode). Returns false if you should wait for the continue event before sending any more traffic. callback has 2 parameters: < Error >err, < Buffer >handle.

  • close(< Buffer >handle, < function >callback) - boolean - Closes the resource associated with handle given by open() or opendir(). Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

  • readData(< Buffer >handle, < Buffer >buffer, < integer >offset, < integer >length, < integer >position, < function >callback) - boolean - Reads length bytes from the resource associated with handle starting at position and stores the bytes in buffer starting at offset. Returns false if you should wait for the continue event before sending any more traffic. callback has 4 parameters: < Error >err, < integer >bytesRead, < Buffer >buffer (offset adjusted), < integer >position.

  • writeData(< Buffer >handle, < Buffer >buffer, < integer >offset, < integer >length, < integer >position, < function >callback) - boolean - Writes length bytes from buffer starting at offset to the resource associated with handle starting at position. Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

  • fstat(< Buffer >handle, < function >callback) - boolean - Retrieves attributes for the resource associated with handle. Returns false if you should wait for the continue event before sending any more traffic. callback has 2 parameters: < Error >err, < Stats >stats.

  • fsetstat(< Buffer >handle, < ATTRS >attributes, < function >callback) - boolean - Sets the attributes defined in attributes for the resource associated with handle. Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

  • futimes(< Buffer >handle, < mixed >atime, < mixed >mtime, < function >callback) - boolean - Sets the access time and modified time for the resource associated with handle. atime and mtime can be Date instances or UNIX timestamps. Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

  • fchown(< Buffer >handle, < integer >uid, < integer >gid, < function >callback) - boolean - Sets the owner for the resource associated with handle. Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

  • fchmod(< Buffer >handle, < mixed >mode, < function >callback) - boolean - Sets the mode for the resource associated with handle. mode can be an integer or a string containing an octal number. Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

  • opendir(< string >path, < function >callback) - boolean - Opens a directory path. Returns false if you should wait for the continue event before sending any more traffic. callback has 2 parameters: < Error >err, < Buffer >handle.

  • readdir(< mixed >location, < function >callback) - boolean - Retrieves a directory listing. location can either be a Buffer containing a valid directory handle from opendir() or a string containing the path to a directory. Returns false if you should wait for the continue event before sending any more traffic. callback has 2 parameters: < Error >err, < mixed >list. list is an Array of { filename: 'foo', longname: '....', attrs: {...} } style objects (attrs is of type ATTR). If location is a directory handle, this function may need to be called multiple times until list is boolean false, which indicates that no more directory entries are available for that directory handle.

  • unlink(< string >path, < function >callback) - boolean - Removes the file/symlink at path. Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

  • rename(< string >srcPath, < string >destPath, < function >callback) - boolean - Renames/moves srcPath to destPath. Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

  • mkdir(< string >path, [< ATTRS >attributes, ]< function >callback) - boolean - Creates a new directory path. Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

  • rmdir(< string >path, < function >callback) - boolean - Removes the directory at path. Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

  • stat(< string >path, < function >callback) - boolean - Retrieves attributes for path. Returns false if you should wait for the continue event before sending any more traffic. callback has 2 parameter: < Error >err, < Stats >stats.

  • lstat(< string >path, < function >callback) - boolean - Retrieves attributes for path. If path is a symlink, the link itself is stat'ed instead of the resource it refers to. Returns false if you should wait for the continue event before sending any more traffic. callback has 2 parameters: < Error >err, < Stats >stats.

  • setstat(< string >path, < ATTRS >attributes, < function >callback) - boolean - Sets the attributes defined in attributes for path. Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

  • utimes(< string >path, < mixed >atime, < mixed >mtime, < function >callback) - boolean - Sets the access time and modified time for path. atime and mtime can be Date instances or UNIX timestamps. Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

  • chown(< string >path, < integer >uid, < integer >gid, < function >callback) - boolean - Sets the owner for path. Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

  • chmod(< string >path, < mixed >mode, < function >callback) - boolean - Sets the mode for path. mode can be an integer or a string containing an octal number. Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

  • readlink(< string >path, < function >callback) - boolean - Retrieves the target for a symlink at path. Returns false if you should wait for the continue event before sending any more traffic. callback has 2 parameters: < Error >err, < string >target.

  • symlink(< string >targetPath, < string >linkPath, < function >callback) - boolean - Creates a symlink at linkPath to targetPath. Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

  • realpath(< string >path, < function >callback) - boolean - Resolves path to an absolute path. Returns false if you should wait for the continue event before sending any more traffic. callback has 2 parameters: < Error >err, < string >absPath.

  • ext_openssh_rename(< string >srcPath, < string >destPath, < function >callback) - boolean - OpenSSH extension Performs POSIX rename(3) from srcPath to destPath. Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

  • ext_openssh_statvfs(< string >path, < function >callback) - boolean - OpenSSH extension Performs POSIX statvfs(2) on path. Returns false if you should wait for the continue event before sending any more traffic. callback has 2 parameters: < Error >err, < object >fsInfo. fsInfo contains the information as found in the statvfs struct.

  • ext_openssh_fstatvfs(< Buffer >handle, < function >callback) - boolean - OpenSSH extension Performs POSIX fstatvfs(2) on open handle handle. Returns false if you should wait for the continue event before sending any more traffic. callback has 2 parameters: < Error >err, < object >fsInfo. fsInfo contains the information as found in the statvfs struct.

  • ext_openssh_hardlink(< string >targetPath, < string >linkPath, < function >callback) - boolean - OpenSSH extension Performs POSIX link(2) to create a hard link to targetPath at linkPath. Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

  • ext_openssh_fsync(< Buffer >handle, < function >callback) - boolean - OpenSSH extension Performs POSIX fsync(3) on the open handle handle. Returns false if you should wait for the continue event before sending any more traffic. callback has 1 parameter: < Error >err.

Server-only methods

  • status(< integer >reqID, < integer >statusCode[, < string >message]) - boolean - Sends a status response for the request identified by id. Returns false if you should wait for the continue event before sending any more traffic.

  • handle(< integer >reqID, < Buffer >handle) - boolean - Sends a handle response for the request identified by id. handle must be less than 256 bytes. Returns false if you should wait for the continue event before sending any more traffic.

  • data(< integer >reqID, < mixed >data[, < string >encoding]) - boolean - Sends a data response for the request identified by id. data can be a Buffer or string. If data is a string, encoding is the encoding of data. Returns false if you should wait for the continue event before sending any more traffic.

  • name(< integer >reqID, < array >names) - boolean - Sends a name response for the request identified by id. Returns false if you should wait for the continue event before sending any more traffic. names must be an array of object where each object can contain:

    • filename - string - The entry's name.

    • longname - string - This is the ls -l-style format for the entry (e.g. -rwxr--r-- 1 bar bar 718 Dec 8 2009 foo)

    • attrs - ATTRS - This is an optional ATTRS object that contains requested/available attributes for the entry.

  • attrs(< integer >reqID, < ATTRS >attrs) - boolean - Sends an attrs response for the request identified by id. attrs contains the requested/available attributes.

ATTRS

An object with the following valid properties:

  • mode - integer - Mode/permissions for the resource.

  • uid - integer - User ID of the resource.

  • gid - integer - Group ID of the resource.

  • size - integer - Resource size in bytes.

  • atime - integer - UNIX timestamp of the access time of the resource.

  • mtime - integer - UNIX timestamp of the modified time of the resource.

When supplying an ATTRS object to one of the SFTP methods:

  • atime and mtime can be either a Date instance or a UNIX timestamp.

  • mode can either be an integer or a string containing an octal number.

Stats

An object with the same attributes as an ATTRS object with the addition of the following methods:

  • stats.isDirectory()

  • stats.isFile()

  • stats.isBlockDevice()

  • stats.isCharacterDevice()

  • stats.isSymbolicLink()

  • stats.isFIFO()

  • stats.isSocket()