Skip to content

Latest commit

 

History

History
405 lines (225 loc) · 22.4 KB

SFTPStream.md

File metadata and controls

405 lines (225 loc) · 22.4 KB
Raw

SFTPStream events

Client/Server events

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

Server-only events

Responses to these client requests are sent using one of the methods listed further in this document under Server-only methods. The valid response(s) for each request are documented below.

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

    flags is a bitfield containing any of the flags defined in SFTPStream.OPEN_MODE. Use the static method SFTPStream.flagsToString() to convert the value to a mode string to be used by fs.open() (e.g. 'r').

    Respond using one of the following:

    • handle() - This indicates a successful opening of the file and passes the given handle back to the client to use to refer to this open file for future operations (e.g. reading, writing, closing).

    • status() - Use this to indicate a failure to open the requested file.

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

    Respond using one of the following:

    • data() - Use this to send the requested chunk of data back to the client. The amount of data sent is allowed to be less than the length requested, for example if the file ends between offset and offset + length.

    • status() - Use this to indicate either end of file (STATUS_CODE.EOF) has been reached (offset is past the end of the file) or if an error occurred while reading the requested part of the file.

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

    Respond using:

    • status() - Use this to indicate success/failure of the write to the file.

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

    Respond using one of the following:

    • attrs() - Use this to send the attributes for the requested file/directory back to the client.

    • status() - Use this to indicate an error occurred while accessing the file/directory.

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

    Respond using:

    • status() - Use this to indicates success/failure of the setting of the given file/directory attributes.

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

    Respond using:

    • status() - Use this to indicate success (STATUS_CODE.OK) or failure of the closing of the file identified by handle.

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

    Respond using one of the following:

    • handle() - This indicates a successful opening of the directory and passes the given handle back to the client to use to refer to this open directory for future operations (e.g. reading directory contents, closing).

    • status() - Use this to indicate a failure to open the requested directory.

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

    Respond using one of the following:

    • name() - Use this to send one or more directory listings for the open directory back to the client.

    • status() - Use this to indicate either end of directory contents (STATUS_CODE.EOF) or if an error occurred while reading the directory contents.

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

    Respond using one of the following:

    • attrs() - Use this to send the attributes for the requested file/directory back to the client.

    • status() - Use this to indicate an error occurred while accessing the file/directory.

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

    Respond using one of the following:

    • attrs() - Use this to send the attributes for the requested file/directory back to the client.

    • status() - Use this to indicate an error occurred while accessing the file/directory.

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

    Respond using:

    • status() - Use this to indicate success/failure of the removal of the file at path.

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

    Respond using:

    • status() - Use this to indicate success/failure of the removal of the directory at path.

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

    Respond using one of the following:

    • name() - Use this to respond with a normalized version of path. No file/directory attributes are required to be sent in this response.

    • status() - Use this to indicate a failure in normalizing path.

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

    Respond using one of the following:

    • name() - Use this to respond with the target of the symlink at path. No file/directory attributes are required to be sent in this response.

    • status() - Use this to indicate a failure in reading the symlink at path.

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

    Respond using:

    • status() - Use this to indicates success/failure of the setting of the given file/directory attributes.

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

    Respond using:

    • status() - Use this to indicate success/failure of the creation of the directory at path.

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

    Respond using:

    • status() - Use this to indicate success/failure of the renaming of the file/directory at oldPath to newPath.

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

    Respond using:

    • status() - Use this to indicate success/failure of the symlink creation.

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 methods

  • SFTPStream.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.

  • SFTPStream.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: 64

    • 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: 64

    • 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

    • mode - mixed - Integer or string representing the file mode to set for the uploaded file.

    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: 0o666,
  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: 0o666,
  autoClose: true
}

    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 >flags, [< mixed >attrs_mode, ]< function >callback) - boolean - Opens a file filename with flags with optional ATTRS object or file mode attrs_mode. flags is any of the flags supported by fs.open (except sync flag). 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 and is an opaque value that could merely contain the value of a backing file descriptor or some other unique, custom value. 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()