ftpserverlib

The library supports FTP transfer compression using the MODE Z command (deflate mode) as specified in draft-preston-ftpext-deflate-04. This allows clients to request compressed data transfers to reduce bandwidth usage.

To use this feature, a client must:

1. Send the FEAT command to verify that MODE Z is advertised in the response.
2. Send the MODE Z command to switch the transfer mode to deflate.

Note: The REST (restart) command is disallowed when using MODE Z because deflate is a streaming compression format and cannot easily resume from a specific byte offset in the compressed stream.

FEAT -> 211 MODE Z
MODE Z -> 200 Using deflate mode

The base ClientDriver (which implements afero.Fs) can be extended to support specific FTP commands that are not part of standard filesystem operations. If your ClientDriver implements these interfaces, the server will automatically enable the corresponding commands:

• ALLO (File Allocation): Implement ClientDriverExtensionAllocate to use AllocateSpace(size int) error.
• AVBL (Available Space): Implement ClientDriverExtensionAvailableSpace to use GetAvailableSpace(dirName string) (int64, error).
• SITE SYMLINK (Symbolic Links): Implement ClientDriverExtensionSymlink to use Symlink(oldname, newname string) error.
• HASH (File Hashing): Implement ClientDriverExtensionHasher to use ComputeHash(name string, algo HASHAlgo, startOffset, endOffset int64) (string, error). Note: EnableHASH must be set to true in Settings for this to work.

If you want to suppress all logs from the library, you can initialize a discard logger using slog.NewTextHandler with io.Discard. This replaces the previous lognoop implementation.

// Create a no-op logger that discards all output
logger := slog.New(slog.NewTextHandler(io.Discard, nil))

The library uses Go's standard library log/slog for structured logging. To customize the log output (e.g., to use JSON format or change the log level), you should configure the global slog logger before initializing the FTP server. This allows you to control how the library's internal logs are formatted and where they are sent.

// Example: Configure JSON structured logging globally
handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
    Level: slog.LevelDebug,
})
slog.SetDefault(slog.New(handler))

// Then create the FTP server
server, err := ftpserver.NewFtpServer(driver)

The passiveTransferHandler manages the lifecycle of a passive data connection. When a client initiates a transfer, the server waits for a connection on a listener. The duration the server waits is determined by the ConnectionTimeout setting in the server's Settings object.

If a connection is not established within this timeout, the Open() method (which calls ConnectionWait) will return an error.

The MainDriver can be augmented by implementing several optional extension interfaces to customize specific parts of the connection lifecycle:

• MainDriverExtensionTLSVerifier: Verify TLS connections during the USER command.
• MainDriverExtensionPassiveWrapper: Wrap the listener used for passive data connections.
• MainDriverExtensionUserVerifier: Control user access after the username is known but before authentication.
• MainDriverExtensionPostAuthMessage: Send a custom message immediately after successful authentication.
• MainDriverExtensionQuitMessage: Define the message displayed when a user quits.

The clientHandler (internal to the package but accessible via the ClientDriver interface) manages the lifecycle of an FTP client connection. It tracks the current working directory (Path), the last used list path (ListPath), and TLS requirements.

Key methods for interacting with a client's state include:

• Path(): Returns the current working directory.
• SetPath(value string): Changes the current working directory.
• ID(): Returns the unique client ID.
• RemoteAddr() / LocalAddr(): Returns the network addresses.
• SetExtra(extra any) / Extra(): Allows attaching application-specific data to the client session.

You can control the balance between CPU usage and compression efficiency by setting the DeflateCompressionLevel in the Settings struct.

It is recommended to use a level between 5 and 6 for a good balance. Higher levels (like 9) are more CPU-intensive and may lead to CPU exhaustion under heavy load.

The FtpServer manages client connections concurrently. When a connection is accepted via Serve(), the server increments a client counter and spawns a new clientHandler in a separate goroutine to handle the FTP command loop.

Common Errors:

• ErrNotListening: Returned when attempting to Stop() a server that hasn't started listening.
• newNetworkError: Returned when network-level failures occur (e.g., failing to bind to a port).
• newDriverError: Returned when the provided MainDriver fails to provide necessary configuration like Settings or TLSConfig.

The ClientDriver is the interface used to provide the filesystem backend for an authenticated client. It is directly based on afero.Fs. When a user authenticates via MainDriver.AuthUser, you return an implementation of ClientDriver that allows the client to perform standard file operations (upload, download, list, etc.) on your chosen backend.

type ClientDriver interface {
	afero.Fs
}