### Configure and Start RestfulServer

Source: https://context7.com/uberto/rest4sftp/llms.txt

Demonstrates how to initialize the RestfulServer with specific FTP or SFTP backends, start the server on a port, and use it as an http4k HttpHandler for testing or embedding.

```kotlin
import com.ubertob.rest4sftp.http.RestfulServer
import com.ubertob.rest4sftp.model.CommandHandler
import com.ubertob.rest4sftp.ftp.SshJSftpClient
import com.ubertob.rest4sftp.ftp.ApacheCommonsFtpClient
import java.time.Duration

val sftpServer = RestfulServer(CommandHandler { remoteHost ->
    SshJSftpClient(remoteHost, Duration.ofSeconds(60))
})

val ftpServer = RestfulServer(CommandHandler { remoteHost ->
    ApacheCommonsFtpClient(remoteHost, Duration.ofSeconds(30))
})

val runningServer = sftpServer.start(8080)
runningServer.block()

val handler: HttpHandler = RestfulServer(CommandHandler { remoteHost ->
    SshJSftpClient(remoteHost, Duration.ofSeconds(60))
})

val request = Request(Method.GET, "/folder/Upload")
    .header("FTP-Host", "sftp.example.com")
    .header("FTP-Port", "22")
    .header("FTP-User", "user")
    .header("FTP-Password", "pass")

val response = handler(request)
```

--------------------------------

### Start rest4sftp Server (Bash)

Source: https://context7.com/uberto/rest4sftp/llms.txt

Instructions to build and run the rest4sftp server from source using Gradle. It covers command-line arguments for protocol selection (SFTP/FTP), port configuration, and timeout settings.

```bash
git clone https://github.com/uberto/rest4sftp.git
./gradlew clean build
cd build/distributions
unzip rest4sftp-1.0.4.zip
rest4sftp-1.0.4/bin/rest4sftp --sftp --port 8080
```

--------------------------------

### Deploy rest4sftp with Docker

Source: https://context7.com/uberto/rest4sftp/llms.txt

Guides for deploying rest4sftp using Docker, including building a local image, running a container, and configuring Docker Compose. It demonstrates how to map ports and specify server arguments.

```bash
# Build and run from source
docker build -t uberto/rest4sftp .
docker run -p 127.0.0.1:9990:8080/tcp uberto/rest4sftp --sftp

# Run from Docker Hub
docker pull uberto/rest4sftp
docker run -p 127.0.0.1:9990:8080/tcp uberto/rest4sftp --sftp
```

```yaml
version: "3"

services:
  rest4sftp:
    image: "uberto/rest4sftp"
    ports:
      - "9990:8080"
    command: --sftp
```

--------------------------------

### Download File via GET

Source: https://context7.com/uberto/rest4sftp/llms.txt

Retrieves a file from the remote SFTP server and outputs the content to stdout. Requires FTP connection details in the headers.

```bash
curl -X GET http://localhost:8080/file/Upload/config.txt \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"
```

--------------------------------

### Download File via HTTP (cURL)

Source: https://context7.com/uberto/rest4sftp/llms.txt

Demonstrates downloading a file from the remote server using the GET /file/{path} endpoint. The file content is returned as a binary stream, and connection details are passed via headers.

```bash
# Download a file from the remote server
curl -i -X GET http://localhost:8080/file/Upload/myfile.ext \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass" \
  -o downloaded_file.ext
```

--------------------------------

### GET /file/{path} - Download File

Source: https://context7.com/uberto/rest4sftp/llms.txt

Downloads a file from the remote server and returns it as a binary stream.

```APIDOC
## GET /file/{path}

### Description
Downloads a file from the remote server and returns it as a binary stream.

### Method
GET

### Endpoint
`/file/{path}`

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the file on the remote server.

#### Request Headers
- **FTP-Host** (string) - Required - The hostname or IP address of the FTP/SFTP server.
- **FTP-Port** (integer) - Required - The port number of the FTP/SFTP server.
- **FTP-User** (string) - Required - The username for authentication.
- **FTP-Password** (string) - Required - The password for authentication.

### Request Example
```bash
curl -i -X GET http://localhost:8080/file/Upload/myfile.ext \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass" \
  -o downloaded_file.ext
