FTP/SFTP

The FTP module allows you perform various operations against an FTP or SFTP server.

📁 A comprehensive FTP client module for BoxLang that brings seamless file transfer capabilities to your applications!

This module provides powerful FTP and SFTP client functionality to the BoxLang language, making it easy to connect to FTP/SFTP servers, transfer files, and manage remote directories with minimal code.

✨ Features

• 🌐 FTP/FTPS/SFTP Support: Connect to standard FTP, secure FTP, and SFTP servers
• 📁 Complete File Operations: Upload, download, rename, and delete files on both FTP and SFTP
• 📂 Directory Management: Create, remove, rename, list, and navigate directories on both FTP and SFTP
• 🔐 Secure Connections: Support for passive/active modes (FTP) and SSH key authentication (SFTP)
• 🔑 SSH Key Support: SFTP with public/private key authentication and optional passphrases
• 🎯 Connection Pooling: Named connections tracked globally via FTPService
• 🔄 Proxy Support: Connect through proxy servers with custom ports (FTP only)
• 📊 Flexible Results: Query or array return types for directory listings
• ⚡ Event-Driven: Interception points for logging, monitoring, and custom logic
• 🛠️ Production Ready: Built by Ortus Solutions with enterprise-grade quality
• 🔧 Zero Configuration: Sensible defaults get you started quickly

📦 Installation

Requirements

• BoxLang: 1+
• Java: JDK 21+

Install via CommandBox CLI

If you are using CommandBox for your web applications, you can install it via CommandBox:

box install bx-ftp

Install via BoxLang Binary

If you want to install it globally for the BoxLang OS binary, use the install-bx-module command:

install-bx-module bx-ftp

The module will automatically register and be available as bx:ftp or <bx:ftp> in your BoxLang script and template applications.

From Source

# Clone the repository
git clone https://github.com/ortus-boxlang/bx-ftp.git
cd bx-ftp

# Build the module
./gradlew build

# The built module will be in build/distributions/

🚀 Quick Start

Here's how to connect to an FTP server and upload a file in just a few lines:

// Connect to FTP server
bx:ftp
    action="open"
    connection="myFTP"
    server="ftp.example.com"
    username="myuser"
    password="mypass";

// Upload a file
bx:ftp
    action="putfile"
    connection="myFTP"
    localFile="/path/to/local/file.txt"
    remoteFile="/remote/file.txt";

// Close connection
bx:ftp action="close" connection="myFTP";

That's it! 🎉 You now have a fully functional FTP client.

SFTP Quick Start

Here's how to connect to an SFTP server with password authentication:

// Connect to SFTP server with password
bx:ftp
    action="open"
    connection="mySFTP"
    server="sftp.example.com"
    username="myuser"
    password="mypass"
    secure="true";  // This makes it SFTP!

// Upload a file via SFTP
bx:ftp
    action="putfile"
    connection="mySFTP"
    localFile="/path/to/local/file.txt"
    remoteFile="/remote/file.txt";

// Close connection
bx:ftp action="close" connection="mySFTP";

Or with SSH key authentication:

// Connect to SFTP server with SSH key
bx:ftp
    action="open"
    connection="mySFTP"
    server="sftp.example.com"
    username="myuser"
    key="/path/to/private/key"
    passphrase="optional_passphrase"
    secure="true";

// Now you can use the connection for file operations

💡 Usage Examples

Basic Examples

📁 Connect and List Files

// Open connection
bx:ftp
    action="open"
    connection="myConn"
    server="ftp.example.com"
    username="user"
    password="pass";

// List directory contents
bx:ftp
    action="listdir"
    connection="myConn"
    directory="/"
    name="files";

// Display results
writeDump(files);

// Close connection
bx:ftp action="close" connection="myConn";

📤 Upload a File

bx:ftp action="open" connection="uploader" server="ftp.example.com" username="user" password="pass";

bx:ftp
    action="putfile"
    connection="uploader"
    localFile="/Users/documents/report.pdf"
    remoteFile="/uploads/monthly-report.pdf"
    result="uploadResult";

if (uploadResult.succeeded) {
    writeOutput("File uploaded successfully!");
} else {
    writeOutput("Upload failed: #uploadResult.statusText#");
}

bx:ftp action="close" connection="uploader";

📥 Download a File

bx:ftp action="open" connection="downloader" server="ftp.example.com" username="user" password="pass";

bx:ftp
    action="getfile"
    connection="downloader"
    remoteFile="/reports/sales-2025.csv"
    localFile="/Users/downloads/sales-2025.csv"
    failIfExists="false"
    result="downloadResult";

writeOutput("Download complete: #downloadResult.succeeded#");

bx:ftp action="close" connection="downloader";

