FTP Server Development Assistant

Expert assistant for working with a Dart-based FTP server implementation that supports both read-only and read-and-write modes with pluggable file system backends.

Project Overview

This is a simple FTP server implementation in Dart that:

Core Architecture

Main Components

1. **FtpServer** (`lib/ftp_server.dart`)

- Main server class for socket binding and connection management

- Maintains active session list for cleanup

- Supports `start()` (blocking) and `startInBackground()` (non-blocking)

2. **FtpSession** (`lib/ftp_session.dart`)

- Manages individual client sessions with authentication

- Handles data connections (passive/active modes)

- Implements file transfer operations with error handling

- Manages directory navigation and file listing

3. **FTPCommandHandler** (`lib/ftp_command_handler.dart`)

- Processes FTP protocol commands (USER, PASS, LIST, RETR, STOR, etc.)

- Enforces read-only mode restrictions

- Handles standard and extended FTP commands

4. **FileOperations Interface** (`lib/file_operations/file_operations.dart`)

- Abstract interface for pluggable file system backends

- Handles path resolution and security boundaries

- Supports physical and virtual file system implementations

File System Backends

- Direct file system access mapped to single physical directory

- Full operations within root directory

- Maps multiple physical directories to virtual root folders

- Restricts operations at virtual root level

- Provides isolation between shared directories

Development Workflow

1. Running Tests

```bash

Run all tests

dart test

Run specific test file

dart test test/ftp_server_test.dart

Run file operations tests

dart test test/file_operations/

```

2. Code Quality

```bash

Static analysis (configured via analysis_options.yaml)

dart analyze

Format all Dart code

dart format .

```

3. Dependency Management

```bash

Install dependencies

dart pub get

Upgrade dependencies

dart pub upgrade

Show dependency tree

dart pub deps

```

4. Running Examples

```bash

Navigate to example and run server

cd example

dart run

```

Key Implementation Details

Server Configuration

Configure server via `ServerType` enum:

Authentication is optional - if username/password provided, clients must authenticate.

Design Patterns

Error Handling

Testing Structure

When Working on This Codebase

1. **Before Making Changes**

- Run `dart analyze` to check for existing issues

- Review relevant tests to understand current behavior

- Check `analysis_options.yaml` for linting rules

2. **Adding New Features**

- Consider if it should be in FtpServer, FtpSession, or FTPCommandHandler

- Add corresponding tests in appropriate test directory

- Update documentation if adding new commands or capabilities

- Test with both physical and virtual file operations

3. **Modifying File Operations**

- Ensure changes work for both PhysicalFileOperations and VirtualFileOperations

- Update interface if adding new operations

- Test path resolution and security boundaries

- Verify copy-on-session behavior remains correct

4. **After Changes**

- Run full test suite: `dart test`

- Check code formatting: `dart format .`

- Verify no analyzer warnings: `dart analyze`

- Test with example server if applicable

5. **Debugging**

- Check server logs for connection and command details

- Use `dart run` in example directory to test live server

- Review session state management for connection issues

- Verify file system backend isolation

Common Tasks

Adding a New FTP Command

1. Add command handler method in `FTPCommandHandler`

2. Register command in command dispatch logic

3. Check if command should be restricted in read-only mode

4. Add tests in `test/ftp_server_test.dart`

Adding a New File System Backend

1. Create new class implementing `FileOperations` interface

2. Implement all required methods with proper error handling

3. Add unit tests in `test/file_operations/`

4. Update example to demonstrate new backend

Improving Error Handling

1. Identify failure points in current code

2. Add proper try-catch blocks with specific exceptions

3. Send appropriate FTP response codes to client

4. Add logging for debugging

5. Write tests for error scenarios