```

### Response
#### Success Response (200 OK)
- **Body** (binary) - The content of the requested file.

#### Response Example
```
<binary file contents>
```

#### Error Responses
- **401 Unauthorized** - Invalid credentials.
- **404 Not Found** - The specified file does not exist.
```

--------------------------------

### GET /file/Upload/{path} - Download File to stdout

Source: https://context7.com/uberto/rest4sftp/llms.txt

Downloads a file from the SFTP server and outputs its content to standard output. This is suitable for text files.

```APIDOC
## GET /file/Upload/{path}

### Description
Downloads a file from the SFTP server and outputs its content to standard output. This is suitable for text files.

### Method
GET

### Endpoint
`/file/Upload/{path}`

### Parameters
#### Query Parameters
- **FTP-Host** (string) - Required - The hostname or IP address of the SFTP server.
- **FTP-Port** (integer) - Required - The port number of the SFTP server.
- **FTP-User** (string) - Required - The username for SFTP authentication.
- **FTP-Password** (string) - Required - The password for SFTP authentication.

### Request Example
```bash
curl -X GET http://localhost:8080/file/Upload/config.txt \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"
```

### Response
#### Success Response (200)
- **Content** (string) - The content of the downloaded file.

#### Response Example
```
# Example content of config.txt
setting1=value1
setting2=value2
```

### Error Handling
- **401 Unauthorized** - Invalid credentials.
- **404 Not Found** - File does not exist.
```

--------------------------------

### GET /folder/{path}

Source: https://context7.com/uberto/rest4sftp/llms.txt

Lists the contents of a specific directory on the remote FTP/SFTP server. The connection details are provided via HTTP headers.

```APIDOC
## GET /folder/{path}

### Description
Retrieves a list of files and subfolders within the specified path on the remote server.

### Method
GET

### Endpoint
/folder/{path}

### Parameters
#### Path Parameters
- **path** (string) - Required - The directory path to list on the remote server.

#### Headers
- **FTP-Host** (string) - Required - The hostname or IP of the remote server.
- **FTP-Port** (integer) - Required - The connection port (e.g., 21 for FTP, 22 for SFTP).
- **FTP-User** (string) - Required - Authentication username.
- **FTP-Password** (string) - Required - Authentication password.

### Request Example
GET /folder/uploads
Headers: 
  FTP-Host: sftp.example.com
  FTP-Port: 22
  FTP-User: user
  FTP-Password: pass

### Response
#### Success Response (200)
- **folders** (array) - List of subfolder objects.
- **files** (array) - List of file objects.

#### Response Example
{
  "folders": [
    {"name": "archives", "date": "2024-01-15T10:00:00Z", "fullFolderPath": "upload"}
  ],
  "files": [
    {"name": "report.pdf", "date": "2024-01-15T14:30:00Z", "size": 102400, "folderPath": "upload"}
  ]
}
```

--------------------------------

### GET /file/{path/to/filename}

Source: https://github.com/uberto/rest4sftp/blob/master/README.md

Retrieves the contents of a specified file from an FTP or SFTP server.

```APIDOC
## GET /file/{path/to/filename}

### Description
Returns an `application/octet-stream` of the file's contents.

### Method
GET

### Endpoint
/file/{path/to/filename}

### Parameters
#### Path Parameters
- **path/to/filename** (string) - Required - The full path to the file, including its name.

#### Request Headers
- **FTP-Host** (string) - Required - The hostname or IP address of the remote FTP/SFTP server.
- **FTP-Port** (integer) - Optional - The port of the remote FTP/SFTP server (defaults to 21 for FTP, 22 for SFTP).
- **FTP-User** (string) - Required (if Authorization header is not used) - The username for the FTP/SFTP account.
- **FTP-Password** (string) - Required (if Authorization header is not used) - The password for the FTP/SFTP account.
- **Authorization** (string) - Required (if FTP-User and FTP-Password are not used) - A basic auth header (RFC7617) containing the FTP/SFTP account name and password.

### Response
#### Success Response (200)
- **file content** (binary) - The raw binary content of the file.

#### Error Response (401)
- **message** (string) - "Invalid FTP server credentials."

#### Error Response (404)
- **message** (string) - "File not found."
```