Advanced Examples

Advanced Examples

🔐 Secure Connection with Passive Mode

try {
    // Open secure connection
    bx:ftp
        action="open"
        connection="secureFTP"
        server="secure.ftp.example.com"
        port="990"
        username="admin"
        password="secretpass"
        secure="true"
        passive="true"
        timeout="60"
        result="ftpResult";

    if (ftpResult.succeeded) {
        writeOutput("Connected to secure FTP server");

        // Perform operations...

    } else {
        throw("Connection failed: #ftpResult.statusText#");
    }
} catch (any e) {
    writeOutput("FTP Error: #e.message#");
} finally {
    bx:ftp action="close" connection="secureFTP";
}

🌐 Connect Through Proxy Server

// Connect via proxy with custom port
bx:ftp
    action="open"
    connection="proxyConn"
    server="ftp.example.com"
    username="user"
    password="pass"
    proxyServer="proxy.company.com:8080";

// Connect via proxy with default port (1080)
bx:ftp
    action="open"
    connection="proxyConn"
    server="ftp.example.com"
    username="user"
    password="pass"
    proxyServer="proxy.company.com";

📂 Directory Management

bx:ftp action="open" connection="dirManager" server="ftp.example.com" username="user" password="pass";

// Create a new directory
bx:ftp
    action="createdir"
    connection="dirManager"
    new="/uploads/2025"
    result="createResult";

// Check if directory exists
bx:ftp
    action="existsdir"
    connection="dirManager"
    directory="/uploads/2025"
    result="existsResult";

writeOutput("Directory exists: #existsResult.returnValue#");

// Change to directory
bx:ftp
    action="changedir"
    connection="dirManager"
    directory="/uploads/2025";

// Get current directory
bx:ftp
    action="getcurrentdir"
    connection="dirManager"
    result="cwdResult";

writeOutput("Current directory: #cwdResult.returnValue#");

bx:ftp action="close" connection="dirManager";

📊 List Directory as Array

bx:ftp action="open" connection="lister" server="ftp.example.com" username="user" password="pass";

// Get directory listing as array of structs
bx:ftp
    action="listdir"
    connection="lister"
    directory="/uploads"
    name="fileList"
    returnType="array";

// Process each file
for (file in fileList) {
    writeOutput("File: #file.name# - Size: #file.size# bytes - Type: #file.type#<br>");

    if (file.isDirectory) {
        writeOutput("  → This is a directory<br>");
    } else {
        writeOutput("  → Last modified: #file.lastModified#<br>");
    }
}

bx:ftp action="close" connection="lister";

🔄 Bulk File Transfer

bx:ftp action="open" connection="bulk" server="ftp.example.com" username="user" password="pass";

files = ["report1.pdf", "report2.pdf", "report3.pdf"];
successCount = 0;
failCount = 0;

for (fileName in files) {
    bx:ftp
        action="putfile"
        connection="bulk"
        localFile="/local/reports/#fileName#"
        remoteFile="/remote/reports/#fileName#"
        result="uploadResult";

    if (uploadResult.succeeded) {
        successCount++;
        writeOutput("✓ Uploaded: #fileName#<br>");
    } else {
        failCount++;
        writeOutput("✗ Failed: #fileName# - #uploadResult.statusText#<br>");
    }
}

writeOutput("<br>Summary: #successCount# successful, #failCount# failed");

bx:ftp action="close" connection="bulk";

🏷️ Rename Files and Directories

bx:ftp action="open" connection="renamer" server="ftp.example.com" username="user" password="pass";

// Rename a file
bx:ftp
    action="renamefile"
    connection="renamer"
    existing="/uploads/temp.txt"
    new="/uploads/final-report.txt"
    result="renameResult";

if (renameResult.returnValue) {
    writeOutput("File renamed successfully");
}

// Rename a directory
bx:ftp
    action="renamedir"
    connection="renamer"
    existing="/old-folder"
    new="/new-folder"
    result="dirRenameResult";

bx:ftp action="close" connection="renamer";

</details>

### SFTP Examples

<details>
<summary>SFTP Examples</summary>

#### 🔐 SFTP with Password Authentication

