Seregon/zftpd

Zero-copy FTP/HTTP Daemon compatible with all POSIX systems

C/11.0 KB/No license
include/ftp_commands.h
raw
zftpd / include / ftp_commands.h
1/*
2MIT License
3 
4Copyright (c) 2026 Seregon
5 
6Permission is hereby granted, free of charge, to any person obtaining a copy
7of this software and associated documentation files (the "Software"), to deal
8in the Software without restriction, including without limitation the rights
9to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10copies of the Software, and to permit persons to whom the Software is
11furnished to do so, subject to the following conditions:
12 
13The above copyright notice and this permission notice shall be included in all
14copies or substantial portions of the Software.
15 
16THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22SOFTWARE.
23*/
24 
25/**
26 * @file ftp_commands.h
27 * @brief FTP command handlers (RFC 959)
28 *
29 * @author SeregonWar
30 * @version 1.0.0
31 * @date 2026-02-13
32 *
33 * PROTOCOL: RFC 959 (File Transfer Protocol)
34 * EXTENSIONS: RFC 3659 (MLST, MLSD, SIZE, MDTM)
35 *
36 */
37 
38#ifndef FTP_COMMANDS_H
39#define FTP_COMMANDS_H
40 
41#include "ftp_types.h"
42 
43/*===========================================================================*
44 * AUTHENTICATION AND CONTROL
45 *===========================================================================*/
46 
47/**
48 * @brief USER command - Specify user name
49 *
50 * @param session Client session
51 * @param args User name
52 *
53 * @return FTP_OK on success, negative error code on failure
54 *
55 * @pre session != NULL
56 * @pre args != NULL (validated by protocol layer)
57 */
58ftp_error_t cmd_USER(ftp_session_t *session, const char *args);
59 
60/**
61 * @brief PASS command - Specify password
62 *
63 * @param session Client session
64 * @param args Password (optional for anonymous)
65 *
66 * @return FTP_OK on success, negative error code on failure
67 */
68ftp_error_t cmd_PASS(ftp_session_t *session, const char *args);
69 
70/**
71 * @brief QUIT command - Terminate session
72 *
73 * @param session Client session
74 * @param args (unused)
75 *
76 * @return FTP_OK (session will be closed after reply)
77 */
78ftp_error_t cmd_QUIT(ftp_session_t *session, const char *args);
79 
80/**
81 * @brief NOOP command - No operation
82 *
83 * @param session Client session
84 * @param args (unused)
85 *
86 * @return FTP_OK
87 */
88ftp_error_t cmd_NOOP(ftp_session_t *session, const char *args);
89 
90/*===========================================================================*
91 * NAVIGATION
92 *===========================================================================*/
93 
94/**
95 * @brief CWD command - Change working directory
96 *
97 * @param session Client session
98 * @param args Directory path
99 *
100 * @return FTP_OK on success, negative error code on failure
101 */
102ftp_error_t cmd_CWD(ftp_session_t *session, const char *args);
103 
104/**
105 * @brief CDUP command - Change to parent directory
106 *
107 * @param session Client session
108 * @param args (unused)
109 *
110 * @return FTP_OK on success, negative error code on failure
111 */
112ftp_error_t cmd_CDUP(ftp_session_t *session, const char *args);
113 
114/**
115 * @brief PWD command - Print working directory
116 *
117 * @param session Client session
118 * @param args (unused)
119 *
120 * @return FTP_OK
121 */
122ftp_error_t cmd_PWD(ftp_session_t *session, const char *args);
123 
124/*===========================================================================*
125 * DIRECTORY LISTING
126 *===========================================================================*/
127 
128/**
129 * @brief LIST command - List directory contents (detailed)
130 *
131 * @param session Client session
132 * @param args Directory path (optional, defaults to CWD)
133 *
134 * @return FTP_OK on success, negative error code on failure
135 */
136ftp_error_t cmd_LIST(ftp_session_t *session, const char *args);
137 
138/**
139 * @brief NLST command - Name list (simple)
140 *
141 * @param session Client session
142 * @param args Directory path (optional)
143 *
144 * @return FTP_OK on success, negative error code on failure
145 */
146ftp_error_t cmd_NLST(ftp_session_t *session, const char *args);
147 
148/**
149 * @brief MLSD command - Machine-readable directory listing (RFC 3659)
150 *
151 * @param session Client session
152 * @param args Directory path (optional)
153 *
154 * @return FTP_OK on success, negative error code on failure
155 */
156ftp_error_t cmd_MLSD(ftp_session_t *session, const char *args);
157 
158/**
159 * @brief MLST command - Machine-readable file info (RFC 3659)
160 *
161 * @param session Client session
162 * @param args File path (optional)
163 *
164 * @return FTP_OK on success, negative error code on failure
165 */
166ftp_error_t cmd_MLST(ftp_session_t *session, const char *args);
167 
168/*===========================================================================*
169 * FILE TRANSFER
170 *===========================================================================*/
171 
172/**
173 * @brief RETR command - Retrieve (download) file
174 *
175 * @param session Client session
176 * @param args File path
177 *
178 * @return FTP_OK on success, negative error code on failure
179 *
180 * @note Uses zero-copy sendfile() when available
181 */
182ftp_error_t cmd_RETR(ftp_session_t *session, const char *args);
183 
184/**
185 * @brief STOR command - Store (upload) file
186 *
187 * @param session Client session
188 * @param args File path
189 *
190 * @return FTP_OK on success, negative error code on failure
191 */
192ftp_error_t cmd_STOR(ftp_session_t *session, const char *args);
193 
194/**
195 * @brief APPE command - Append to file
196 *
197 * @param session Client session
198 * @param args File path
199 *
200 * @return FTP_OK on success, negative error code on failure
201 */
202ftp_error_t cmd_APPE(ftp_session_t *session, const char *args);
203 
204/**
205 * @brief REST command - Restart transfer
206 *
207 * @param session Client session
208 * @param args Byte offset
209 *
210 * @return FTP_OK on success, negative error code on failure
211 */
212ftp_error_t cmd_REST(ftp_session_t *session, const char *args);
213 
214/*===========================================================================*
215 * FILE MANAGEMENT
216 *===========================================================================*/
217 
218/**
219 * @brief DELE command - Delete file
220 *
221 * @param session Client session
222 * @param args File path
223 *
224 * @return FTP_OK on success, negative error code on failure
225 */
226ftp_error_t cmd_DELE(ftp_session_t *session, const char *args);
227 
228/**
229 * @brief RMD command - Remove directory
230 *
231 * @param session Client session
232 * @param args Directory path
233 *
234 * @return FTP_OK on success, negative error code on failure
235 */
236ftp_error_t cmd_RMD(ftp_session_t *session, const char *args);
237 
238/**
239 * @brief MKD command - Make directory
240 *
241 * @param session Client session
242 * @param args Directory path
243 *
244 * @return FTP_OK on success, negative error code on failure
245 */
246ftp_error_t cmd_MKD(ftp_session_t *session, const char *args);
247 
248/**
249 * @brief RNFR command - Rename from (step 1)
250 *
251 * @param session Client session
252 * @param args Source path
253 *
254 * @return FTP_OK on success, negative error code on failure
255 */
256ftp_error_t cmd_RNFR(ftp_session_t *session, const char *args);
257 
258/**
259 * @brief RNTO command - Rename to (step 2)
260 *
261 * @param session Client session
262 * @param args Destination path
263 *
264 * @return FTP_OK on success, negative error code on failure
265 *
266 * @pre RNFR must have been called first
267 */
268ftp_error_t cmd_RNTO(ftp_session_t *session, const char *args);
269 
270/*===========================================================================*
271 * DATA CONNECTION
272 *===========================================================================*/
273 
274/**
275 * @brief CPFR command - Copy from
276 *
277 * @param session Client session
278 * @param args Source path
279 *
280 * @return FTP_OK on success, negative error code on failure
281 */
282ftp_error_t cmd_CPFR(ftp_session_t *session, const char *args);
283 
284/**
285 * @brief CPTO command - Copy to
286 *
287 * @param session Client session
288 * @param args Destination path
289 *
290 * @return FTP_OK on success, negative error code on failure
291 */
292ftp_error_t cmd_CPTO(ftp_session_t *session, const char *args);
293 
294/**
295 * @brief COPY command - Copy file
296 *
297 * @param session Client session
298 * @param args Source and Destination path
299 *
300 * @return FTP_OK on success, negative error code on failure
301 */
302ftp_error_t cmd_COPY(ftp_session_t *session, const char *args);
303 
304/**
305 * @brief PORT command - Active mode data connection
306 *
307 * Format: PORT h1,h2,h3,h4,p1,p2
308 *
309 * @param session Client session
310 * @param args Client address and port
311 *
312 * @return FTP_OK on success, negative error code on failure
313 */
314ftp_error_t cmd_PORT(ftp_session_t *session, const char *args);
315 
316/**
317 * @brief PASV command - Passive mode data connection
318 *
319 * @param session Client session
320 * @param args (unused)
321 *
322 * @return FTP_OK on success, negative error code on failure
323 */
324ftp_error_t cmd_PASV(ftp_session_t *session, const char *args);
325 
326/**
327 * @brief EPSV command - Extended passive mode (RFC 2428)
328 *
329 * @param session Client session
330 * @param args (unused or "ALL")
331 *
332 * @return FTP_OK on success, negative error code on failure
333 */
334ftp_error_t cmd_EPSV(ftp_session_t *session, const char *args);
335 
336/**
337 * @brief OPTS command - Feature negotiation (RFC 2389)
338 *
339 * @param session Client session
340 * @param args Feature + option (e.g. "UTF8 ON")
341 *
342 * @return FTP_OK on success
343 */
344ftp_error_t cmd_OPTS(ftp_session_t *session, const char *args);
345 
346/**
347 * @brief SITE command - Site-specific commands
348 *
349 * @param session Client session
350 * @param args Site command (e.g. "CHMOD 755 file")
351 *
352 * @return FTP_OK (accepts CHMOD as no-op)
353 */
354ftp_error_t cmd_SITE(ftp_session_t *session, const char *args);
355 
356/**
357 * @brief CLNT command - Client identification
358 *
359 * @param session Client session
360 * @param args Client name string
361 *
362 * @return FTP_OK (always accepted)
363 */
364ftp_error_t cmd_CLNT(ftp_session_t *session, const char *args);
365 
366/*===========================================================================*
367 * INFORMATION
368 *===========================================================================*/
369 
370/**
371 * @brief SIZE command - Return file size (RFC 3659)
372 *
373 * @param session Client session
374 * @param args File path
375 *
376 * @return FTP_OK on success, negative error code on failure
377 */
378ftp_error_t cmd_SIZE(ftp_session_t *session, const char *args);
379 
380/**
381 * @brief MDTM command - Return modification time (RFC 3659)
382 *
383 * @param session Client session
384 * @param args File path
385 *
386 * @return FTP_OK on success, negative error code on failure
387 */
388ftp_error_t cmd_MDTM(ftp_session_t *session, const char *args);
389 
390/**
391 * @brief STAT command - Return status
392 *
393 * @param session Client session
394 * @param args File/directory path (optional)
395 *
396 * @return FTP_OK on success, negative error code on failure
397 */
398ftp_error_t cmd_STAT(ftp_session_t *session, const char *args);
399 
400/**
401 * @brief SYST command - Return system type
402 *
403 * @param session Client session
404 * @param args (unused)
405 *
406 * @return FTP_OK
407 */
408ftp_error_t cmd_SYST(ftp_session_t *session, const char *args);
409 
410/**
411 * @brief FEAT command - List features
412 *
413 * @param session Client session
414 * @param args (unused)
415 *
416 * @return FTP_OK
417 */
418ftp_error_t cmd_FEAT(ftp_session_t *session, const char *args);
419 
420/**
421 * @brief HELP command - Return help information
422 *
423 * @param session Client session
424 * @param args Command name (optional)
425 *
426 * @return FTP_OK
427 */
428ftp_error_t cmd_HELP(ftp_session_t *session, const char *args);
429 
430/*===========================================================================*
431 * TRANSFER PARAMETERS
432 *===========================================================================*/
433 
434/**
435 * @brief TYPE command - Set transfer type
436 *
437 * Types: A (ASCII), I (Binary/Image)
438 *
439 * @param session Client session
440 * @param args Type code
441 *
442 * @return FTP_OK on success, negative error code on failure
443 */
444ftp_error_t cmd_TYPE(ftp_session_t *session, const char *args);
445 
446/**
447 * @brief MODE command - Set transfer mode
448 *
449 * Modes: S (Stream), B (Block), C (Compressed)
450 * Note: Only Stream mode supported
451 *
452 * @param session Client session
453 * @param args Mode code
454 *
455 * @return FTP_OK on success, negative error code on failure
456 */
457ftp_error_t cmd_MODE(ftp_session_t *session, const char *args);
458 
459/**
460 * @brief STRU command - Set file structure
461 *
462 * Structures: F (File), R (Record), P (Page)
463 * Note: Only File structure supported
464 *
465 * @param session Client session
466 * @param args Structure code
467 *
468 * @return FTP_OK on success, negative error code on failure
469 */
470ftp_error_t cmd_STRU(ftp_session_t *session, const char *args);
471 
472/*===========================================================================*
473 * ENCRYPTION (ChaCha20)
474 *===========================================================================*/
475 
476#if FTP_ENABLE_CRYPTO
477/**
478 * @brief AUTH command - Negotiate encryption
479 *
480 * Supports: AUTH XCRYPT (ChaCha20 stream cipher)
481 *
482 * @param session Client session
483 * @param args Auth mechanism ("XCRYPT")
484 *
485 * @return FTP_OK on success, negative error code on failure
486 */
487ftp_error_t cmd_AUTH(ftp_session_t *session, const char *args);
488#endif /* FTP_ENABLE_CRYPTO */
489 
490#endif /* FTP_COMMANDS_H */
491