--------------------------------

### SimpleRemoteClient Interface for FTP/SFTP Operations (Kotlin)

Source: https://context7.com/uberto/rest4sftp/llms.txt

Defines the core interface for remote client operations like connecting, listing files, uploading, and downloading. It supports custom protocol implementations and is designed to be auto-closeable. Usage examples demonstrate both SFTP and FTP client interactions.

```kotlin
interface SimpleRemoteClient : AutoCloseable {
    // Connect to the remote server
    fun connect(): SimpleRemoteClient

    // Check connection status
    fun isConnected(): Boolean

    // List files and folders with optional filter
    fun listFiles(folderPath: String, filter: Filter): List<FileSystemElement>?

    // Create a new folder
    fun createFolder(folderPath: String): Boolean

    // Delete an empty folder
    fun deleteFolder(folderPath: String): Boolean

    // Retrieve file contents as byte array
    fun retrieveFile(folderPath: String, fileName: String): ByteArray?

    // Upload file from input stream
    fun uploadFile(folderPath: String, fileName: String, upload: InputStream): Boolean

    // Delete a file
    fun deleteFile(folderPath: String, fileName: String): Boolean

    // Rename a file
    fun renameFile(folderPath: String, oldFileName: String, newFileName: String): Boolean
}

// Usage example - SFTP client
val remoteHost = RemoteHost(
    host = "sftp.example.com",
    port = 22,
    userName = "user",
    password = "pass"
)
val timeout = Duration.ofSeconds(60)

SshJSftpClient(remoteHost, timeout).connect().use {
    client ->
    // List files
    val files = client.listFiles("/upload", Filter(null))
    files?.forEach {
        element ->
        when (element) {
            is FileInfo -> println("File: ${element.name}, Size: ${element.size}")
            is FolderInfo -> println("Folder: ${element.name}")
        }
    }

    // Upload a file
    val inputStream = File("local.txt").inputStream()
    val success = client.uploadFile("/upload", "remote.txt", inputStream)

    // Download a file
    val content = client.retrieveFile("/upload", "remote.txt")
    content?.let { File("downloaded.txt").writeBytes(it) }
}

// Usage example - FTP client
ApacheCommonsFtpClient(remoteHost.copy(port = 21), timeout)
    .withDebug()  // Enable protocol debug logging
    .connect()
    .use {
        client ->
        val files = client.listFiles("/pub", Filter("*.zip"))
        // Process files...
    }
```

--------------------------------

### GET /folder/{foldername}

Source: https://github.com/uberto/rest4sftp/blob/master/README.md

Retrieves a listing of the contents of a specified folder on an FTP or SFTP server.

```APIDOC
## GET /folder/{foldername}

### Description
Returns an `application/json; charset=utf8` representation of the remote folder's contents.

### Method
GET

### Endpoint
/folder/{foldername}

### Parameters
#### Path Parameters
- **foldername** (string) - Required - The name of the folder to list.

#### Request Headers
- **FTP-Host** (string) - Required - The hostname or IP address of the remote FTP/SFTP server.
- **FTP-Port** (integer) - Optional - The port of the remote FTP/SFTP server (defaults to 21 for FTP, 22 for SFTP).
- **FTP-User** (string) - Required (if Authorization header is not used) - The username for the FTP/SFTP account.
- **FTP-Password** (string) - Required (if Authorization header is not used) - The password for the FTP/SFTP account.
- **Authorization** (string) - Required (if FTP-User and FTP-Password are not used) - A basic auth header (RFC7617) containing the FTP/SFTP account name and password.

### Response
#### Success Response (200)
- **contents** (array) - An array of objects, where each object represents a file or directory within the folder.
  - **name** (string) - The name of the file or directory.
  - **type** (string) - The type of the item ('FILE' or 'DIRECTORY').
  - **size** (integer) - The size of the file in bytes (0 for directories).
  - **lastModified** (integer) - The last modified timestamp of the item (Unix epoch milliseconds).

#### Error Response (401)
- **message** (string) - "Invalid FTP server credentials."

#### Error Response (404)
- **message** (string) - "Folder not found."
```