```java
// Connect to SFTP server
bx:ftp
    action="open"
    connection="sftpConn"
    server="sftp.example.com"
    port="22"  // Default SFTP port
    username="sftpuser"
    password="securepass"
    secure="true";

// Upload a file via SFTP
bx:ftp
    action="putfile"
    connection="sftpConn"
    localFile="/local/path/document.pdf"
    remoteFile="/remote/path/document.pdf";

// List directory
bx:ftp
    action="listdir"
    connection="sftpConn"
    directory="/uploads"
    name="sftpFiles";

// Close SFTP connection
bx:ftp action="close" connection="sftpConn";

🔑 SFTP with SSH Key Authentication

// Connect using SSH private key
bx:ftp
    action="open"
    connection="sftpKey"
    server="sftp.example.com"
    username="deployuser"
    key="/path/to/private/id_rsa"
    secure="true";

// Or with a passphrase-protected key
bx:ftp
    action="open"
    connection="sftpSecure"
    server="sftp.example.com"
    username="deployuser"
    key="/path/to/private/id_rsa"
    passphrase="my-key-passphrase"
    secure="true";

// Use the connection normally
bx:ftp
    action="putfile"
    connection="sftpKey"
    localFile="/build/app.zip"
    remoteFile="/deployments/app.zip";

bx:ftp action="close" connection="sftpKey";

🌐 SFTP with Fingerprint Verification

// Connect with host key fingerprint verification
bx:ftp
    action="open"
    connection="sftpVerified"
    server="sftp.example.com"
    username="verifieduser"
    password="securepass"
    fingerprint="SHA256:abc123def456..."
    secure="true";

// Proceed with secure verified connection
bx:ftp
    action="listdir"
    connection="sftpVerified"
    directory="/"
    name="files";

bx:ftp action="close" connection="sftpVerified";

📁 SFTP Directory Operations

// Open SFTP connection
bx:ftp
    action="open"
    connection="sftpMgr"
    server="sftp.example.com"
    username="admin"
    password="adminpass"
    secure="true";

// Create directory
bx:ftp
    action="createdir"
    connection="sftpMgr"
    new="/backups/2024";

// Check if directory exists
bx:ftp
    action="existsdir"
    connection="sftpMgr"
    directory="/backups/2024"
    result="dirExists";

if (dirExists.returnValue) {
    writeOutput("Backup directory ready!");
}

// Remove empty directory
bx:ftp
    action="removedir"
    connection="sftpMgr"
    directory="/temp/old-data";

bx:ftp action="close" connection="sftpMgr";

🏷️ SFTP File Rename Operations

// Open SFTP connection
bx:ftp
    action="open"
    connection="sftpRename"
    server="sftp.example.com"
    username="admin"
    password="adminpass"
    secure="true";

// Rename a file
bx:ftp
    action="renamefile"
    connection="sftpRename"
    existing="/uploads/draft-report.pdf"
    new="/uploads/final-report-2026.pdf"
    result="renameResult";

if (renameResult.returnValue) {
    writeOutput("File renamed successfully via SFTP");
}

// Rename a directory
bx:ftp
    action="renamedir"
    connection="sftpRename"
    existing="/projects/old-project-name"
    new="/projects/new-project-name"
    result="dirRenameResult";

if (dirRenameResult.returnValue) {
    writeOutput("Directory renamed successfully via SFTP");
}

bx:ftp action="close" connection="sftpRename";

🗑️ SFTP File Removal Operations

// Open SFTP connection
bx:ftp
    action="open"
    connection="sftpRemove"
    server="sftp.example.com"
    username="admin"
    password="adminpass"
    secure="true";

// Remove a file
bx:ftp
    action="removefile"
    connection="sftpRemove"
    remoteFile="/temp/cache-file.tmp"
    result="removeResult";

if (removeResult.returnValue) {
    writeOutput("File removed successfully via SFTP");
} else {
    writeOutput("Failed to remove file: #removeResult.errorText#");
}

// Alternative: use 'remove' action (alias)
bx:ftp
    action="remove"
    connection="sftpRemove"
    remoteFile="/logs/old-log.txt"
    result="removeResult2";

bx:ftp action="close" connection="sftpRemove";

</details>

## 📚 Available Actions

<details>
<summary>Available Actions</summary>

All actions can use a `result` attribute to store the result of the action in a variable. If not provided, the result will be stored in a variable called `bxftp` (or `cftp` if you are in CFML compat mode).

### 🔌 Connection Actions

#### `open` - Connect to FTP/SFTP Server

Opens a connection to an FTP or SFTP server and tracks it in the FTPService.

**Attributes:**

| Attribute | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `connection` | string | ✅ Yes | - | Name of the connection to track |
| `server` | string | ✅ Yes | - | Server IP or hostname |
| `port` | numeric | No | 21 (FTP)<br>22 (SFTP) | Server port number |
| `username` | string | ✅ Yes | - | Authentication username |
| `password` | string | Conditional | - | Authentication password (required if `key` not provided) |
| `timeout` | numeric | No | 30 | Connection timeout in seconds |
| `secure` | boolean | No | false | Use SFTP when true, FTP when false |
| `passive` | boolean | No | true | Use passive mode (FTP only) |
| `proxyServer` | string | No | - | Proxy server hostname:port (FTP only) |
| `key` | string | No | - | Path to SSH private key file (SFTP only) |
| `passphrase` | string | No | - | Passphrase for encrypted SSH key (SFTP only) |
| `fingerprint` | string | No | - | Server's host key fingerprint for verification (SFTP only) |

**Examples:**

```java
// Basic FTP connection
bx:ftp
    action="open"
    connection="myConn"
    server="ftp.example.com"
    username="user"
    password="pass";

