# remotefs
Changelog
·
Get started
·
Documentation
~ The Omni Filetransfer Client Library (and more!) ~
Developed by @veeso
Current version: 0.3.1 (22/10/2024)
---
## About remotefs ☁️
remotefs is a library that provides a file system structure to work with all the most popular file transfer protocols.
This is achieved through a trait called `RemoteFs` which exposes methods to operate on the remote file system.
Currently the library exposes a client for **Sftp**, **Scp**, **Kube**, **Ftp**, **WebDAV** and **Aws-s3** as external libraries.
### Why remotefs ❓
You might be wondering, "why remotefs?"
The first and foremost reason is to provide a generic interface over multiple protocols.
For example, in [termscp](https://github.com/veeso/termscp) it allows the support of multiple protocols without any protocol-specific code.
The second reason is that often, users just want a simple way to operate on a remote file system, however, they don't have the time to spend researching the ins and outs of each protocol.
Using remotefs, this is no longer a problem: all you need is to configure the options to your liking, then you're ready to connect.
---
## Features 🎁
- 📁 Different communication protocols
- **Aws S3**
- **FTP** and **FTPS**
- **SFTP**
- **SCP**
- **SMB**
- ✔️ Configurable: use only the client that you need
- 🤖 Extensible: adding new protocols is easy
- 🚀 Simple: easy to setup
- 😄 Understandable: no need to understand the underlying protocol
---
## Get started 🚀
First, add `remotefs` to your list of dependencies:
```toml
remotefs = "^0.3.0"
```
select over a variety of features:
- `find`: enable the `find()` method on `RemoteFs` trait (_enabled by default_)
- `no-log`: disable logging. By default, the `log` crate is used.
### Client libraries 🔌
To use an existing client, you must add them to your `Cargo.toml`, along with remotefs:
- [aws-s3](https://github.com/remotefs-rs/remotefs-rs-aws-s3)
```toml
remotefs-aws-s3 = "^0.3.0"
```
- [ftp](https://github.com/remotefs-rs/remotefs-rs-ftp)
```toml
remotefs-ftp = { version = "^0.3.0", features = [ "secure" ] }
```
- [kube](https://github.com/remotefs-rs/remotefs-rs-kube)
```toml
remotefs-kube = "^0.3.0"
```
- [smb](https://github.com/remotefs-rs/remotefs-rs-smb)
```toml
remotefs-smb = "^0.3.0"
```
- [ssh](https://github.com/remotefs-rs/remotefs-rs-ssh)
```toml
remotefs-ssh = "^0.4.0"
```
- [webdav](https://github.com/remotefs-rs/remotefs-rs-webdav)
```toml
remotefs-webdav = "^0.2.0"
```
---
## Remote file system 💾
As mentioned earlier, this library exposes a trait called `RemoteFs`.
This trait exposes several methods to operate on a remote file system via the chosen client.
Let's briefly go over which methods are available:
- **connect**: connect to the remote host.
- **disconnect**: disconnect from the remote host.
- **is_connected**: returns whether the client is connected to the remote host.
- **append_file**: append specified buffer to the specified file.
- **append**: open a file for append and returns a stream to write to it.
- **change_dir**: change the working directory to provided path.
- **copy**: copy a file from the specified source path to the specified destination.
- **create_dir**: create a directory with the specified file mode at the specified path.
- **create_file**: create a file at a specified path with the specified content.
- **create**: create a file and returns a stream to write to it.
- **exec**: executes a shell command.
- **exists**: checks whether file at specified path exists.
- **list_dir**: get entries at the provided path.
- **mov**: move a file from the specified source path to the specified destination.
- **open_file**: open a file for reading and fill the specified buffer with the file content.
- **open**: open a file and returns a stream to read it.
- **pwd**: get working directory.
- **remove_dir_all**: remove file/directory and all of its content.
- **remove_dir**: remove directory at the specified path. It fails if it is not an empty directory.
- **remove_file**: remove file at the specified path. It fails if it is not a file.
- **setstat**: set file metadata for file at the specified path.
- **stat**: get file information of file at the specified path.
- **symlink**: create a symlink at the specified path, pointing to the specified file.
### Client compatibility table ✔️
The following table states the compatibility for each client associated with the remote file system trait method.
Note: `connect()`, `disconnect()` and `is_connected()` **MUST** always be supported, and are so omitted in the table.
| Client/Method | Aws-S3 | Ftp | Kube | Scp | Sftp | Smb | WebDAV |
| -------------- | ------ | --- |------| --- | ---- |-----| ------ |
| append_file | No | Yes | No | No | Yes | Yes | No |
| append | No | Yes | No | No | Yes | No | No |
| change_dir | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| copy | No | No | Yes | Yes | Yes | No | No |
| create_dir | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| create_file | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| create | No | Yes | No | Yes | Yes | No | No |
| exec | No | No | Yes | Yes | Yes | No | No |
| exists | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| list_dir | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| mov | No | Yes | Yes | Yes | Yes | Yes | Yes |
| open_file | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| open | No | Yes | No | Yes | Yes | No | No |
| pwd | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| remove_dir_all | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| remove_dir | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| remove_file | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| setstat | No | No | Yes | Yes | Yes | No | No |
| stat | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| symlink | No | No | Yes | Yes | Yes | Yes | No |
---
## Support the developer ☕
If you like remotefs and you're grateful for the work I've done, please consider a little donation 🥳
You can make a donation on the following platforms:
[](https://ko-fi.com/veeso)
[](https://www.paypal.me/chrisintin)
---
## Apps using remotefs 🚀
- [termscp](https://github.com/veeso/termscp)
---
## Contributing and issues 🤝🏻
Contributions, bug reports, new features, and questions are welcome! 😉
If you have any questions or concerns, or you want to suggest a new feature, or you want just want to improve remotefs, feel free to open an issue or leave a pull request.
Please follow [our contributing guidelines](CONTRIBUTING.md)
---
## Changelog ⏳
View remotefs` changelog [HERE](CHANGELOG.md)
---
## License 📃
remotefs is licensed under the MIT license.
You can read the entire license [HERE](LICENSE)