LuaSocket: FTP support

FTP

FTP (File Transfer Protocol) is a protocol used to transfer files between hosts. The ftp namespace offers thorough support to FTP, under a simple interface. The implementation conforms to RFC 959.

High level functions are provided supporting the most common operations. These high level functions are implemented on top of a lower level interface. Using the low-level interface, users can easily create their own functions to access any operation supported by the FTP protocol. For that, check the implementation.

To really benefit from this module, a good understanding of LTN012, Filters sources and sinks is necessary.

To obtain the ftp namespace, run:

-- loads the FTP module and any libraries it requires
local ftp = require("socket.ftp")

URLs MUST conform to RFC 1738, that is, an URL is a string in the form:

[ftp://][<user>[:<password>]@]<host>[:<port>][/<path>][type=a|i]

The following constants in the namespace can be set to control the default behavior of the FTP module:

PASSWORD: default anonymous password.
PORT: default port used for the control connection;
TIMEOUT: sets the timeout for all I/O operations;
USER: default anonymous user;

ftp.get(url [, create])
ftp.get{
  host = string,
  sink = LTN12 sink,
  argument or path = string,
  [user = string,]
  [password = string]
  [command = string,]
  [port = number,]
  [type = string,]
  [step = LTN12 pump step,]
  [create = function]
}

The get function has two forms. The simple form has fixed functionality: it downloads the contents of a URL and returns it as a string. The generic form allows a lot more control, as explained below. The create parameter is only used in the string form, and will be used as alternative for socket.tcp if it is provided. In the advanced form create has to be specified in the arguments table.

If the argument of the get function is a table, the function expects at least the fields host, sink, and one of argument or path (argument takes precedence). Host is the server to connect to. Sink is the simple LTN12 sink that will receive the downloaded data. Argument or path give the target path to the resource in the server. The optional arguments are the following:

user, password: User name and password used for authentication. Defaults to "ftp:anonymous@anonymous.org";
command: The FTP command used to obtain data. Defaults to "retr", but see example below;
port: The port to used for the control connection. Defaults to 21;
type: The transfer mode. Can take values "i" or "a". Defaults to whatever is the server default;
step: LTN12 pump step function used to pass data from the server to the sink. Defaults to the LTN12 pump.step function;
create: An optional function to be used instead of socket.tcp when the communications socket is created.

If successful, the simple version returns the URL contents as a string, and the generic function returns 1. In case of error, both functions return nil and an error message describing the error.

-- load the ftp support
local ftp = require("socket.ftp")

-- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
-- and get file "lua.tar.gz" from directory "pub/lua" as binary.
f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")

-- load needed modules
local ftp = require("socket.ftp")
local ltn12 = require("ltn12")
local url = require("socket.url")

-- a function that returns a directory listing
function nlst(u)
    local t = {}
    local p = url.parse(u)
    p.command = "nlst"
    p.sink = ltn12.sink.table(t)
    local r, e = ftp.get(p)
    return r and table.concat(t), e
end

ftp.put(url, content [, create])
ftp.put{
  host = string,
  source = LTN12 sink,
  argument or path = string,
  [user = string,]
  [password = string]
  [command = string,]
  [port = number,]
  [type = string,]
  [step = LTN12 pump step,]
  [create = function]
}

The put function has two forms. The simple form has fixed functionality: it uploads a string of content into a URL. The generic form allows a lot more control, as explained below. The create parameter is only used in the string form, and will be used as alternative for socket.tcp if it is provided. In the advanced form create has to be specified in the arguments table.

If the argument of the put function is a table, the function expects at least the fields host, source, and one of argument or path (argument takes precedence). Host is the server to connect to. Source is the simple LTN12 source that will provide the contents to be uploaded. Argument or path give the target path to the resource in the server. The optional arguments are the following:

user, password: User name and password used for authentication. Defaults to "ftp:anonymous@anonymous.org";
command: The FTP command used to send data. Defaults to "stor", but see example below;
port: The port to used for the control connection. Defaults to 21;
type: The transfer mode. Can take values "i" or "a". Defaults to whatever is the server default;
step: LTN12 pump step function used to pass data from the server to the sink. Defaults to the LTN12 pump.step function;
create: An optional function to be used instead of socket.tcp when the communications socket is created.

Both functions return 1 if successful, or nil and an error message describing the reason for failure.

-- load the ftp support
local ftp = require("socket.ftp")

-- Log as user "fulano" on server "ftp.example.com",
-- using password "silva", and store a file "README" with contents 
-- "wrong password, of course"
f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README", 
    "wrong password, of course")

-- load the ftp support
local ftp = require("socket.ftp")
local ltn12 = require("ltn12")

-- Log as user "fulano" on server "ftp.example.com",
-- using password "silva", and append to the remote file "LOG", sending the
-- contents of the local file "LOCAL-LOG"
f, e = ftp.put{
  host = "ftp.example.com", 
  user = "fulano",
  password = "silva",
  command = "appe",
  argument = "LOG",
  source = ltn12.source.file(io.open("LOCAL-LOG", "r"))
}