gftp/actor

OTP actor wrapper for gftp that serializes all FTP operations.

Wrapping an FtpClient in an actor prevents protocol state corruption by ensuring that control commands are rejected while a data channel is open.

Usage

import gftp
import gftp/actor as ftp_actor

let assert Ok(client) = gftp.connect("ftp.example.com", 21)
let assert Ok(started) = ftp_actor.start(client)
let handle = started.data

let assert Ok(_) = ftp_actor.login(handle, "user", "password")
let assert Ok(cwd) = ftp_actor.pwd(handle)
let assert Ok(_) = ftp_actor.quit(handle)

Message-based streaming

The actor enforces chunk protection: once a data channel is opened via open_retr, open_stor, etc., all control commands return Error(DataTransferInProgress) until close_data_channel is called.

let assert Ok(data_stream) = ftp_actor.open_retr(handle, "file.txt")
// ... receive data via stream.receive_next_packet_as_message ...
let assert Ok(_) = ftp_actor.close_data_channel(handle, data_stream)

Types

Handle

opaque </>

Handle to an FTP actor. Use the public functions in this module to interact with it.

The handle wraps the actor subject and a configurable call timeout (default 30 seconds). Use with_call_timeout to adjust the timeout for all subsequent calls.

pub opaque type Handle

Message

opaque </>

Internal message type for the FTP actor. Users interact via the public functions, not by sending messages directly.

pub opaque type Message

Values

abor

</>

pub fn abor(handle: Handle) -> Result(Nil, result.FtpError)

Abort an active file transfer.

appe

</>

pub fn appe(
  handle: Handle,
  path: String,
  writer: fn(stream.DataStream) -> Result(Nil, result.FtpError),
) -> Result(Nil, result.FtpError)

Append to a file using a callback.

cdup

</>

pub fn cdup(handle: Handle) -> Result(Nil, result.FtpError)

Change to parent directory.

clear_command_channel

</>

pub fn clear_command_channel(
  handle: Handle,
) -> Result(Nil, result.FtpError)

Clear the command channel encryption.

close_data_channel

</>

pub fn close_data_channel(
  handle: Handle,
  data_stream: stream.DataStream,
) -> Result(Nil, result.FtpError)

Close a data channel and finalize the transfer.

custom_command

</>

pub fn custom_command(
  handle: Handle,
  command_str: String,
  expected_statuses: List(status.Status),
) -> Result(response.Response, result.FtpError)

Execute a custom FTP command.

custom_data_command

</>

pub fn custom_data_command(
  handle: Handle,
  command_str: String,
  expected_statuses: List(status.Status),
  on_data_stream: fn(stream.DataStream, response.Response) -> Result(
    Nil,
    result.FtpError,
  ),
) -> Result(Nil, result.FtpError)

Execute a custom data command with a callback.

cwd

</>

pub fn cwd(
  handle: Handle,
  path: String,
) -> Result(Nil, result.FtpError)

Change working directory.

dele

</>

pub fn dele(
  handle: Handle,
  path: String,
) -> Result(Nil, result.FtpError)

Delete a file.

eprt

</>

pub fn eprt(
  handle: Handle,
  address: String,
  port: Int,
  ip_version: mode.IpVersion,
) -> Result(Nil, result.FtpError)

Execute an EPRT command.

feat

</>

pub fn feat(
  handle: Handle,
) -> Result(
  dict.Dict(String, option.Option(String)),
  result.FtpError,
)

Retrieve server features (FEAT command).

into_secure

</>

pub fn into_secure(
  handle: Handle,
  ssl_options: kafein.WrapOptions,
) -> Result(Nil, result.FtpError)

Switch to explicit secure mode (FTPS).

list

</>

pub fn list(
  handle: Handle,
  pathname: option.Option(String),
) -> Result(List(String), result.FtpError)

List directory contents.

</>

pub fn login(
  handle: Handle,
  username: String,
  password: String,
) -> Result(Nil, result.FtpError)

mdtm

</>

pub fn mdtm(
  handle: Handle,
  pathname: String,
) -> Result(timestamp.Timestamp, result.FtpError)

Get the modification time of a file.

mkd

</>

pub fn mkd(
  handle: Handle,
  path: String,
) -> Result(Nil, result.FtpError)

Create a directory.

mlsd

</>

pub fn mlsd(
  handle: Handle,
  pathname: option.Option(String),
) -> Result(List(String), result.FtpError)

Machine-readable directory listing.

mlst

</>

pub fn mlst(
  handle: Handle,
  pathname: option.Option(String),
) -> Result(String, result.FtpError)

Execute an MLST command.

nlst

</>

pub fn nlst(
  handle: Handle,
  pathname: option.Option(String),
) -> Result(List(String), result.FtpError)

List file names only.

noop

</>

pub fn noop(handle: Handle) -> Result(Nil, result.FtpError)

Send a NOOP command.