ftp
A pure MoonBit FTP client library ported from jlaffaye/ftp, supporting passive mode, MLSD/LIST parsing, resume and FTPS.
ftp
network
client
protocol
async
Author
Version
0.1.0
License
Apache-2.0
Repository
Last updated
19 hours ago
Downloads
2
Dependencies
- moonbitlang/async0.21.3
- moonbitlang/x0.5.4
#PaiGack/ftp
纯 MoonBit 实现的 FTP 客户端库，移植自 jlaffaye/ftp。
支持被动模式、MLSD / LIST 四种列表格式解析、断点续传与 FTPS（显式 / 隐式 TLS）。
#环境要求
- MoonBit 工具链（moon）
- C 编译器：gcc + libc6-dev。FTP 需要真实 TCP + TLS，模块声明了 preferred_target = "native"，native 后端的编译与链接依赖 C 工具链。
安装：
curl -fsSL https://cli.moonbitlang.cn/install/unix.sh | bash
export PATH="$HOME/.moon/bin:$PATH"
# native 后端所需的 C 工具链（Debian / Ubuntu）
sudo apt-get install -y gcc libc6-dev#开发
所有 moon 命令都显式带上 --target native：preferred_target 已是 native，
wasm / wasm-gc 后端提供不了真实网络栈。
moon fmt --check # 格式化检查
moon check --target native --deny-warn # 类型检查，0 warning 0 error
moon test --target native # 运行测试（真机用例默认跳过）
moon build --target native # 构建
moon run cmd/ftp # 运行 CLI（打印 usage）
moon info # 更新生成接口（.mbti）#真实 FTP 服务器测试
ftp_server_test.mbt 的端到端用例跑在真实的 vsftpd 上，需要显式设置环境变量才会
执行（不设时用例直接 return，本机 moon test 保持全绿）。服务器由公共脚本
scripts/start-ftp.sh 以 Docker 起，四个「能力画像」各一个容器：
scripts/start-ftp.sh # 起 full / no-mlst / no-time / no-epsv 四个容器
export FTP_TEST_HOST=127.0.0.1 FTP_TEST_PORT=2121 FTP_TEST_USER=test FTP_TEST_PASS=test FTP_TEST_FIXTURE=/fixture FTP_TEST_DIR=/upload FTP_TEST_PORT_NO_MLST=2122 FTP_TEST_PORT_NO_TIME=2123 FTP_TEST_PORT_NO_EPSV=2124
moon test --target native
scripts/stop-ftp.sh # 打日志并清理容器GitHub Actions、CNB 流水线与 CNB 云原生开发环境调用的都是同一份脚本
（scripts/start-ftp.sh / scripts/stop-ftp.sh），镜像为
jmoyer/vsftpd（vsftpd 3.0.5），fixture 在 testdata/ftp/fixture/。
详见 docs/porting/05-testing.md 第 4 节。
#公共脚本
跨 CI 复用、需要跟平台无关的脚本统一放在 scripts/：
| 脚本 | 作用 |
|---|---|
| scripts/start-ftp.sh | 起四个真实 FTP 服务器容器并轮询端口，起不来直接 exit 1 |
| scripts/stop-ftp.sh | 打印每个容器的日志并删除，从不失败 |
#目录结构
所有源码直接平铺在仓库根目录，没有包目录层级。原先的 types/ client/ parse/
这些目录全部展开成了同级的 .mbt 文件，引用也从 @types.Entry 变成直接的 Entry
（都在同一个包 PaiGack/ftp 里）。
.
├── entry.mbt Entry / EntryType / TransferType 纯逻辑
├── status.mbt RFC 959 状态码与常量 + status_text() 纯逻辑
├── error.mbt FtpError / FtpErrors 纯逻辑
├── parse.mbt RFC3659 / UNIX ls / DOS DIR / hostedftp 解析器 纯逻辑
│ 回退链 + LIST 时间字段解析 + 字段扫描器
├── pathutil.mbt 远端路径 join（对齐 Go path.Join 语义） 纯逻辑
├── control.mbt 控制通道：命令编码、多行响应、状态码校验 IO
│ + 流量日志包装
├── transport.mbt EPSV / PASV / PRET / REST / 数据连接 / TLS 建立 IO
├── client.mbt FTPClient + Session/Options + DialOptions IO
│ + SIZE / MDTM / MFMT
├── dial.mbt dial / 登录 / FEAT 能力协商 IO
├── commands.mbt CWD / PWD / MKD / RMD / DELE / RNFR+RNTO IO
│ / NOOP / REIN / QUIT
├── list.mbt / transfer.mbt / walker.mbt
│ 列表、传输、目录树遍历 IO
├── cmd/ftp/ CLI 示例：ls / get / put / walk / mkdir / rm
├── scripts/ 跨 CI 复用的公共脚本
│ ├── start-ftp.sh 起四个真实 FTP 服务器容器（CNB / GitHub 共用）
│ └── stop-ftp.sh 打容器日志并清理
├── testdata/ftp/ 测试数据：fixture 与 vsftpd 配置模板
├── .cnb.yml / .github/workflows/ CNB 与 GitHub 两条流水线（调同一份 scripts/）
├── moon.pkg 根包清单（唯一的源码包）
└── moon.mod 模块根根包只有一个 moon.pkg，它的普通 import 块里带着 moonbitlang/async：纯逻辑与 IO
源码同属一个包，MoonBit 目前也没有「按文件限定 import」的语法。分层约束因此落在每个
源文件头部的 // Layer: pure logic / // Layer: IO 标记上，目录树按层分组列出文件名。
依赖方向单向、禁止反向，详见 docs/porting/01-architecture.md。
#文档
- docs/porting.md — 移植总体方案
- docs/porting/ — 实施文档集（架构、上游映射、工作包、API 映射、测试、兼容清单、风险、验收）
#致谢与来源
本项目为 jlaffaye/ftp（ISC License）的 MoonBit 移植，
参考其协议实现与测试用例。原项目版权归 Julien Laffaye 所有。
#许可证
Apache-2.0，见 LICENSE。
FtpError
pub(all) suberror FtpError {
ServerError(code~ : Int, msg~ : String)
InvalidCommand(arg~ : String)
UnsupportedListLine(line~ : String)
UnsupportedListDate(field~ : String)
ParseError(msg~ : String)
} derive(Debug)Error type for every failure that is produced by the FTP protocol layer
itself (as opposed to failures raised by the underlying IO stack, which
bubble up untouched so callers can still inspect the OS error).
FtpErrors
Aggregation of several failures that happened during one logical
operation. This mirrors Go's errors.Join: the upstream implementation
deliberately keeps every error (transfer + close + status read) instead
of returning as soon as the first one shows up.
Control
An FTP control connection: a line buffered reader/writer pair over the
underlying socket.
The reader and the writer are kept as trait objects so the same code drives
a plain Tcp socket and a Tls connection after AUTH TLS.
Control::host
The peer address of the control connection.
Control::new
Wrap an already connected reader/writer pair.
Control::read_line
Read one line, without its trailing CRLF. Raises ReaderClosed when the
connection was closed before a complete line arrived.
Control::send_line
Write line followed by CRLF.
DataConn
The data connection used for one transfer.
DataConn::close
Close the data connection without touching the control channel.
DataConn::reader
The readable end of the data connection.
DataResponse
A data transfer in progress, returned by retr / retr_from.
It implements @io.Reader; close() is idempotent and performs the
mandatory 226 wrap-up read.
DataResponse::close
Release the data connection and read the closing 226.
This is upstream's checkDataShut plus Close: dropping it would leave
the trailing 226 in the control channel and desynchronise the next
command. Errors from the two phases are aggregated.
DataResponse::read
async fn DataResponse::read(self : DataResponse, dst : FixedArray[Byte], offset? : Int, max_len? : Int) -> IntRead up to max_len bytes of the transfer.
DialOptions
pub struct DialOptions {
timeout_ms : Int
shut_timeout_ms : Int
tls : Bool
explicit_tls : Bool
trust : TrustedRoot
disable_epsv : Bool
trust_pasv_ip : Bool
disable_utf8 : Bool
disable_mlsd : Bool
writing_mdtm : Bool
force_list_hidden : Bool
location : Zone
}The connection options, the MoonBit counterpart of upstream's 16
DialWith* functions. Every field has a documented default so that
dial(addr) alone is a valid call.
DialOptions::default
The documented defaults: 30s connect timeout, no TLS, EPSV enabled,
PASV IP untrusted, UTF8 and MLSD enabled, UTC timestamps.
DialOptions::set_disable_epsv
Turn EPSV off, forcing PASV.
DialOptions::set_disable_mlsd
Turn MLSD off, forcing LIST.
DialOptions::set_disable_utf8
Turn OPTS UTF8 ON off.
DialOptions::set_explicit_tls
Turn explicit AUTH TLS on or off.
Force LIST -a.
DialOptions::set_location
Replace the timezone used to interpret LIST timestamps.
DialOptions::set_shut_timeout_ms
Replace the 226 wrap-up timeout in milliseconds.
DialOptions::set_timeout_ms
Replace the connect timeout in milliseconds.
DialOptions::set_tls
Turn implicit TLS on or off.
DialOptions::set_trust
Replace the certificate trust policy.
DialOptions::set_trust_pasv_ip
Trust or distrust the IP returned by PASV.
DialOptions::set_writing_mdtm
Use MDTM <time> <path> to write timestamps (VsFtpd quirk).
DialOptions::to_state_options
Project a DialOptions onto the subset of parameters the data channel
layer needs.
Entry
pub struct Entry {
name : String
target : String
type_ : EntryType
size : UInt64
time : ZonedDateTime
} derive(Debug)A single remote directory entry.
Mirroring upstream ftp.Entry:
- target is empty for non-symlinks (Go zero value semantics),
- time carries an explicit timezone because LIST timestamps are wall-clock time in the server's timezone.
Entry::set_name
Replace the name of an entry in place.
Entry::set_size
Replace the size of an entry in place.
Entry::set_target
Replace the symlink target of an entry in place.
Entry::set_time
Replace the modification time of an entry in place.
EntryType
FTPClient
The FTP client, the equivalent of upstream ftp.ServerConn.
Upstream documents this type as not safe for concurrent use. We keep the
same constraint but enforce it with a Mutex so that a misuse shows up as
serialized commands instead of a corrupted session — a deliberate
improvement over the Go implementation, with unchanged semantics.
FTPClient::has_feature
Whether the server advertised name in its FEAT list.
FTPClient::is_closed
Whether the client already sent QUIT.
FTPClient::is_get_time_supported
Whether the server accepts MDTM to read modification times.
FTPClient::is_mfmt_supported
Whether the server accepts MFMT to set modification times.
FTPClient::is_mlst_supported
Whether the server advertised MLST (and MLSD was not disabled
explicitly).
FTPClient::is_set_time_supported
Whether the modification time can be written, either via MFMT or via the
VsFtpd style MDTM <time> <path>.
FTPClient::is_time_precise_in_list
Whether LIST output carries second level precision. Servers without
MDTM only give minute precision through LIST.
FTPClient::location
The timezone used to interpret LIST timestamps.
FTPClient::lock
Acquire the internal lock, making every public operation serialized.
Upstream documents ServerConn as not concurrency safe; enforcing it at
runtime is a deliberate improvement that does not change the semantics.
FTPClient::options
The connection options this client was dialed with.
FTPClient::session
The negotiated session state shared with the data channel layer.
FTPClient::set_closed
Mark the client as closed so that quit becomes idempotent.
FTPClient::set_features
Replace the cached FEAT feature set.
FTPClient::set_location
Replace the timezone used to interpret LIST timestamps.
FTPClient::set_mdtm_can_write
Record whether MDTM may be used to write timestamps (VsFtpd quirk).
FTPClient::set_mdtm_supported
Record whether the server supports MDTM.
FTPClient::set_mfmt_supported
Record whether the server supports MFMT.
FTPClient::set_mlst_supported
Record whether the server supports MLST / MLSD.
FTPClient::state_options
The data channel view of the connection options.
ListDateField
type ListDateFieldThe pieces of a LIST date field: MMM is consumed by the caller.
ListDateField::day
The day of month of a parsed date field.
ListDateField::has_time
Whether the field used the yearless HH:MM shape.
ListDateField::hour
The hour, 0 when the field carried none.
ListDateField::minute
The minute, 0 when the field carried none.
ListDateField::next
The index right after the parsed date field.
ListDateField::year
The year of a parsed date field, 0 when the field carried none.
ListFormat
Which of the four parsers recognised a listing line. The order of the
variants is the fallback order used by parse_list_line.
Options
pub struct Options {
disable_epsv : Bool
trust_pasv_ip : Bool
tls : Bool
timeout_ms : Int
shut_timeout_ms : Int
trust : TrustedRoot
}The connection parameters that affect the data channel, mirroring the
subset of upstream DialOptions that transport cares about.
Options::default
Default options, matching the documented defaults in
docs/porting/04-api-mapping.md.
Options::disable_epsv
Whether EPSV is disabled by configuration.
Options::new
fn Options::new(disable_epsv : Bool, trust_pasv_ip : Bool, tls : Bool, timeout_ms : Int, shut_timeout_ms : Int, trust : TrustedRoot) -> OptionsBuild the data channel options explicitly.
Options::shut_timeout_ms
Timeout pushing the control connection before the 226 read, milliseconds.
Options::timeout_ms
Connect timeout for the data connection, milliseconds.
Options::tls
Whether the data connection is wrapped in TLS.
Options::trust
The certificate trust policy for TLS data connections.
Response
A parsed FTP reply: the numeric status code and the (possibly multi line)
message body.
The body keeps the text of the framing status lines, matching the semantics
of Go's textproto.ReadResponse; see read_response for why the callers
depend on that.
Response::message
The message body of the reply.
Scanner
pub struct Scanner {
src : String
offset : Int
}A whitespace separated field scanner, a faithful port of upstream
scanner.go.
The position semantics are not intuitive and upstream has a dedicated
test for them, so they are spelled out here:
new Scanner("foo bar x y")
.next() -> "foo", position stops *after* the run of spaces
.remaining() -> " bar x y" // the leading space is kept
.next() -> "bar"
.remaining() -> "x y"In other words next() consumes the field and exactly one following
space. Everything after that stays in remaining().
Scanner::next
Consume and return the next whitespace separated field.
Returns "" at end of input. As in upstream, an empty field is only
produced at the end — runs of spaces never yield empty fields.
Scanner::next_fields
Read up to count consecutive fields. Stops early (without raising) when
the input is exhausted, exactly like upstream nextFields.
Session
Everything transport needs from a dialed FTP session.
This type exists to break the otherwise circular dependency between the
client package (which owns FTPClient) and the transport package
(which needs the control connection and the capability flags). client
embeds a Session and fills it in during dial / feat, transport
only reads it.
Session::control
The control connection of this session.
Session::new
Build a session around an already established control connection.
Session::options
The connection parameters of this session.
Session::set_skip_epsv
Remember that EPSV failed; every later transfer goes through PASV.
Session::set_use_pret
Record whether the server supports PRET.
Session::skip_epsv
Whether EPSV has already failed and must not be retried.
TransferType
The transfer type of the data connection, matching the FTP TYPE command
arguments.
TransferType::argument
The FTP TYPE argument, an alias of to_string that reads better at the
call site.
TransferType::from_string
Parse a TYPE command argument back into a TransferType, the inverse of
TransferType::to_string.
TransferType::to_string
The argument string sent with the TYPE command.
Walker
A depth-first directory tree walker, a faithful port of upstream
ftp.Walker.
The API contract matters here: next() returns false on a listing error
instead of raising, and the error is readable through err().
Walker::entries
The entries currently waiting on the stack, oldest first.
Walker::next
Advance to the next entry, returning false when the walk is finished or
when a listing failed.
The five steps are exactly upstream's:
- initialise cur to a synthetic folder entry for the root,
- list cur when descend is set, recording (not raising) failures,
- push every child except . and ..,
- stop when the stack is empty,
- pop the stack top, reset descend, return true.
Walker::pop
Drop and return the most recently pushed entry, if any.
Walker::push
Push a child entry onto the walk stack.
Walker::set_stack
Replace the pending entry stack.
Walker::skip_dir
Do not descend into the directory returned by the last next().
append
APPE <path>, appending a file.
apply_list_time
fn apply_list_time(entry : Entry, year : Int, month : Int, day : Int, has_time : Bool, hour : Int, minute : Int, now : ZonedDateTime) -> Unit raise FtpErrorInterpret the MMM DD HH:MM / MMM DD YYYY time field of a LIST line.
This is upstream's setTime including the six month rule from
info ls 10.1.6:
- when the field contains : there is no year, so the current year is assumed; if the resulting instant is not before now + 6 months, the year is decremented,
- when the field has no : the year must be exactly four digits, a malformed year is an error (not a fallback),
- a missing time (HH:MM) defaults to midnight.
change_dir
CWD <path>, expecting 250.
change_dir_to_parent
CDUP, expecting 250.
check_data_shut
Read the 226 (or 250) that terminates a transfer. Must always run
before the next command is sent.
check_for_command_injection
Refuse command arguments that contain CR or LF.
Upstream calls this checkForCommandInjection; the check must happen
before a single byte is written to the socket, otherwise a crafted path
could smuggle extra FTP commands into the session.
cmd
Send cmd (already encoded) and return the reply.
cmd_data_conn_from
Open a data connection and start a transfer command on it.
This is the heart of the data channel and follows upstream
cmdDataConnFrom step by step:
- PRET <cmd> first when the server advertised PRET,
- open the data connection,
- REST <offset> when a resume offset was given, expecting 350,
- send the transfer command, expecting 125 or 150,
- on a non 2xx answer, close the data connection before raising.
cmd_expect
Send cmd and require one of the expected status codes.
An empty expected list accepts any code, which is how upstream spells
cmd(..., -1) for the expected == -1 case. A mismatch raises
FtpError::ServerError carrying the original message.
cmd_format
Send \format`` with args applied through {} substitution and require
one of the expected codes. Convenience wrapper mirroring upstream
cmd(format, args, expected...).
current_dir
PWD, returning the path inside the quoted part of the 257 reply.
default_dial_timeout_ms
let default_dial_timeout_ms : IntDefault timeout used when dialing a server, in milliseconds
(upstream ftp.DefaultDialTimeout, 30s).
dial
async fn dial(addr : String, timeout_ms? : Int, shut_timeout_ms? : Int, tls? : Bool, explicit_tls? : Bool, trust? : TrustedRoot, disable_epsv? : Bool, trust_pasv_ip? : Bool, disable_utf8? : Bool, disable_mlsd? : Bool, writing_mdtm? : Bool, force_list_hidden? : Bool, location? : Zone) -> FTPClientConnect to addr (host or host:port) and return a ready client.
The options mirror the Go DialWith* family; they are labels rather than
a function-options variadic, which is the MoonBit idiom recorded in
docs/porting/04-api-mapping.md.
Once connected the client reads the greeting (expecting 220). When
explicit_tls is set it then sends AUTH TLS, expects 234 and upgrades
the control connection.
epoch
The UNIX epoch, a convenient zero value for Entry::time.
@time.ZonedDateTime::from_unix_second raises, which is awkward in pure
parsers, so the fallback lives here where the failure path can be handled
exactly once.
epsv
Send EPSV (RFC 2428) and return the data port the server opened.
229 Entering Extended Passive Mode (|||6446|)
extract_quoted
fn extract_quoted(message : String) -> String?Extract the substring between the first pair of double quotes, which is how
257 "/incoming" created. encodes the path.
feat
Ask the server for its feature list and cache the capabilities the client
cares about.
A server that answers FEAT with anything other than 211 simply has no
feature list; that is not an error, upstream treats it the same way.
file_size
SIZE <path>, expecting 213.
find_date_start_pub
fn find_date_start_pub(line : String, start : Int) -> Int?Index of the first MMM DD date field at or after start.
flatten_errors
Return every error carried by an aggregate, or the error itself when it is
not an aggregate. Useful for tests and for re-raising partial failures.
format_mdtm
Render a timestamp as yyyyMMddHHmmss in UTC.
get_data_port
Get the port to connect to, preferring EPSV and permanently falling back
to PASV after the first failure.
The "EPSV failed once, never try again" behaviour is a deliberate upstream
design choice: some servers answer EPSV with an error but also with a
malformed PASV reply, and retrying EPSV on every transfer turns a fast
failure into a timeout per file.
get_entry
MLST <path>: the facts of a single entry.
The body carries the framing lines too, so this follows upstream exactly:
the message must split into at least three lines, the first and the last
are dropped, and the remaining lines are merged into one entry (RFC 3659
allows the facts of a single file to be spread over several lines).
get_time
MDTM <path>, expecting 213 and a yyyyMMddHHmmss UTC timestamp.
is_all_digits
fn is_all_digits(src : String) -> BoolWhether every byte of src is an ASCII digit.
is_bogus_data_ip
fn is_bogus_data_ip(cmd_ip : String, data_ip : String) -> BoolDecide whether the IP returned by PASV may be used as the data
destination.
Upstream's rule, kept verbatim: the address is bogus when it is multicast,
or when its "privateness" differs from the control connection, or when its
loopback-ness differs. This is what makes a server that answers
PASV ... (10,0,0,1,...) from a public IP unusable unless the caller opts
in with trust_pasv_ip.
is_continuation
fn is_continuation(line : String) -> BoolWhether the line is a multi line continuation (211-Features:), i.e. the
fourth byte is -.
is_loopback
fn is_loopback(ip : String) -> BoolWhether ip is a loopback address (127.0.0.0/8 or ::1).
is_multicast
fn is_multicast(ip : String) -> BoolWhether ip is a multicast address (224.0.0.0/4 or ff00::/8).
is_positive_completion
fn is_positive_completion(code : Int) -> BoolWhether the code is a 2xx "positive completion" reply.
is_positive_intermediate
fn is_positive_intermediate(code : Int) -> BoolWhether the code is a 1xx "positive intermediate" reply.
is_private
fn is_private(ip : String) -> BoolWhether ip is a private (RFC 1918 / link local / ULA) address.
join
fn join(base : String, name : String) -> StringJoin two remote path fragments the way Go's path.Join does: the result
is always cleaned (. dropped, .. resolved, no empty segment, no
trailing slash), using / as separator. A leading / in the inputs is
significant only for the first non-empty segment, matching path.Join.
join("root/", "lo") == "root/lo"
join("root", "a") == "root/a"
join("root", "..") == "."
join("", "a") == "a"join_all
Variadic form of join, equivalent to path.Join(parts...).
join_errors
Build an aggregated error, collapsing the trivial cases so callers do not
have to care about them:
- no error at all -> None
- exactly one error -> that error itself
- otherwise -> FtpErrors::MultipleErrors
list
List a directory.
MLSD is preferred when the server supports it; otherwise LIST (with
-a when force_list_hidden is set) is parsed with the four parser
fallback. Lines that no parser recognises are skipped, not fatal: real
servers emit total 1 headers and other noise.
login
Authenticate with USER / PASS, then negotiate capabilities.
The sequence matches upstream Login:
USER -> 331 -> PASS -> 230, then FEAT, then TYPE I, then
optionally OPTS UTF8 ON, and for implicit TLS PBSZ 0 / PROT P.
The FEAT / OPTS / TYPE steps are taken outside the client lock: they
are public API and take the lock themselves, and the lock is deliberately
not re-entrant (see FTPClient::lock). Holding it across these calls would
deadlock every login against a real server.
logout
REIN, expecting 220: drops the authentication state but keeps the
control connection.
make_entry
Build an entry with the given name and type; the target defaults to the
empty string and the time to the epoch in UTC, both of which the parsers
overwrite when the server supplies the information.
make_file
Build a plain file entry, the most common shape.
make_folder
Build a folder entry, the shape used by the walker root marker.
make_link
Build a link entry with the given target.
month_names
The English month abbreviations accepted in LIST output, in calendar
order (Jan == 1).
name_list
NLST <path>: a bare list of names, one per line.
new_datetime
fn new_datetime(year : Int, month : Int, day : Int, hour : Int, minute : Int, zone : Zone) -> ZonedDateTime raise FtpErrorBuild a ZonedDateTime in zone, raising UnsupportedListDate when the
calendar fields are not a valid date (e.g. Feb 30).
open_data_conn
Open the passive data connection.
With TLS the socket is connected but the handshake is deferred to the first
read/write: ProFTPD and PureFTPD both refuse a data connection that starts
its handshake before the transfer command was answered.
parse_decimal
fn parse_decimal(text : String) -> Int?Parse a decimal string into an Int, returning None on any non-digit.
parse_dos_dir_line
Parse a MS-DOS / Windows DIR style line:
07-27-17 04:50PM 1264086 File.txt
11-06-16 09:31AM <DIR> SoftlibFaithful port of upstream parseDirListLine:
- the first field is the date and is tried against four layouts (01-02-06 03:04PM with one or two digit month/day/year, and the 01-02-06 15:04 24 hour variant),
- <DIR> switches the type to folder and the size to 0,
- anything else must be a plain decimal size.
parse_epsv
Extract the port from an EPSV reply body.
The body is expected to contain ||| followed by the port and a closing
|. A malformed reply raises ParseError instead of silently using port
0, which would otherwise hang the connect.
parse_features
Parse a FEAT body into a set of command names.
Feature lines have the shape COMMAND [description]; only the first token
is kept, uppercased.
The leading space test is not cosmetic: the body carries the text of the
211-Features: and 211 End framing lines too (see read_response), and
once trimmed they would otherwise register as features named FEATURES:
and END. Upstream filters with exactly this test.
parse_hostedftp_line
Parse a hostedftp.com style line, which is ls -l without the link count:
drwxr-xr-x folder 0 Aug 15 05:49 !!!-Tipp des Haus!Upstream parseHostedFTPLine rewrites the first field by appending a
space and the literal link count 0, then delegates to the Unix ls
parser. Keeping that trick means the two parsers stay in sync.
parse_list_date_field
Parse the two year-dependent shapes used by the LIST time field, given
the MMM DD prefix has already been consumed.
Returns (year, month, day, has_time, hour, minute, next_index). year is
0 when the field carried no year at all (the HH:MM shape), the caller
substitutes the current year.
parse_list_line
Parse a single LIST / MLSD line, trying the four parsers in the fixed
fallback order documented in docs/porting/02-upstream-map.md.
line must not contain the trailing CR/LF. now is the reference instant
used for the "no year" heuristic and is an explicit parameter so that the
upstream test cases (fixed at 2017-03-10 23:00 UTC) stay reproducible.
parse_ls_line
Parse a Unix ls -l style line:
drwxr-xr-x 3 110 1002 3 Dec 02 2009 pub
-rw-r--r-- 1 marketwired marketwired 12016 Mar 16 2016 newsml
drwxr-xr-x folder 0 Aug 15 05:49 !!!-Tipp des Haus!Port of upstream parseLsListLine:
- the permission field is 10 bytes, or 11 with an ACL + marker,
- the type comes from the first character,
- the size is the last numeric field before the date, which is what makes the ls -l and the "no link count" variants both parse,
- the date is found by scanning for MMM DD , so extra columns do not shift the parse,
- the name is the entire remainder, so spaces inside names survive,
- a symlink's -> is split into name and target.
parse_ls_time
fn parse_ls_time(src : String, start : Int, now : ZonedDateTime) -> (ZonedDateTime, Int)? raise FtpErrorParse an ls -l time field: MMM DD HH:MM or MMM DD YYYY.
Returns the resolved time and the index right after the field.
parse_mdtm
Parse a yyyyMMddHHmmss timestamp as UTC.
parse_month
fn parse_month(name : String) -> Int?Parse a three letter month name case-insensitively, returning 1..12.
parse_next_rfc3659_line
Merge the facts of a continuation line into the previous RFC 3659 entry.
Some servers answer MLST with the same entry spread over several lines;
upstream parseNextRFC3659ListLine requires the names to match.
parse_octet
fn parse_octet(text : String) -> Int?Parse a decimal byte value (0..255), returning None otherwise.
parse_pasv
Parse the six comma separated numbers of a PASV reply into an IP and a
port (port = p1 * 256 + p2). Fewer than six numbers is an error.
parse_port
fn parse_port(digits : String) -> Int?Parse a non-empty decimal string into an Int, returning None on any
non-digit byte or on overflow.
parse_rfc3659_line
Parse a single RFC 3659 (MLSD / MLST) fact line:
type=file;size=951;modify=20140101000000; welcome.msgFaithful port of upstream parseRFC3659ListLine:
- the facts are separated by ;, the last one is followed by the name,
- fact keys are matched case-insensitively (Type= works as well, which is what WFTPD/Serv-U emit),
- sizd is accepted as a typo for size,
- an unrecognised type= value is an error, not a fallback,
- a line whose last fact is not terminated by ; is not an RFC 3659 line.
parse_uint
Parse an unsigned 64 bit integer in the given radix, rejecting empty input
and overflowing values.
pasv
Send PASV and return the (ip, port) pair the server advertises.
227 Entering Passive Mode (127,0,0,1,196,6)
quit
QUIT and close the connection.
The errors are aggregated instead of short-circuiting: a failure to send
QUIT must not hide a failure to close the socket, and the other way
round. This mirrors upstream's use of errors.Join.
read_response
Read a complete reply from the control connection, handling both the single
line and the multi line (RFC 959 211-...211 End) shapes.
The result reproduces Go's net/textproto.ReadResponse byte for byte,
because the rest of the port (starting with FEAT and MLST) is written
against that shape. Two consequences are load bearing:
- the message includes the text of the first and of the terminating status line, joined by \n. Go's feat() filters those back out with a leading space test, and its GetEntry relies on lines[1:lc-1]; a body that dropped the boundary lines would break MLST outright.
- a line that is exactly three digits, with no separator, is a short response error, not an empty message.
The multi line terminator is the line that repeats the code without a
dash. Getting that wrong makes FEAT swallow the next reply, so it has a
dedicated test.
remove_dir
RMD <path>, expecting 250.
rename
Rename in two steps, RNFR -> 350 then RNTO -> 250.
retr
RETR <path>, returning a readable DataResponse.
retr_from
RETR <path> after REST <offset>, i.e. a resumed download.
set_file_time
Set the modification time of path.
MFMT is tried first; when the server only advertises MDTM and
writing_mdtm is set, the VsFtpd quirk MDTM <time> <path> is used
instead. When neither is available the call raises ServerError with
code 502, matching upstream's "not implemented" behaviour.
set_size
Parse a numeric size field the way Go's strconv.ParseUint(s, 0, 64) does:
an explicit 0x / 0X prefix means hex, 0o / 0O means octal,
a leading 0 means octal, and anything else is decimal.
set_transfer_type
TYPE I / TYPE A.
split_addr
fn split_addr(addr : String, default_port : Int) -> (String, Int)Split host / host:port into its two components, applying default_port
when the caller did not specify one.
status_closing_control_connection
let status_closing_control_connection : Int221 Service closing control connection. — the answer to QUIT.
status_restart_marker_answer
let status_restart_marker_answer : IntRFC 959 / RFC 2228 / RFC 2428 / RFC 3659 status codes.
Values are kept byte-for-byte identical to upstream status.go. Several
distinct constants intentionally share the same numeric value (the RFCs
overload the code), which is fine because they are plain Int constants.
let status_service_unavailable : Intstatus_text
fn status_text(code : Int) -> StringThe human readable text for every known status code, copied from
upstream status.go (no localization on purpose).
stor
STOR <path>, uploading from source.
stor_from
STOR <path> after REST <offset>, i.e. a resumed upload.
The zero-byte TLS case is handled explicitly: ProFTPD answers
Unable to build data connection when the data connection was never
written to, because the TLS handshake never happened. Uploading nothing
while triggering the handshake explicitly keeps the server happy.
Install
Download zipA pure MoonBit FTP client library ported from jlaffaye/ftp, supporting passive mode, MLSD/LIST parsing, resume and FTPS.
ftpnetworkclientprotocolasync
0.1.0
Apache-2.0
Updated 19 hours ago
2 downloadsDependencies
- moonbitlang/async0.21.3
- moonbitlang/x0.5.4