golib/ftpclient/README.md

ftpclient Package

The ftpclient package provides a high-level, thread-safe FTP client abstraction for Go, built on top of jlaffaye/ftp. It simplifies FTP operations, connection management, error handling, and configuration, including TLS support and advanced options.

Features

• Thread-safe FTP client with connection pooling
• Rich configuration struct with validation (hostname, login, password, timeouts, TLS, etc.)
• Support for explicit/implicit TLS, time zones, and FTP protocol options (UTF8, EPSV, MLSD, MDTM)
• Full set of FTP commands: file/directory listing, upload, download, rename, delete, recursive removal, and more
• Custom error codes for precise diagnostics
• Context and TLS configuration registration
• Automatic connection checking and recovery

---

Main Types & Functions

Config Struct

Defines all connection and protocol options:

• Hostname: FTP server address (required, RFC1123)
• Login / Password: Credentials for authentication
• ConnTimeout: Timeout for all operations
• TimeZone: Force a specific time zone for the connection
• DisableUTF8, DisableEPSV, DisableMLSD, EnableMDTM: Protocol feature toggles
• ForceTLS: Require TLS for the connection
• TLS: TLS configuration (see github.com/nabbar/golib/certificates)
• Methods to register context and default TLS providers

Example

import (
    "github.com/nabbar/golib/ftpclient"
    "time"
)

cfg := &ftpclient.Config{
    Hostname:    "ftp.example.com:21",
    Login:       "user",
    Password:    "pass",
    ConnTimeout: 10 * time.Second,
    ForceTLS:    true,
    // ... other options
}
if err := cfg.Validate(); err != nil {
    // handle config error
}

---

FTPClient Interface

Main interface for FTP operations:

• Connect() error: Establish connection
• Check() error: Check and validate connection (NOOP)
• Close(): Close connection (QUIT)
• NameList(path string) ([]string, error): List file names (NLST)
• List(path string) ([]*ftp.Entry, error): List directory entries (LIST/MLSD)
• ChangeDir(path string) error: Change working directory (CWD)
• CurrentDir() (string, error): Get current directory (PWD)
• FileSize(path string) (int64, error): Get file size (SIZE)
• GetTime(path string) (time.Time, error): Get file modification time (MDTM)
• SetTime(path string, t time.Time) error: Set file modification time (MFMT/MDTM)
• Retr(path string) (*ftp.Response, error): Download file (RETR)
• RetrFrom(path string, offset uint64) (*ftp.Response, error): Download from offset
• Stor(path string, r io.Reader) error: Upload file (STOR)
• StorFrom(path string, r io.Reader, offset uint64) error: Upload from offset
• Append(path string, r io.Reader) error: Append to file (APPE)
• Rename(from, to string) error: Rename file (RNFR/RNTO)
• Delete(path string) error: Delete file (DELE)
• RemoveDirRecur(path string) error: Recursively delete directory
• MakeDir(path string) error: Create directory (MKD)
• RemoveDir(path string) error: Remove directory (RMD)
• Walk(root string) (*ftp.Walker, error): Walk directory tree

Example

cli, err := ftpclient.New(cfg)
if err != nil {
    // handle error
}
defer cli.Close()

files, err := cli.List("/")
if err != nil {
    // handle error
}
for _, entry := range files {
    // process entry
}

---

Error Handling

All errors are wrapped with custom codes (see errors.go):

• ErrorParamsEmpty
• ErrorValidatorError
• ErrorEndpointParser
• ErrorNotInitialized
• ErrorFTPConnection
• ErrorFTPConnectionCheck
• ErrorFTPLogin
• ErrorFTPCommand

Use err.Error() for user-friendly messages and check error codes for diagnostics.

---

Notes

• The client is thread-safe and manages connection state automatically.
• TLS and context can be customized via registration methods.
• All FTP commands are wrapped and errors are contextualized.
• Designed for Go 1.18+.