// SFTP connection with password
bx:ftp
    action="open"
    connection="sftpConn"
    server="sftp.example.com"
    username="user"
    password="pass"
    secure="true";

// SFTP connection with SSH key
bx:ftp
    action="open"
    connection="sftpKey"
    server="sftp.example.com"
    username="deployuser"
    key="/path/to/id_rsa"
    secure="true";

// Connection via proxy (FTP only)
bx:ftp
    action="open"
    connection="proxyConn"
    server="ftp.example.com"
    username="user"
    password="pass"
    proxyServer="proxy.company.com:8080";

close - Close FTP/SFTP Connection

Closes an open FTP or SFTP connection and removes it from the FTPService.

Attributes:

Attribute	Type	Required	Description
connection	string	✅ Yes	Name of the connection to close

Example:

bx:ftp action="close" connection="myConn";

📂 Directory Actions

changedir - Change Working Directory

Changes the current working directory on the FTP server.

Attributes:

Attribute	Type	Required	Description
connection	string	✅ Yes	Connection name
directory	string	✅ Yes	Directory path to change to

Example:

bx:ftp action="changedir" connection="myConn" directory="/uploads/2025";

createdir - Create Directory

Creates a new directory on the FTP server.

Attributes:

Attribute	Type	Required	Description
connection	string	✅ Yes	Connection name
new	string	✅ Yes	Path of directory to create

Example:

bx:ftp action="createdir" connection="myConn" new="/uploads/reports" result="createResult";

if (createResult.returnValue) {
    writeOutput("Directory created successfully");
}

existsdir - Check Directory Existence

Checks if a directory exists on the FTP server.

Attributes:

Attribute	Type	Required	Description
connection	string	✅ Yes	Connection name
directory	string	✅ Yes	Directory path to check

Example:

bx:ftp action="existsdir" connection="myConn" directory="/uploads" result="existsResult";

if (existsResult.returnValue) {
    writeOutput("Directory exists");
} else {
    writeOutput("Directory not found");
}

getcurrentdir - Get Working Directory

Retrieves the current working directory path.

Attributes:

Attribute	Type	Required	Description
connection	string	✅ Yes	Connection name

Example:

bx:ftp action="getcurrentdir" connection="myConn" result="cwdResult";
writeOutput("Current directory: #cwdResult.returnValue#");

listdir - List Directory Contents

Lists files and directories in the specified directory.

Attributes:

Attribute	Type	Required	Default	Description
connection	string	✅ Yes	-	Connection name
directory	string	✅ Yes	-	Directory to list
name	string	✅ Yes	-	Variable name to store results
returnType	string	No	"query"	Return format: "query" or "array"

Query Columns:

• name - File/directory name
• isDirectory - Boolean indicating if item is a directory
• lastModified - Last modification timestamp
• size - File size in bytes (aliased as length for CFML compatibility)
• mode - File permissions mode
• path - File path without drive designation
• url - Complete URL for the item
• type - Type: "file", "directory", "symbolic link", or "unknown"
• raw - Raw FTP listing representation
• attributes - File attributes
• isReadable - Boolean for read permission
• isWritable - Boolean for write permission
• isExecutable - Boolean for execute permission

Examples:

// List as query (default)
bx:ftp action="listdir" connection="myConn" directory="/" name="files";

// List as array of structs
bx:ftp action="listdir" connection="myConn" directory="/" name="files" returnType="array";

// Process results
for (file in files) {
    writeOutput("#file.name# - #file.size# bytes<br>");
}

removedir - Remove Directory

Removes a directory from the FTP server.

Attributes:

Attribute	Type	Required	Description
connection	string	✅ Yes	Connection name
directory	string	✅ Yes	Directory path to remove

Example:

bx:ftp action="removedir" connection="myConn" directory="/temp/old-data" result="removeResult";

if (removeResult.returnValue) {
    writeOutput("Directory removed successfully");
}

renamedir - Rename Directory

Renames a directory on the FTP server.

Attributes:

Attribute	Type	Required	Description
connection	string	✅ Yes	Connection name
existing	string	✅ Yes	Current directory path
new	string	✅ Yes	New directory path

Example:

