Categorygithub.com/tera-insights/sftp
modulepackage
2.0.0-alpha+incompatible
Repository: https://github.com/tera-insights/sftp.git
Documentation: pkg.go.dev

# README

Golang SFTP Server

GoDoc

The sftp package implements the SFTP server protocol. To serve SFTP, you need only an io.ReadWriter for the packet transport (typically this will be an SSH channel), and a RequestHandler implementation.

This package currently provides two RequestHandler implementations for your convenience: an in-memory filesystem (MemFS) and a wrapper around the OS filesystem (HostFS). Both implementations are excellent references for writing your own driver.

See the GoDoc for full documentation and small examples. Larger examples can be found in the examples/ folder.

Contributing

We welcome pull requests, bug fixes and issue reports.

Before proposing a large change, first please discuss your change by raising an issue.

For API/code bugs, please include a small, self contained code example to reproduce the issue. For pull requests, remember test coverage.

We try to handle issues and pull requests with a 0 open philosophy. That means we will try to address the submission as soon as possible and will work toward a resolution. If progress can no longer be made (eg. unreproducible bug) or stops (eg. unresponsive submitter), we will close the bug.

Thanks.

Navigating the Source Code

The SFTP protocol spec used for reference can be found here. Please also review the OpenSSH extensions and changes, as they influenced most of the SFTP ecosystem.

  • packets.go

    All (un)marshaling code for standard SFTP packets. Please respect the fxp<type>Pkt naming convention. Do not propose using the reflect or encoding/binary packages for marshaling unless you can prove that they are not vastly slower than manually-written marshaling code.

    Note: Packets do not technically adhere to the encoding.BinaryMarshaler/Unmarshaler interfaces. This is done for significant performance gains, and packet types are not exposed by the package so it should be a non-issue. Namely, fxpWritePkt retains a subslice of the data passed to Unmarshal, and packets cannot directly unmarshal themselves from their marshaled forms. Both of these gotchas should be pretty easy to keep in check and allow for minimal copying and memory usage.

  • packets_extended.go

    All (un)marshaling code for extended packets. Please respect the fxpExt<type>Pkt naming convention and read the packets.go note above.

  • sftp.go

    Contains all the SFTP protocol constants, like packet types and file open flags. Please respect the fxp<type> naming convention, e.g. SSH_FXP_INIT becomes fxpInit and SSH_FXP_READDIR becomes fxpReaddir.

  • server.go

    Contains the Serve(io.ReadWriter, RequestHandler) implementation and also the RequestHandler interface.

  • handler_*.go

    Each RequestHandler implementation gets its own file, prefixed with handler_.

  • TODO(samterainsights): rest of the files cleanup/documentation...

# Packages

No description provided by the author
No description provided by the author

# Functions

HostFS creates a RequestHandler wrapping the OS filesystem.
MemFS creates a new in-memory filesystem capable of servicing SFTP requests.
Serve the SFTP protocol over a connection.

# Constants

AttrFlagAcModTime indicates the access time and modification time fields are present on a FileAttr.
AttrFlagExtended indicates that extensions are present on a FileAttr.
AttrFlagPermissions indicates that the permissions field is present on a FileAttr.
AttrFlagSize indicates that the size field is present on a FileAttr.
AttrFlagUIDGID indicates that the UID/GID fields are present on a FileAttr.
ErrBadMessage means an incorrectly formatted packet or protocol incompatibility was detected; directly translates to SSH_FX_BAD_MESSAGE.
ErrConnectionLost is a client-generated pseudo-error indicating that connection to the server has been lost; directly translates to SSH_FX_CONNECTION_LOST.
ErrEOF indicates end-of-file; directly translates to SSH_FX_EOF.
ErrGeneric indicates that some error occurred; directly translates to SSH_FX_FAILURE.
ErrIsADirectory indicates that the given path exists but is a directory in a context where a directory cannot be used; directly translates to SSH_FX_FILE_IS_A_DIRECTORY.
ErrNoConnection is a client-generated pseudo-error indicating that it has no connection to the server; directly translates to SSH_FX_NO_CONNECTION.
ErrNoSuchFile means a reference was made to a path which does not exist; directly translates to SSH_FX_NO_SUCH_FILE.
ErrNotADirectory indicates that the given path exists but is not a directory when a directory is required; directly translates to SSH_FX_NOT_A_DIRECTORY.
ErrOpUnsupported indicates that an operation is not implemented by the server; directly translates to SSH_FX_OP_UNSUPPORTED.
ErrPermDenied means the client does not have sufficient permissions to perform the operation; directly translates to SSH_FX_PERMISSION_DENIED.
MaxReaddirItems is the maximum number of files to return for a single SSH_FXP_READDIR request.
PFlagAppend forces all writes to append data to the end of any existing file (overrides PFlagTruncate).
PFlagCreate means the file should be created if it does not already exist.
PFlagExclusive means the request should fail if the file already exists.
PFlagRead means open the file for reading.
PFlagTruncate means an existing file must be truncated, i.e.
PFlagWrite means open the file for writing.
ProtocolVersion is the SFTP version implemented by this library.

# Structs

An Extension is a key-value pair where the name is the extension name and the value is some abitrary data encoded as a string.
FileAttr is a Golang idiomatic represention of the SFTP file attributes present on some requests, described here: https://tools.ietf.org/html/draft-ietf-secsh-filexfer-02#section-5 TODO(samterainsights): validate flags on incoming packets and return a protocol error per the spec if unknown flags are set.
HostFSOpts is used to configure a HostFS RequestHandler.
A StatusError is returned when an SFTP operation fails, and provides additional information about the failure.
A StatVFS contains detailed information about a virtual filesystem.

# Interfaces

DirReader is the interface that wraps the basic ReadEntries method.
A FileHandle is an TODO(samterainsights).
RequestHandler is responsible for handling the various kinds of SFTP requests.