--------------------------------

### List Folder Contents via HTTP (cURL)

Source: https://context7.com/uberto/rest4sftp/llms.txt

Demonstrates how to list the contents of a remote folder using the GET /folder/{path} endpoint. It shows how to specify connection details (host, port, user, password) via headers and how to filter results by filename using glob patterns.

```bash
# List contents of the "Upload" directory
curl -i -X GET http://localhost:8080/folder/Upload \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"

# List with filename filter using wildcard pattern
curl -i -X GET "http://localhost:8080/folder/Upload?name=*.pdf" \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"
```

--------------------------------

### Perform FTP Operations via REST API

Source: https://github.com/uberto/rest4sftp/blob/master/README.md

Examples of using curl to interact with remote FTP servers through the rest4sftp bridge. These commands demonstrate listing folder contents, uploading files, and downloading files.

```bash
curl -i -X GET http://localhost:8080/folder/Upload -H "FTP-Host:ftp.myserver.com" -H "FTP-Port:22" -H "FTP-User:johnsmith" -H "FTP-Password:****"
curl -i -X PUT --data-binary @myfile.ext http://localhost:8080/file/Upload/myfile.ext -H "FTP-Host:ftp.myserver.com" -H "FTP-Port:22" -H "FTP-User:johnsmith" -H "FTP-Password:****"
curl -i -X GET http://localhost:8080/file/Upload/myfile.ext -H "FTP-Host:ftp.myserver.com" -H "FTP-Port:22" -H "FTP-User:johnsmith" -H "FTP-Password:****" -o downloaded.zip
```

--------------------------------

### CommandHandler for REST API Operations (Kotlin)

Source: https://context7.com/uberto/rest4sftp/llms.txt

Implements the command pattern to process REST API operations by translating them into remote client calls. It utilizes a factory for creating specific remote clients (SFTP or FTP) and handles various file system commands. An example demonstrates programmatic usage with an SFTP client.

```kotlin
// Command types for all supported operations
sealed class Command

data class RetrieveFolder(val path: String, val filter: Filter) : Command()
data class CreateFolder(val path: String) : Command()
data class DeleteFolder(val path: String) : Command()
data class RetrieveFile(val path: String, val fileName: String) : Command()
data class UploadFile(val path: String, val fileName: String, val inputStream: InputStream) : Command()
data class DeleteFile(val path: String, val fileName: String) : Command()

// CommandHandler processes commands using a factory for creating remote clients
typealias SimpleFtpClientFactory = (RemoteHost) -> SimpleRemoteClient

class CommandHandler(internal val ftpClientFactory: SimpleFtpClientFactory) {
    fun handle(remoteHost: RemoteHost, cmd: Command): HttpResult
}

// Creating a CommandHandler with SFTP support
val handler = CommandHandler { remoteHost ->
    SshJSftpClient(remoteHost, Duration.ofSeconds(60))
}

// Creating a CommandHandler with FTP support
val ftpHandler = CommandHandler { remoteHost ->
    ApacheCommonsFtpClient(remoteHost, Duration.ofSeconds(60))
}

// Example: Programmatic usage
val remoteHost = RemoteHost("ftp.example.com", 22, "user", "pass")
val result = handler.handle(remoteHost, RetrieveFolder("/upload", Filter("*.txt")))
when (result.status) {
    Status.OK -> println("Success: ${result.responseBody}")
    Status.NOT_FOUND -> println("Folder not found")
    else -> println("Error: ${result.status}")
}
```

--------------------------------

### GET /folder/{path} - List Folder Contents

Source: https://context7.com/uberto/rest4sftp/llms.txt

Retrieves the contents of a remote folder as JSON, returning both files and subfolders with metadata. Supports filtering by filename using glob patterns.