bx:ftp
    action="renamedir"
    connection="myConn"
    existing="/old-name"
    new="/new-name"
    result="renameResult";

📄 File Actions

existsfile - Check File Existence

Checks if a file exists on the FTP server.

Attributes:

Attribute	Type	Required	Description
connection	string	✅ Yes	Connection name
remoteFile	string	✅ Yes	Remote file path to check

Example:

bx:ftp action="existsfile" connection="myConn" remoteFile="/data/report.pdf" result="existsResult";

if (existsResult.returnValue) {
    writeOutput("File exists");
}

getfile - Download File

Downloads a file from the FTP server to the local filesystem.

Attributes:

Attribute	Type	Required	Default	Description
connection	string	✅ Yes	-	Connection name
remoteFile	string	✅ Yes	-	Remote file path to download
localFile	string	✅ Yes	-	Local file path to save to
failIfExists	boolean	No	true	Fail if local file already exists

Example:

// Download with overwrite protection
bx:ftp
    action="getfile"
    connection="myConn"
    remoteFile="/reports/sales.csv"
    localFile="/Users/downloads/sales.csv";

// Download and overwrite if exists
bx:ftp
    action="getfile"
    connection="myConn"
    remoteFile="/reports/sales.csv"
    localFile="/Users/downloads/sales.csv"
    failIfExists="false"
    result="downloadResult";

if (downloadResult.succeeded) {
    writeOutput("Download complete");
}

putfile - Upload File

Uploads a file from the local filesystem to the FTP server.

Attributes:

Attribute	Type	Required	Description
connection	string	✅ Yes	Connection name
localFile	string	✅ Yes	Local file path to upload
remoteFile	string	✅ Yes	Remote file path destination

Example:

bx:ftp
    action="putfile"
    connection="myConn"
    localFile="/Users/documents/report.pdf"
    remoteFile="/uploads/report.pdf"
    result="uploadResult";

if (uploadResult.succeeded) {
    writeOutput("Upload successful: #uploadResult.statusText#");
}

removefile (or remove) - Delete File

Deletes a file from the FTP server.

Attributes:

Attribute	Type	Required	Description
connection	string	✅ Yes	Connection name
remoteFile	string	✅ Yes	Remote file path to delete

Example:

bx:ftp action="removefile" connection="myConn" remoteFile="/temp/old-file.txt" result="removeResult";

if (removeResult.returnValue) {
    writeOutput("File deleted successfully");
}

renamefile - Rename File

Renames a file on the FTP server.

Attributes:

Attribute	Type	Required	Description
connection	string	✅ Yes	Connection name
existing	string	✅ Yes	Current file path
new	string	✅ Yes	New file path

Example:

bx:ftp
    action="renamefile"
    connection="myConn"
    existing="/uploads/temp.txt"
    new="/uploads/final-report.txt"
    result="renameResult";

if (renameResult.returnValue) {
    writeOutput("File renamed successfully");
}

📊 Result Object

All FTP actions return a result object with the following structure:

{
    statusCode : 200,              // Numeric FTP status code
    statusText : "Success",        // Human-readable status message
    errorCode : 0,                 // Error code (if any)
    errorText : "",                // Error message (if any)
    returnValue : true,            // Action-specific return value
    succeeded : true               // Boolean indicating success/failure
}

Common Status Codes

Code	Meaning	Description
200	Success	Command successful
221	Goodbye	Service closing control connection
226	Transfer complete	Closing data connection, file transfer successful
230	Login successful	User logged in
250	Success	Requested file action okay, completed
550	Failed	File unavailable or permission denied
552	Exceeded	Storage allocation exceeded
553	Not allowed	File name not allowed

Using Result Variables

// Store result in custom variable
bx:ftp action="putfile" connection="myConn" localFile="test.txt" remoteFile="/test.txt" result="uploadResult";

if (uploadResult.succeeded) {
    writeOutput("Success! Status: #uploadResult.statusCode#");
} else {
    writeOutput("Failed: #uploadResult.errorText#");
}

// Default result variable (bxftp)
bx:ftp action="putfile" connection="myConn" localFile="test.txt" remoteFile="/test.txt";

if (bxftp.succeeded) {
    writeOutput("Upload successful");
}

🎯 Interception Points

Interception Points

The FTP module announces several interception points that allow you to hook into the FTP operation lifecycle for logging, monitoring, metrics, or custom logic.

beforeFTPCall

Announced before any FTP action is executed.

Interceptor Data:

{
    connection : FTPConnection,    // The FTP connection object
    action : "putfile",           // The action being performed
    result : FTPResult,           // The result object (empty at this point)
    attributes : {                // All attributes passed to the component
        connection : "myConn",
        localFile : "/path/to/file.txt",
        remoteFile : "/remote/file.txt"
        // ... other attributes
    }
}

