XanTools.FtpServer 3.0.0

XanFTP: Custom Server-Client File Transfer Protocol

XanFTP is a C# implementation of a non-standard, lightweight file transfer protocol (FTP). It enables efficient, asynchronous file transfers between a client and a server with extensibility for advanced use cases.

Key Features

• Custom Protocol: A simplified and extendable file transfer protocol.
• Server-Client Architecture: Facilitates bidirectional file transfers.
• Dynamic Metadata: Attach metadata to file operations for advanced scenarios.
• Asynchronous Design: Optimized for performance and scalability.
• Extensible API: Integrate custom handlers, file options, and serialization methods.

Table of Contents

1. Installation
2. Getting Started
3. Detailed API Reference
   • Core Classes
   • Session Management
   • Options and Metadata
   • Helper Methods
4. Examples
   • Server Example
   • Client Example
5. Technical Explanation
6. Contributing

Installation

Install XanFTP via NuGet:

dotnet add package XanFTP

Getting Started

Prerequisites

• .NET 6.0 or later

Basic Setup

• Server : Instantiate and start the server to listen for client connections.

• Client : Connect to the server and initiate file operations.

Detailed API Reference

Core Classes

XanFtpServer Manages server-side operations such as accepting client connections and handling file transfers.

• Constructor : public XanFtpServer(IPEndPoint localEndPoint) Initializes the server with a specified local endpoint.

• Methods :

  • Start(): Starts the server with a default backlog size.

  • Start(int backlog): Starts the server with a specified backlog size.

  • Stop(): Stops the server from listening for connections.

  • AcceptConnectionAsync(ServerAcceptHandler acceptHandler, CancellationToken cancellationToken = default): Accepts incoming client connections and processes file transfer requests. XanFtpClient Handles client-side operations such as sending and requesting files.

• Constructor : public XanFtpClient()

• Methods :

  • Connect(IPEndPoint endPoint): Connects to a server endpoint.

  • SendFileAsync(FileSendOptions options, Dictionary<string, dynamic>? additionalData, CancellationToken cancellationToken = default): Sends a file to the server.

  • RequestFileAsync(FileAcceptOptions options, Dictionary<string, dynamic>? additionalData, CancellationToken cancellationToken = default): Requests a file from the server.

Session Management

FileSession Base class for managing file-related sessions.

• Properties :

  • NetworkStream: The stream used for communication.

  • FileName: The name of the file being transferred.

  • AdditionalData: Metadata associated with the session.

  • AcceptHandler: Delegate for handling server-side permissions.

  • OperationType: The type of operation (e.g., send or request file).

  • FileOptions: Options for file transfer. SendFileSession Manages file-sending sessions and extends FileSession.

• Properties :
  • FileSegments: A collection of file segments to be sent. AcceptFileSession Manages file-accepting sessions and extends FileSession.

Options and Metadata

FileOptions Base class for file-related options.

• Properties :

  • FilePath: The path to the file being transferred. FileSendOptions Options for sending files.

• Properties :

  • MaxBufferSize: Maximum buffer size for file segments. FileAcceptOptions Options for accepting files.

• Properties :

  • OutputFile: Path to save the accepted file.

Helper Methods

XanFtpHelper Provides static methods for handling file transfers.

• Methods :

  • SendFileAsync(SendFileSession session, CancellationToken cancellationToken = default): Sends a file in segments to a server.

  • AcceptFileAsync(AcceptFileSession acceptFileSession, CancellationToken cancellationToken = default): Accepts and writes a file to a specified location.

Examples

Server Example

var server = new XanFtpServer(new IPEndPoint(IPAddress.Any, 12345));
server.Start();

await server.AcceptConnectionAsync((operation, filePath, additionalData) =>
{
    Console.WriteLine($"Operation: {operation}, File: {filePath}");
    return new FileAcceptOptions { OutputFile = "received_file.txt" };
});

Client Example

var client = new XanFtpClient();
client.Connect(new IPEndPoint(IPAddress.Loopback, 12345));

// Send a file to the server
await client.SendFileAsync(new FileSendOptions
{
    FilePath = "file_to_send.txt",
    MaxBufferSize = 4096
}, null);

// Request a file from the server
await client.RequestFileAsync(new FileAcceptOptions
{
    OutputFile = "downloaded_file.txt"
}, null);

Technical Explanation

File Transfer Workflow

1. Connection Establishment : The client connects to the server using a TCP socket.

2. Session Creation : Depending on the operation, a SendFileSession or AcceptFileSession is initialized.

3. File Segmentation : The file is divided into segments, which are sent sequentially.

4. Metadata Handling : Metadata and permissions are exchanged between the client and server to validate the operation.

5. Completion : Once all segments are transferred, the session is finalized.

JSON Serialization

The DynamicJsonConverter dynamically maps JSON tokens to corresponding .NET types, enabling seamless metadata handling. Example:

var json = "{\"key\": 123}";
var dictionary = JsonSerializer.Deserialize<Dictionary<string, dynamic>>(json, new JsonSerializerOptions
{
    Converters = { new DynamicJsonConverter() }
});

Contributing

We welcome contributions to XanFTP. To contribute:

1. Fork this repository.

2. Create a feature branch.

3. Submit a pull request with detailed explanations of your changes.