remote-fs 0.1.2

Unified async file operations over SMB, FTP, and SFTP
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

# remote-fs

统一的远程文件系统抽象，一套 API 覆盖 **SMB / FTP / SFTP**。

基于 Tokio 异步运行时，按 Cargo feature 按需启用协议后端。

## 特性

| Feature | 默认 | 后端 |
|---------|:----:|------|
| `smb` | — | [`smb2`](https://crates.io/crates/smb2) |
| `ftp` | — | [`async-ftp`](https://crates.io/crates/async-ftp) |
| `sftp` | — | [`async-ssh2-tokio`](https://crates.io/crates/async-ssh2-tokio) + [`russh-sftp`](https://crates.io/crates/russh-sftp) |
| `full` | — | 同时启用以上全部协议 |

## 安装

```toml
# 按需启用协议
remote-fs = { version = "0.1", features = ["ftp"] }

# 或一次全开
remote-fs = { version = "0.1", features = ["full"] }
```

## 快速开始

三套协议共用同一套 `RemoteFileSystem` 接口：

```rust
use remote_fs::{Client, FtpConfig, RemoteFileSystem};

#[tokio::main]
async fn main() -> remote_fs::Result<()> {
    let mut client = Client::ftp(&FtpConfig::new("ftp.example.com", "user", "pass")).await?;

    let entries = client.list("/").await?;
    for entry in &entries {
        println!("{}  {} bytes", entry.name, entry.size);
    }

    client.write("/hello.txt", b"hello").await?;
    client.download("/hello.txt", std::path::Path::new("./hello.txt")).await?;
    client.disconnect().await?;
    Ok(())
}
```

### SMB

```rust
use remote_fs::{Client, SmbConfig};

# async fn demo() -> remote_fs::Result<()> {
let cfg = SmbConfig::new("192.168.1.10", "Documents", "user", "pass")
    .workgroup("WORKGROUP");
let mut client = Client::smb(&cfg).await?;
# let _ = client;
# Ok(())
# }
```

### SFTP

```rust
use remote_fs::{Client, SftpConfig};

# async fn demo() -> remote_fs::Result<()> {
// 密码认证
let mut client = Client::sftp(
    &SftpConfig::with_password("host", "user", "pass"),
).await?;

// 或私钥认证
let mut client = Client::sftp(
    &SftpConfig::with_key("host", "user", "/path/to/id_rsa"),
).await?;
# let _ = client;
# Ok(())
# }
```

### Builder

```rust
use remote_fs::{ClientBuilder, SftpConfig};

# async fn demo() -> remote_fs::Result<()> {
let client = ClientBuilder::new()
    .sftp(SftpConfig::with_password("host", "user", "pass"))
    .build()
    .await?;
# let _ = client;
# Ok(())
# }
```

## API

所有后端共享 [`RemoteFileSystem`](src/traits.rs) trait：

| 方法 | 说明 |
|------|------|
| `connect` / `disconnect` | 连接生命周期 |
| `is_connected` | 连接状态 |
| `list` / `metadata` / `exists` | 路径查询 |
| `mkdir` / `mkdir_all` / `rmdir` | 目录操作 |
| `remove_file` / `remove` / `rename` | 文件变更 |
| `read` / `write` | 内存读写 |
| `download` / `upload` | 本地 ↔ 远程传输 |

## 运行测试

```powershell
# 仅跑不依赖协议后端的测试
cargo test

# 跑全部协议相关集成测试
cargo test --features full

# 只跑某一协议
cargo test --features ftp --test ftp_offline
```