Use Cases:

• Pre-flight validation
• Logging all FTP operations
• Performance monitoring (start timer)
• Security auditing

Example:

class {
    function beforeFTPCall( event, interceptData ) {
        var logger = getLogger();
        logger.info(
            "FTP Action Starting: #interceptData.action# on connection #interceptData.attributes.connection#"
        );

        // Store start time for performance tracking
        interceptData.startTime = now();
    }
}

afterFTPCall

Announced after an FTP action completes successfully.

Interceptor Data:

{
    connection : FTPConnection,    // The FTP connection object
    action : "putfile",           // The action that was performed
    result : FTPResult,           // The populated result object
    attributes : {                // All attributes passed to the component
        connection : "myConn",
        localFile : "/path/to/file.txt",
        remoteFile : "/remote/file.txt"
    }
}

Use Cases:

• Success logging
• Performance metrics (calculate duration)
• Notifications or alerts
• Analytics and reporting

Example:

class {
    function afterFTPCall( event, interceptData ) {
        var logger = getLogger();
        var result = interceptData.result;

        logger.info(
            "FTP Action Completed: #interceptData.action# - Status: #result.statusCode# - Success: #result.succeeded#"
        );

        // Track successful transfers
        if ( result.succeeded && interceptData.action == "putfile" ) {
            metrics.recordUpload( interceptData.attributes.remoteFile );
        }
    }
}

onFTPConnectionOpen

Announced when a new FTP connection is opened.

Interceptor Data:

{
    connection : FTPConnection,    // The newly opened connection
    attributes : {                // Connection attributes
        server : "ftp.example.com",
        username : "user",
        port : 21,
        passive : true
        // ... other connection attributes
    }
}

Use Cases:

• Connection logging
• Connection pooling metrics
• Security monitoring
• Access auditing

Example:

class {
    function onFTPConnectionOpen( event, interceptData ) {
        var logger = getLogger();
        var attrs = interceptData.attributes;

        logger.info(
            "FTP Connection Opened: #attrs.server#:#attrs.port# as #attrs.username# (Passive: #attrs.passive#)"
        );

        // Track active connections
        connectionMonitor.recordConnection(
            server = attrs.server,
            user = attrs.username,
            timestamp = now()
        );
    }
}

onFTPConnectionClose

Announced when an FTP connection is closed.

Interceptor Data:

{
    connection : FTPConnection    // The connection being closed
}

Use Cases:

• Connection cleanup logging
• Session duration tracking
• Connection pool management
• Resource monitoring

Example:

component {
    function onFTPConnectionClose( event, interceptData ) {
        var logger = getLogger();
        var conn = interceptData.connection;

        logger.info(
            "FTP Connection Closed: #conn.getName()# - Status: #conn.getStatus()#"
        );

        // Track connection closures
        connectionMonitor.recordClosure(
            connection = conn.getName(),
            timestamp = now()
        );
    }
}

onFTPError

Announced when an FTP operation encounters an error.

Interceptor Data:

{
    connection : FTPConnection,    // The FTP connection object
    action : "putfile",           // The action that failed
    error : IOException,          // The exception object
    attributes : {                // All attributes passed to the component
        connection : "myConn",
        localFile : "/path/to/file.txt",
        remoteFile : "/remote/file.txt"
    }
}

Use Cases:

• Error logging and alerting
• Retry logic
• Fallback mechanisms
• Error analytics

Example:

component {
    function onFTPError( event, interceptData ) {
        var logger = getLogger();
        var error = interceptData.error;

        logger.error(
            "FTP Action Failed: #interceptData.action# - Error: #error.getMessage()#",
            error
        );

        // Send alert for critical errors
        if ( interceptData.action == "putfile" ) {
            alertService.send(
                message = "FTP upload failed: #error.getMessage()#",
                severity = "high",
                details = interceptData
            );
        }
    }
}

🔗 Connection Management

Connection Management

The FTP module uses the FTPService to manage named connections globally across your application.

Connection Lifecycle

1. Open: Connection is created and tracked by name
2. Use: Multiple actions can use the same connection
3. Close: Connection is removed from tracking

Reusing Connections

// Open once
bx:ftp action="open" connection="myConn" server="ftp.example.com" username="user" password="pass";

// Use multiple times
bx:ftp action="putfile" connection="myConn" localFile="file1.txt" remoteFile="/file1.txt";
bx:ftp action="putfile" connection="myConn" localFile="file2.txt" remoteFile="/file2.txt";
bx:ftp action="listdir" connection="myConn" directory="/" name="files";

// Close when done
bx:ftp action="close" connection="myConn";

