Skip to main content

​
Overview

The ConnectionOptions interface defines optional configuration parameters for FTP client connections. All fields are optional and have sensible defaults.

​
Type Definition

export interface ConnectionOptions {
  user?: string;
  pass?: string;
  port?: number;
  activePort?: number;
  activeIp?: string;
  activeIpv6?: boolean;
  secure?: boolean;
}

​
Fields

​
user
string
default:"anonymous"
The username for FTP authentication.When not specified, the client uses “anonymous” as the default username, which is standard for public FTP servers.Example:
const client = new FTPClient('ftp.example.com', {
  user: 'myusername'
});
​
pass
string
default:"anonymous"
The password for FTP authentication.When not specified, the client uses “anonymous” as the default password. For anonymous FTP access, this is typically an email address or simply “anonymous”.Example:
const client = new FTPClient('ftp.example.com', {
  user: 'myusername',
  pass: 'mypassword'
});
​
port
number
default:21
The port number to connect to on the FTP server.The standard FTP control connection port is 21. You may need to specify a different port if your FTP server uses a non-standard configuration.Example:
const client = new FTPClient('ftp.example.com', {
  port: 2121  // Custom FTP port
});
​
activePort
number
default:20
The port number to use for active mode data connections.In active FTP mode, the server initiates data connections back to the client. The standard port for this is 20. Most modern FTP clients use passive mode instead, where the client initiates all connections.Example:
const client = new FTPClient('ftp.example.com', {
  activePort: 2020
});
​
activeIp
string
default:"127.0.0.1"
The IP address to use for active mode data connections.This specifies the IP address where the server should connect back to for active mode transfers. In most Cloudflare Workers scenarios, passive mode is preferred.Example:
const client = new FTPClient('ftp.example.com', {
  activeIp: '192.168.1.100'
});
​
activeIpv6
boolean
default:false
Whether to use IPv6 for active mode data connections.When set to true, the client will use IPv6 addressing for active mode connections. This requires both the client and server to support IPv6.Example:
const client = new FTPClient('ftp.example.com', {
  activeIpv6: true
});
​
secure
boolean
default:false
Whether to use secure FTP connections via STARTTLS.When set to true, the client will:
  1. Check if the server advertises AUTH TLS support via the FEAT command
  2. Initiate a STARTTLS handshake to encrypt the control connection
  3. Enable TLS for data channel transfers using PROT P
This provides encryption for both control commands and file transfers.
If the server doesn’t advertise STARTTLS support but this option is enabled, the client will attempt the TLS handshake anyway and log a warning.
Example:
const client = new FTPClient('ftp.example.com', {
  user: 'myusername',
  pass: 'mypassword',
  secure: true  // Enable encrypted connection
});
await client.connect();

​
Usage Examples

​
Anonymous Connection

import { FTPClient } from 'workerd-ftp';

// Uses default anonymous credentials
const client = new FTPClient('ftp.example.com');
await client.connect();

​
Authenticated Connection

import { FTPClient } from 'workerd-ftp';

const client = new FTPClient('ftp.example.com', {
  user: 'myusername',
  pass: 'mypassword',
  port: 21
});
await client.connect();

​
Secure Connection with TLS

import { FTPClient } from 'workerd-ftp';

const client = new FTPClient('ftp.example.com', {
  user: 'myusername',
  pass: 'mypassword',
  secure: true  // Enables STARTTLS encryption
});
await client.connect();

​
Custom Port Configuration

import { FTPClient } from 'workerd-ftp';

const client = new FTPClient('ftp.example.com', {
  user: 'myusername',
  pass: 'mypassword',
  port: 2121,        // Custom control port
  activePort: 2020   // Custom data port for active mode
});
await client.connect();

​
Default Configuration

When you create an FTPClient without providing options, or when you omit specific fields, the following defaults are used: 
{
  user: 'anonymous',
  pass: 'anonymous',
  port: 21,
  activePort: 20,
  activeIp: '127.0.0.1',
  activeIpv6: false,
  secure: false
}

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us