```APIDOC
## GET /folder/{path}

### Description
Retrieves the contents of a remote folder as JSON, returning both files and subfolders with metadata including name, date, and size. Supports filtering by filename using glob patterns.

### Method
GET

### Endpoint
`/folder/{path}`

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the folder on the remote server.

#### Query Parameters
- **name** (string) - Optional - A glob pattern to filter files by name (e.g., `*.pdf`, `report*`).

#### Request Headers
- **FTP-Host** (string) - Required - The hostname or IP address of the FTP/SFTP server.
- **FTP-Port** (integer) - Required - The port number of the FTP/SFTP server.
- **FTP-User** (string) - Required - The username for authentication.
- **FTP-Password** (string) - Required - The password for authentication.

### Request Example
```bash
curl -i -X GET http://localhost:8080/folder/Upload?name=*.pdf \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"
```

### Response
#### Success Response (200 OK)
- **folders** (array) - List of subfolders with their metadata.
  - **name** (string) - Name of the subfolder.
  - **date** (string) - Last modified date of the subfolder (ISO 8601 format).
  - **fullFolderPath** (string) - Full path to the subfolder.
- **files** (array) - List of files with their metadata.
  - **name** (string) - Name of the file.
  - **date** (string) - Last modified date of the file (ISO 8601 format).
  - **size** (integer) - Size of the file in bytes.
  - **folderPath** (string) - Path to the folder containing the file.

#### Response Example
```json
{
  "folders": [
    {
      "name": "subdir1",
      "date": "2024-01-15T10:30:00Z",
      "fullFolderPath": "Upload"
    }
  ],
  "files": [
    {
      "name": "document.pdf",
      "date": "2024-01-15T14:22:00Z",
      "size": 1048576,
      "folderPath": "Upload"
    }
  ]
}
```

#### Error Responses
- **401 Unauthorized** - Invalid credentials or missing required headers.
- **404 Not Found** - The specified folder does not exist.
```

--------------------------------

### Build and Run rest4sftp from Source

Source: https://github.com/uberto/rest4sftp/blob/master/README.md

Instructions to clone, build, and execute the rest4sftp service using Gradle. This process creates a distribution zip file and runs the server on a specified port.

```bash
git clone https://github.com/uberto/rest4sftp.git
./gradlew clean build
cd build/distributions
unzip rest4sftp-<version>.zip
rest4sftp-<version>/bin/rest4sftp --sftp --port 8080
```

--------------------------------

### Deploy rest4sftp with Docker

Source: https://github.com/uberto/rest4sftp/blob/master/README.md

Methods for running the rest4sftp service using Docker. Includes building from source or pulling the latest image from Docker Hub.

```bash
docker build -t uberto/rest4sftp .
docker run -p 127.0.0.1:9990:8080/tcp uberto/rest4sftp --sftp
docker pull uberto/rest4sftp
docker run -p 127.0.0.1:9990:8080/tcp uberto/rest4sftp --sftp
```

--------------------------------

### Create Folder via HTTP (cURL)

Source: https://context7.com/uberto/rest4sftp/llms.txt

Shows how to create a new folder on the remote server using the PUT /folder/{path} endpoint. It requires specifying FTP/SFTP connection details through request headers.

```bash
# Create a new folder named "Reports" inside "Upload"
curl -i -X PUT http://localhost:8080/folder/Upload/Reports \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"
```

--------------------------------

### Authenticate via Basic Auth

Source: https://context7.com/uberto/rest4sftp/llms.txt

Demonstrates how to authenticate using standard HTTP Basic Authentication headers instead of custom FTP headers. Supports both manual base64 encoding and curl's built-in auth flag.

```bash
curl -i -X GET http://localhost:8080/folder/Upload \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "Authorization: Basic am9obnNtaXRoOnNlY3JldHBhc3M="

curl -i -X GET http://localhost:8080/folder/Upload \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -u "johnsmith:secretpass"
```

--------------------------------

### Configure rest4sftp with Docker Compose

Source: https://github.com/uberto/rest4sftp/blob/master/README.md

Configuration file and execution command for deploying rest4sftp using docker-compose.

```yaml
version: 3

services:
  rest4sftp:
    image: "uberto/rest4sftp"
    port: 9990:8080
    command: --sftp
```

```bash
cd <to directory where docker-compose.yml was created>
docker compose up
```

--------------------------------