Connection Best Practices

• ✅ Always close connections when done to free resources
• ✅ Use descriptive names for connections to avoid conflicts
• ✅ Reuse connections for multiple operations to improve performance
• ✅ Use try/finally to ensure connections are closed even on errors
• ❌ Don't leave connections open indefinitely

Accessing Connection Information

After opening a connection, it's stored in a variable with the connection name:

bx:ftp action="open" connection="info" server="ftp.example.com" username="user" password="pass";

writeDump( info );
// Outputs connection details: server, port, username, status, etc.

❌ Error Handling

Error Handling

Common Connection Issues

Connection Refused Errors:

• Verify FTP server is running and accessible
• Check firewall settings for FTP ports (21 for control, 20 for data)
• For passive mode, ensure passive port range is accessible
• Verify credentials are correct

Passive vs Active Mode:

• Passive Mode (default): Client initiates both control and data connections
• Active Mode: Server initiates data connection back to client
• Use passive mode for connections through firewalls/NAT

Error Handling Patterns

Try/Catch/Finally

try {
    bx:ftp action="open" connection="safeConn" server="ftp.example.com" username="user" password="pass";

    bx:ftp action="putfile" connection="safeConn" localFile="file.txt" remoteFile="/file.txt" result="uploadResult";

    if (!uploadResult.succeeded) {
        throw("Upload failed: #uploadResult.statusText#");
    }

} catch (any e) {
    writeOutput("FTP Error: #e.message#<br>");
    // Log error, send alert, etc.
} finally {
    // Always close connection
    bx:ftp action="close" connection="safeConn";
}

Status Code Checking

bx:ftp action="putfile" connection="conn" localFile="test.txt" remoteFile="/test.txt" result="ftpResult";

switch (ftpResult.statusCode) {
    case 226:
        writeOutput("Transfer successful");
        break;
    case 550:
        writeOutput("File not found or permission denied");
        break;
    case 552:
        writeOutput("Storage allocation exceeded");
        break;
    case 553:
        writeOutput("File name not allowed");
        break;
    default:
        writeOutput("Operation failed: #ftpResult.statusText#");
}

❓ Troubleshooting

Troubleshooting

Connection Refused Errors

Problem: FTP operations fail with "Connection refused" errors.

Solutions:

• ✅ Verify FTP server is running: nc -v hostname port
• ✅ Check firewall allows FTP ports (21, 20, and passive range)
• ✅ Ensure passive mode is configured on server (for passive=true)
• ✅ Verify credentials are correct
• ✅ Test connection with FTP client (FileZilla, etc.)

Passive Mode Failures

Problem: Connection succeeds but file transfers fail.

Solutions:

• ✅ Ensure FTP server has passive mode enabled
• ✅ Check passive port range is open in firewall
• ✅ Verify server announces correct IP for passive connections
• ✅ Try active mode instead: passive="false"

File Upload Failures

Problem: Files fail to upload with permission errors.

Solutions:

• ✅ Verify user has write permissions on remote directory
• ✅ Check disk space on FTP server
• ✅ Ensure remote directory exists
• ✅ Try uploading to a different directory

Connection Timeout

Problem: Connection attempts timeout.

Solutions:

• ✅ Increase timeout: timeout="60"
• ✅ Check network connectivity to FTP server
• ✅ Verify server is not blocking your IP
• ✅ Test if server is behind a firewall or proxy

Proxy Connection Issues

Problem: Cannot connect through proxy server.

Solutions:

• ✅ Verify proxy server address and port: proxyServer="proxy.company.com:8080"
• ✅ Check proxy supports FTP protocol
• ✅ Ensure proxy authentication (if required) is configured
• ✅ Test proxy with other FTP clients

🛠️ Development & Testing

Development & Testing

Local Development Setup

This module includes Docker configuration for local FTP and SFTP server testing:

# Copy Docker environment configuration
cp src/test/resources/.env.docker src/test/resources/.env

# Start FTP and SFTP test servers
docker-compose up -d --build

# Run tests
./gradlew test

# Stop servers
docker-compose down

Test Server Configuration (Docker)

FTP Server:

• Host: localhost
• Control Port: 2221
• Data Port: 2220
• Passive Ports: 10000-10010
• Username: test_user
• Password: testpass

SFTP Server:

• Host: localhost
• Port: 2222
• Username: test_user
• Password: testpass

Building from Source

# Clone repository
git clone https://github.com/ortus-boxlang/bx-ftp.git
cd bx-ftp

# Download BoxLang dependency
./gradlew downloadBoxLang

# Build module
./gradlew build

# Run tests (requires Docker FTP server)
docker-compose up -d
./gradlew test

# Create distribution
./gradlew zipModuleStructure

