# FileSystem

## FileSystem

File system operations facade for a specific Sandbox.

Provides methods for directory management, file upload/download, metadata inspection, and
search/replace operations.

### Methods

#### createFolder()
```java
public void createFolder(String path, String mode)
```

Creates a directory in the Sandbox.

**Parameters**:

- `path` _String_ - directory path
- `mode` _String_ - POSIX mode (for example `755`); defaults to `755` when `null`

**Throws**:

- `io.daytona.sdk.exception.DaytonaException` - if creation fails

#### deleteFile()
```java
public void deleteFile(String path)
```

Deletes a file.

**Parameters**:

- `path` _String_ - file path to delete

**Throws**:

- `io.daytona.sdk.exception.DaytonaException` - if deletion fails

#### downloadFile()
```java
public byte[] downloadFile(String remotePath)
```

Downloads a file into memory.

**Parameters**:

- `remotePath` _String_ - source file path in the Sandbox

**Returns**:

- `byte[]` - file bytes; empty array when no file payload is returned

**Throws**:

- `io.daytona.sdk.exception.DaytonaException` - if download or local read fails

#### downloadFileStream()
```java
public InputStream downloadFileStream(String remotePath) throws io.daytona.sdk.exception.DaytonaException
```

Downloads a single file from the Sandbox as a stream without buffering the entire file
into memory. The returned `InputStream` can be piped directly to an HTTP response,
written to a file, or processed on the fly.

The caller is responsible for closing the returned stream.

**Parameters**:

- `remotePath` _String_ - source file path in the Sandbox

**Returns**:

- `InputStream` - an `InputStream` streaming the file content

**Throws**:

- `io.daytona.sdk.exception.DaytonaException` - if the file does not exist or access is denied

#### downloadFileStream()
```java
public InputStream downloadFileStream(String remotePath, int timeoutSeconds) throws io.daytona.sdk.exception.DaytonaException
```

Downloads a single file from the Sandbox as a stream without buffering the entire file
into memory, with a custom timeout.

The caller is responsible for closing the returned stream.

**Parameters**:

- `remotePath` _String_ - source file path in the Sandbox
- `timeoutSeconds` _int_ - timeout in seconds; 0 means no timeout

**Returns**:

- `InputStream` - an `InputStream` streaming the file content

**Throws**:

- `io.daytona.sdk.exception.DaytonaException` - if the file does not exist or access is denied

#### downloadFileStream()
```java
public InputStream downloadFileStream(String remotePath, DownloadStreamOptions options) throws io.daytona.sdk.exception.DaytonaException
```

Downloads a single file from the Sandbox as a stream with configurable options.

**Parameters**:

- `remotePath` _String_ - source file path in the Sandbox
- `options` _DownloadStreamOptions_ - download options including timeout and progress callback

**Returns**:

- `InputStream` - an InputStream streaming the file content

**Throws**:

- `io.daytona.sdk.exception.DaytonaException` - if download fails

#### uploadFile()
```java
public void uploadFile(byte[] content, String remotePath)
```

Uploads in-memory file content to a Sandbox path.

**Parameters**:

- `content` _byte[]_ - file bytes; `null` uploads an empty file
- `remotePath` _String_ - destination file path in the Sandbox

**Throws**:

- `io.daytona.sdk.exception.DaytonaException` - if upload fails

#### uploadFileStream()
```java
public void uploadFileStream(InputStream source, String remotePath, UploadStreamOptions options)
```

Streams an upload to a Sandbox path without buffering the source. The bytes are
piped through a progress-counting wrapper directly into a streaming multipart
request, so heap usage stays flat regardless of source size.

**Parameters**:

- `source` _InputStream_ - the data source; the caller retains ownership and is responsible for closing it
- `remotePath` _String_ - destination file path in the Sandbox
- `options` _UploadStreamOptions_ - upload options including timeout, cancellation, and progress callback

**Throws**:

- `io.daytona.sdk.exception.DaytonaException` - if upload fails

#### uploadFileStream()
```java
public void uploadFileStream(InputStream source, String remotePath)
```

Convenience overload using default options.

**Parameters**:

- `source` _InputStream_ -
- `remotePath` _String_ -

#### listFiles()
```java
public List<FileInfo> listFiles(String path)
```

Lists files and directories under a path.

**Parameters**:

- `path` _String_ - directory path

**Returns**:

- `List\<FileInfo\>` - file metadata entries

**Throws**:

- `io.daytona.sdk.exception.DaytonaException` - if listing fails

#### listFiles()
```java
public List<FileInfo> listFiles(String path, Integer depth)
```

Lists files and directories under a path, optionally recursing into subdirectories.

**Parameters**:

- `path` _String_ - directory path
- `depth` _Integer_ - how many levels deep to list: depth=1 (default) lists the directory's entries, depth=2 also includes their children, and so on; must be >= 1. Each returned entry carries a full path field.

**Returns**:

- `List\<FileInfo\>` - file metadata entries

**Throws**:

- `io.daytona.sdk.exception.DaytonaException` - if listing fails

#### getFileDetails()
```java
public FileInfo getFileDetails(String path)
```

Returns metadata for a single file or directory.

**Parameters**:

- `path` _String_ - file or directory path

**Returns**:

- `FileInfo` - metadata record

**Throws**:

- `io.daytona.sdk.exception.DaytonaException` - if lookup fails

#### findFiles()
```java
public List<Map<String, Object>> findFiles(String path, String pattern)
```

Searches files by content pattern.

**Parameters**:

- `path` _String_ - root directory to search
- `pattern` _String_ - text pattern to find

**Returns**:

- `List\<Map\<String, Object\>\>` - list of matches containing file, line, and content

**Throws**:

- `io.daytona.sdk.exception.DaytonaException` - if the search request fails

#### searchFiles()
```java
public Map<String, Object> searchFiles(String path, String pattern)
```

Searches files by file-name pattern.

**Parameters**:

- `path` _String_ - root directory to search
- `pattern` _String_ - file-name pattern

**Returns**:

- `Map\<String, Object\>` - result map containing `files`

**Throws**:

- `io.daytona.sdk.exception.DaytonaException` - if the search request fails

#### replaceInFiles()
```java
public void replaceInFiles(List<String> files, String pattern, String newValue)
```

Performs in-place replacement in multiple files.

**Parameters**:

- `files` _List\<String\>_ - files to process
- `pattern` _String_ - pattern to replace
- `newValue` _String_ - replacement text

**Throws**:

- `io.daytona.sdk.exception.DaytonaException` - if replacement fails

#### moveFiles()
```java
public void moveFiles(String source, String destination)
```

Moves or renames a file or directory.

**Parameters**:

- `source` _String_ - source path
- `destination` _String_ - destination path

**Throws**:

- `io.daytona.sdk.exception.DaytonaException` - if move fails