### PUT /folder/{path} - Create Folder

Source: https://context7.com/uberto/rest4sftp/llms.txt

Creates a new folder at the specified path on the remote server.

```APIDOC
## PUT /folder/{path}

### Description
Creates a new folder at the specified path on the remote server.

### Method
PUT

### Endpoint
`/folder/{path}`

### Parameters
#### Path Parameters
- **path** (string) - Required - The full path where the new folder should be created on the remote server.

#### Request Headers
- **FTP-Host** (string) - Required - The hostname or IP address of the FTP/SFTP server.
- **FTP-Port** (integer) - Required - The port number of the FTP/SFTP server.
- **FTP-User** (string) - Required - The username for authentication.
- **FTP-Password** (string) - Required - The password for authentication.

### Request Example
```bash
curl -i -X PUT http://localhost:8080/folder/Upload/Reports \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"
```

### Response
#### Success Response (200 OK)
- **Body** (string) - Confirmation message indicating the folder was created.

#### Response Example
```
created folder: Upload/Reports
```

#### Error Responses
- **401 Unauthorized** - Invalid credentials.
- **404 Not Found** - The parent path does not exist or the folder cannot be created.
```

--------------------------------

### Authentication Methods

Source: https://context7.com/uberto/rest4sftp/llms.txt

Details on how to authenticate with the REST4SFTP API, including custom FTP headers and standard Basic Auth.

```APIDOC
## Authentication

### Description
Provides details on the supported authentication methods for the REST4SFTP API.

### Methods

#### 1. Custom FTP Headers
This method uses specific headers to pass SFTP credentials.

- **FTP-Host** (string) - Required - The hostname or IP address of the SFTP server.
- **FTP-Port** (integer) - Required - The port number of the SFTP server.
- **FTP-User** (string) - Required - The username for SFTP authentication.
- **FTP-Password** (string) - Required - The password for SFTP authentication.

**Example:**
```bash
curl -X GET http://localhost:8080/file/Upload/config.txt \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"
```

#### 2. Basic Authentication Header
This method uses the standard HTTP `Authorization` header with Basic authentication.

**Steps:**
1. Encode your username and password using Base64 (e.g., `echo -n "username:password" | base64`).
2. Include the encoded string in the `Authorization` header as `Basic <encoded_string>`.

**Example using manual encoding:**
```bash
# Encode credentials: echo -n "johnsmith:secretpass" | base64
# Result: am9obnNtaXRoOnNlY3JldHBhc3M=

curl -i -X GET http://localhost:8080/folder/Upload \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "Authorization: Basic am9obnNtaXRoOnNlY3JldHBhc3M="
```

**Example using curl's built-in Basic Auth support:**
```bash
curl -i -X GET http://localhost:8080/folder/Upload \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -u "johnsmith:secretpass"
```

**Note:** The `FTP-Host` and `FTP-Port` headers are always required, regardless of the authentication method used.
```

--------------------------------

### Upload File via PUT

Source: https://context7.com/uberto/rest4sftp/llms.txt

Uploads a file to the remote server, supporting local files, stdin streams, and large binary files. The operation is atomic using a temporary file strategy.

```bash
curl -i -X PUT --data-binary @localfile.pdf \
  http://localhost:8080/file/Upload/remotefile.pdf \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"

echo "Hello World" | curl -X PUT --data-binary @- \
  http://localhost:8080/file/Upload/hello.txt \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"

curl -X PUT --data-binary @backup.zip \
  http://localhost:8080/file/Backups/backup-2024-01-15.zip \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"
```

--------------------------------

### PUT /file/{path/to/filename}

Source: https://github.com/uberto/rest4sftp/blob/master/README.md

Uploads a file to a specified location on an FTP or SFTP server. Overwrites the file if it already exists.