Module Architecture

• FTPService: Global singleton service managing all FTP connections
• FTP Component: BoxLang component (@BoxComponent) providing FTP operations
• FTPConnection: Represents an active FTP connection with state management
• FTPResult: Encapsulates operation results with status codes and messages
• Dependencies: Apache Commons Net 3.11.1 for FTP protocol implementation

Testing with Docker

The included Docker setup provides a consistent FTP/SFTP testing environment:

# Copy Docker-specific environment configuration
cp src/test/resources/.env.docker src/test/resources/.env

# Start FTP and SFTP servers with specific configuration
docker-compose up -d --build

# View logs
docker-compose logs -f

# Stop and remove containers
docker-compose down

# Force recreate (after config changes)
docker-compose up -d --build --force-recreate

Docker Port Mapping:

• FTP Control: 2221 (mapped from container port 21)
• FTP Data: 2220 (mapped from container port 20)
• SFTP: 2222 (mapped from container port 22)
• FTP Passive: 10000-10010

CI Environment: Tests in GitHub Actions use standard ports (21 for FTP, 22 for SFTP) as servers run directly on the Ubuntu runner. The .env.example file uses these standard ports by default.

Important: The vsftpd.conf file includes critical passive mode configuration:

pasv_enable=YES
pasv_min_port=10000
pasv_max_port=10010
pasv_address=127.0.0.1

🔄 CFML Compatibility

CFML Compatibility

This module will require the bx-cfml-compat module if you want it to work like Adobe ColdFusion/Lucee in your CFML applications.

Differences from CFML

• Result Variable: BoxLang uses bxftp by default, CFML compat mode uses cftp
• Component Name: Use bx:ftp in BoxLang, cftp with compat module
• Features: BoxLang FTP includes modern features like event interception

Migration from CFML

All CFML <cfftp> should work with no changes when using bx-cfml-compat. However, for native BoxLang usage, update tags as follows:

// CFML
<cfftp action="open" connection="myConn" server="ftp.example.com" username="user" password="pass">

// BoxLang (with bx-cfml-compat)
<cftp action="open" connection="myConn" server="ftp.example.com" username="user" password="pass">

// BoxLang (native)
<bx:ftp action="open" connection="myConn" server="ftp.example.com" username="user" password="pass">

🤝 Contributing

We ❤️ contributions! This project is open source and welcomes your help to make it even better.

🐛 Found a Bug?

If you discover a bug, please:

1. Check existing issues at GitHub Issues
2. Create a new issue with:

   • Clear title and description
   • Steps to reproduce
   • Expected vs actual behavior
   • BoxLang version and environment details
   • Sample code that demonstrates the issue

💡 Have an Enhancement Idea?

We'd love to hear your ideas! Please:

1. Open a Feature Request
2. Describe the feature and its use case
3. Explain how it would benefit users

📚 Improve Documentation

Documentation improvements are always welcome:

• Fix typos or unclear explanations
• Add more examples
• Improve code comments
• Create tutorials or guides

💰 Financial Support

You can support BoxLang and all Ortus Solutions open source projects:

• 🌟 Become a Patron
• 💵 One-time PayPal Donation

Patrons get exclusive benefits like:

• Priority support
• Early access to new features
• FORGEBOX Pro account
• CFCasts account

📞 Support Channels

Need help? Don't create an issue—use our support channels:

• 💬 Ortus Community Discourse
• 📱 Box Team Slack
• 🏢 Professional Support

🏆 Contributors

Thank you to all our amazing contributors! ❤️

Made with contributors-img

🔐 Security Vulnerabilities

If you discover a security vulnerability:

1. DO NOT create a public issue
2. Email [e-mail]
3. Report in #security channel on Box Team Slack

All vulnerabilities will be promptly addressed.

📄 License

This project is licensed under the Apache License 2.0.

Copyright 2025 Ortus Solutions, Corp

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

See LICENSE file for full details.

💼 Support & Resources

📖 Documentation

• Module Docs: You're reading them! 📚
• BoxLang Docs: https://boxlang.ortusbooks.com/
• Apache Commons Net: https://commons.apache.org/proper/commons-net/

🌐 Links

• BoxLang Website: https://boxlang.io
• Ortus Solutions: https://www.ortussolutions.com
• GitHub Repository: https://github.com/ortus-boxlang/bx-ftp
• Issue Tracker: https://github.com/ortus-boxlang/bx-ftp/issues
• ForgeBox: https://forgebox.io/view/bx-ftp

🎓 Learning Resources

• BoxLang Training: https://www.ortussolutions.com/services/training
• CFCasts: https://www.cfcasts.com
• Blog: https://www.ortussolutions.com/blog