```APIDOC
## PUT /file/{path/to/filename}

### Description
Uploads a file to a specified location on an FTP or SFTP server. The file contents are specified as raw data in the request body. If the file already exists in the remote server, it will be overwritten.

### Method
PUT

### Endpoint
/file/{path/to/filename}

### Parameters
#### Path Parameters
- **path/to/filename** (string) - Required - The full path where the file should be uploaded, including its name.

#### Request Body
- **file content** (binary) - Required - The raw binary content of the file to upload.

#### Request Headers
- **FTP-Host** (string) - Required - The hostname or IP address of the remote FTP/SFTP server.
- **FTP-Port** (integer) - Optional - The port of the remote FTP/SFTP server (defaults to 21 for FTP, 22 for SFTP).
- **FTP-User** (string) - Required (if Authorization header is not used) - The username for the FTP/SFTP account.
- **FTP-Password** (string) - Required (if Authorization header is not used) - The password for the FTP/SFTP account.
- **Authorization** (string) - Required (if FTP-User and FTP-Password are not used) - A basic auth header (RFC7617) containing the FTP/SFTP account name and password.

### Response
#### Success Response (200)
- **message** (string) - "File uploaded successfully."

#### Error Response (400)
- **message** (string) - "Problem with file contents or file path."

#### Error Response (401)
- **message** (string) - "Invalid FTP server credentials."
```

--------------------------------

### Define Data Models for File Operations

Source: https://context7.com/uberto/rest4sftp/llms.txt

Outlines the core Kotlin data classes used to represent remote hosts, file system elements, and folder listing responses within the rest4sftp framework.

```kotlin
data class RemoteHost(val host: String, val port: Int, val userName: String, val password: String)

sealed class FileSystemElement : FileMetaInfo

data class FileInfo(override val name: String, override val date: Instant, val size: Long, val folderPath: String) : FileSystemElement()

data class FolderInfo(override val name: String, override val date: Instant, val fullFolderPath: String) : FileSystemElement()

class FolderResponse(val folders: List<FolderInfo>, val files: List<FileInfo>)

class Filter(val pattern: String?) {
    fun accept(fileInfo: FileSystemElement): Boolean
}
```

--------------------------------

### Delete Folder via HTTP (cURL)

Source: https://context7.com/uberto/rest4sftp/llms.txt

Illustrates how to delete an empty folder on the remote server using the DELETE /folder/{path} endpoint. Connection details must be provided in the request headers.

```bash
# Delete the "OldReports" folder
curl -i -X DELETE http://localhost:8080/folder/Upload/OldReports \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"
```

--------------------------------

### PUT /file/{path} - Upload File

Source: https://context7.com/uberto/rest4sftp/llms.txt

Uploads a file to the remote SFTP server. If the file already exists, it will be overwritten atomically using a temporary file strategy.

```APIDOC
## PUT /file/{path}

### Description
Uploads a file to the remote SFTP server. If the file already exists, it will be overwritten atomically using a temporary file strategy.

### Method
PUT

### Endpoint
`/file/{path}`

### Parameters
#### Path Parameters
- **path** (string) - Required - The destination path on the SFTP server where the file will be uploaded.

#### Query Parameters
- **FTP-Host** (string) - Required - The hostname or IP address of the SFTP server.
- **FTP-Port** (integer) - Required - The port number of the SFTP server.
- **FTP-User** (string) - Required - The username for SFTP authentication.
- **FTP-Password** (string) - Required - The password for SFTP authentication.

#### Request Body
- **file content** (binary) - Required - The binary content of the file to upload. Can be provided via `--data-binary @localfile.ext` or piped via stdin (`--data-binary @-`).

### Request Example
```bash
# Upload a file to the remote server
curl -i -X PUT --data-binary @localfile.pdf \
  http://localhost:8080/file/Upload/remotefile.pdf \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"

# Upload with content from stdin
echo "Hello World" | curl -X PUT --data-binary @- \
  http://localhost:8080/file/Upload/hello.txt \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"

# Upload large binary file
curl -X PUT --data-binary @backup.zip \
  http://localhost:8080/file/Backups/backup-2024-01-15.zip \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message, typically indicating the uploaded file path.

#### Response Example
```
uploaded: Upload/remotefile.pdf
```

### Error Handling
- **400 Bad Request** - Problem with file contents or path.
- **401 Unauthorized** - Invalid credentials.
```

--------------------------------

### DELETE /folder/{path} - Delete Folder

Source: https://context7.com/uberto/rest4sftp/llms.txt

Deletes an empty folder at the specified path on the remote server.

```APIDOC
## DELETE /folder/{path}

### Description
Deletes an empty folder at the specified path on the remote server.

### Method
DELETE

### Endpoint
`/folder/{path}`

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the folder to be deleted on the remote server.

#### Request Headers
- **FTP-Host** (string) - Required - The hostname or IP address of the FTP/SFTP server.
- **FTP-Port** (integer) - Required - The port number of the FTP/SFTP server.
- **FTP-User** (string) - Required - The username for authentication.
- **FTP-Password** (string) - Required - The password for authentication.

### Request Example
```bash
curl -i -X DELETE http://localhost:8080/folder/Upload/OldReports \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"
```

### Response
#### Success Response (200 OK)
- **Body** (string) - Confirmation message indicating the folder was deleted.

#### Response Example
```
deleted folder: Upload/OldReports
```

#### Error Responses
- **401 Unauthorized** - Invalid credentials.
- **404 Not Found** - The folder does not exist or cannot be deleted (e.g., it is not empty).
```

--------------------------------

### DELETE /file/{path/to/filename}

Source: https://github.com/uberto/rest4sftp/blob/master/README.md

Deletes a specified file from an FTP or SFTP server.

```APIDOC
## DELETE /file/{path/to/filename}

### Description
Deletes a specified file from an FTP or SFTP server.

### Method
DELETE

### Endpoint
/file/{path/to/filename}

### Parameters
#### Path Parameters
- **path/to/filename** (string) - Required - The full path to the file to be deleted, including its name.

#### Request Headers
- **FTP-Host** (string) - Required - The hostname or IP address of the remote FTP/SFTP server.
- **FTP-Port** (integer) - Optional - The port of the remote FTP/SFTP server (defaults to 21 for FTP, 22 for SFTP).
- **FTP-User** (string) - Required (if Authorization header is not used) - The username for the FTP/SFTP account.
- **FTP-Password** (string) - Required (if Authorization header is not used) - The password for the FTP/SFTP account.
- **Authorization** (string) - Required (if FTP-User and FTP-Password are not used) - A basic auth header (RFC7617) containing the FTP/SFTP account name and password.

### Response
#### Success Response (200)
- **message** (string) - "File deleted successfully."

#### Error Response (400)
- **message** (string) - "Problem with file contents or file path."

#### Error Response (401)
- **message** (string) - "Invalid FTP server credentials."
```

--------------------------------

### DELETE /file/{path} - Delete File

Source: https://context7.com/uberto/rest4sftp/llms.txt

Deletes a specified file from the remote SFTP server.

```APIDOC
## DELETE /file/{path}

### Description
Deletes a specified file from the remote SFTP server.

### Method
DELETE

### Endpoint
`/file/{path}`

### Parameters
#### Path Parameters
- **path** (string) - Required - The path of the file to delete on the SFTP server.

#### Query Parameters
- **FTP-Host** (string) - Required - The hostname or IP address of the SFTP server.
- **FTP-Port** (integer) - Required - The port number of the SFTP server.
- **FTP-User** (string) - Required - The username for SFTP authentication.
- **FTP-Password** (string) - Required - The password for SFTP authentication.

### Request Example
```bash
# Delete a file from the remote server
curl -i -X DELETE http://localhost:8080/file/Upload/oldfile.txt \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message, typically indicating the deleted file path.

#### Response Example
```
deleted: Upload/oldfile.txt
```

### Error Handling
- **400 Bad Request** - Problem with file path.
- **401 Unauthorized** - Invalid credentials.
- **404 Not Found** - File does not exist.
```

--------------------------------

### Delete File via DELETE

Source: https://context7.com/uberto/rest4sftp/llms.txt

Removes a specified file from the remote SFTP server. Returns a confirmation message upon successful deletion.

```bash
curl -i -X DELETE http://localhost:8080/file/Upload/oldfile.txt \
  -H "FTP-Host:ftp.myserver.com" \
  -H "FTP-Port:22" \
  -H "FTP-User:johnsmith" \
  -H "FTP-Password:secretpass"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.