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
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
//! Symlink and junction operations for `VirtualPath`.
//!
//! All link operations delegate to the inner `StrictPath`, which enforces boundary checks.
//! The virtual-path view is preserved across link creation.
use super::VirtualPath;
use std::path::Path;
impl<Marker> VirtualPath<Marker> {
/// Create a symlink at `link_path` pointing to this virtual path (same virtual root required).
///
/// Both `self` (target) and `link_path` must be `VirtualPath` instances created via `virtual_join()`,
/// which ensures all paths are clamped to the virtual root. Absolute paths like `"/etc/config"`
/// passed to `virtual_join()` are automatically clamped to `vroot/etc/config`, ensuring symlinks
/// cannot escape the virtual root boundary.
///
/// # Examples
///
/// ```rust
/// # use strict_path::VirtualRoot;
/// # let td = tempfile::tempdir().unwrap();
/// let vroot: VirtualRoot = VirtualRoot::try_new_create(td.path())?;
///
/// // Create target file
/// let target = vroot.virtual_join("/etc/config/app.conf")?;
/// target.create_parent_dir_all()?;
/// target.write(b"config data")?;
///
/// // Ensure link parent directory exists (Windows requires this for symlink creation)
/// let link = vroot.virtual_join("/links/config.link")?;
/// link.create_parent_dir_all()?;
///
/// // Create symlink - may fail on Windows without Developer Mode/admin privileges
/// if let Err(e) = target.virtual_symlink("/links/config.link") {
/// // Skip test if we don't have symlink privileges (Windows ERROR_PRIVILEGE_NOT_HELD = 1314)
/// #[cfg(windows)]
/// if e.raw_os_error() == Some(1314) { return Ok(()); }
/// return Err(e.into());
/// }
///
/// assert_eq!(link.read_to_string()?, "config data");
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub fn virtual_symlink<P: AsRef<Path>>(&self, link_path: P) -> std::io::Result<()> {
let link_ref = link_path.as_ref();
let validated_link = if link_ref.is_absolute() {
match self.virtual_join(link_ref) {
Ok(p) => p,
Err(e) => return Err(std::io::Error::other(e)),
}
} else {
// Resolve as sibling
let parent = match self.virtualpath_parent() {
Ok(Some(p)) => p,
Ok(None) => match self
.inner
.boundary()
.clone()
.virtualize()
.into_virtualpath()
{
Ok(root) => root,
Err(e) => return Err(std::io::Error::other(e)),
},
Err(e) => return Err(std::io::Error::other(e)),
};
match parent.virtual_join(link_ref) {
Ok(p) => p,
Err(e) => return Err(std::io::Error::other(e)),
}
};
self.inner.strict_symlink(validated_link.inner.path())
}
/// Read the target of a symbolic link and return it as a validated `VirtualPath`.
///
/// DESIGN NOTE:
/// This method has limited practical use because `virtual_join` resolves symlinks
/// during canonicalization. A `VirtualPath` obtained via `virtual_join("/link")` already
/// points to the symlink's target, not the symlink itself.
///
/// To read a symlink target before validation, use `std::fs::read_link` on the raw
/// path, then validate the target with `virtual_join`:
///
/// # Examples
///
/// ```rust
/// use strict_path::VirtualRoot;
///
/// let temp = tempfile::tempdir()?;
/// let vroot: VirtualRoot = VirtualRoot::try_new(temp.path())?;
///
/// // Create a target file
/// let target = vroot.virtual_join("/data/target.txt")?;
/// target.create_parent_dir_all()?;
/// target.write("secret")?;
///
/// // Create symlink (may fail on Windows without Developer Mode)
/// if target.virtual_symlink("/data/link.txt").is_ok() {
/// // virtual_join resolves symlinks: link.txt -> target.txt
/// let resolved = vroot.virtual_join("/data/link.txt")?;
/// assert_eq!(resolved.virtualpath_display().to_string(), "/data/target.txt");
/// // The resolved path reads the target file's content
/// assert_eq!(resolved.read_to_string()?, "secret");
/// }
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub fn virtual_read_link(&self) -> std::io::Result<Self> {
// Read the raw symlink target
let raw_target = std::fs::read_link(self.inner.path())?;
// If the target is relative, resolve it relative to the symlink's parent
let resolved_target = if raw_target.is_relative() {
match self.inner.path().parent() {
Some(parent) => parent.join(&raw_target),
None => raw_target,
}
} else {
raw_target
};
// Validate through virtual_join which clamps escapes
// We need to compute the relative path from the virtual root
let vroot = self.inner.boundary().clone().virtualize();
vroot
.virtual_join(resolved_target)
.map_err(std::io::Error::other)
}
/// Create a hard link at `link_path` pointing to this virtual path (same virtual root required).
///
/// Both `self` (target) and `link_path` must be `VirtualPath` instances created via `virtual_join()`,
/// which ensures all paths are clamped to the virtual root. Absolute paths like `"/etc/data"`
/// passed to `virtual_join()` are automatically clamped to `vroot/etc/data`, ensuring hard links
/// cannot escape the virtual root boundary.
///
/// # Examples
///
/// ```rust
/// # use strict_path::VirtualRoot;
/// # let td = tempfile::tempdir().unwrap();
/// let vroot: VirtualRoot = VirtualRoot::try_new_create(td.path())?;
///
/// // Create target file
/// let target = vroot.virtual_join("/shared/data.dat")?;
/// target.create_parent_dir_all()?;
/// target.write(b"shared data")?;
///
/// // Ensure link parent directory exists (Windows requires this for hard link creation)
/// let link = vroot.virtual_join("/backup/data.dat")?;
/// link.create_parent_dir_all()?;
///
/// // Create hard link
/// target.virtual_hard_link("/backup/data.dat")?;
///
/// // Read through link path, verify through target (hard link behavior)
/// link.write(b"modified")?;
/// assert_eq!(target.read_to_string()?, "modified");
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub fn virtual_hard_link<P: AsRef<Path>>(&self, link_path: P) -> std::io::Result<()> {
let link_ref = link_path.as_ref();
let validated_link = if link_ref.is_absolute() {
match self.virtual_join(link_ref) {
Ok(p) => p,
Err(e) => return Err(std::io::Error::other(e)),
}
} else {
// Resolve as sibling
let parent = match self.virtualpath_parent() {
Ok(Some(p)) => p,
Ok(None) => match self
.inner
.boundary()
.clone()
.virtualize()
.into_virtualpath()
{
Ok(root) => root,
Err(e) => return Err(std::io::Error::other(e)),
},
Err(e) => return Err(std::io::Error::other(e)),
};
match parent.virtual_join(link_ref) {
Ok(p) => p,
Err(e) => return Err(std::io::Error::other(e)),
}
};
self.inner.strict_hard_link(validated_link.inner.path())
}
/// Create a Windows NTFS directory junction at `link_path` pointing to this virtual path.
///
/// - Windows-only and behind the `junctions` feature.
/// - Directory-only semantics; both paths must share the same virtual root.
#[cfg(all(windows, feature = "junctions"))]
pub fn virtual_junction<P: AsRef<Path>>(&self, link_path: P) -> std::io::Result<()> {
// Mirror virtual semantics used by symlink/hard-link helpers:
// - Absolute paths are interpreted in the VIRTUAL namespace and clamped to this root
// - Relative paths are resolved as siblings (or from the virtual root when at root)
let link_ref = link_path.as_ref();
let validated_link = if link_ref.is_absolute() {
match self.virtual_join(link_ref) {
Ok(p) => p,
Err(e) => return Err(std::io::Error::other(e)),
}
} else {
let parent = match self.virtualpath_parent() {
Ok(Some(p)) => p,
Ok(None) => match self
.inner
.boundary()
.clone()
.virtualize()
.into_virtualpath()
{
Ok(root) => root,
Err(e) => return Err(std::io::Error::other(e)),
},
Err(e) => return Err(std::io::Error::other(e)),
};
match parent.virtual_join(link_ref) {
Ok(p) => p,
Err(e) => return Err(std::io::Error::other(e)),
}
};
// Delegate to strict helper after validating link location in virtual space
self.inner.strict_junction(validated_link.inner.path())
}
/// Rename/move within the same virtual root. Relative destinations are siblings; absolute are clamped to root.
///
/// Accepts `impl AsRef<Path>` for the destination. Absolute paths (starting with `"/"`) are
/// automatically clamped to the virtual root via internal `virtual_join()` call, ensuring the
/// destination cannot escape the virtual boundary. Relative paths are resolved as siblings.
/// Parent directories are not created automatically.
///
/// # Examples
///
/// ```rust
/// # use strict_path::VirtualRoot;
/// # let td = tempfile::tempdir().unwrap();
/// let vroot: VirtualRoot = VirtualRoot::try_new_create(td.path())?;
///
/// let source = vroot.virtual_join("temp/file.txt")?;
/// source.create_parent_dir_all()?;
/// source.write(b"content")?;
///
/// // Absolute destination path is clamped to virtual root
/// let dest_dir = vroot.virtual_join("/archive")?;
/// dest_dir.create_dir_all()?;
/// source.virtual_rename("/archive/file.txt")?;
///
/// let renamed = vroot.virtual_join("/archive/file.txt")?;
/// assert_eq!(renamed.read_to_string()?, "content");
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub fn virtual_rename<P: AsRef<Path>>(&self, dest: P) -> std::io::Result<()> {
let dest_ref = dest.as_ref();
let dest_v = if dest_ref.is_absolute() {
match self.virtual_join(dest_ref) {
Ok(p) => p,
Err(e) => return Err(std::io::Error::other(e)),
}
} else {
// Resolve as sibling under the current virtual parent (or root if at "/")
let parent = match self.virtualpath_parent() {
Ok(Some(p)) => p,
Ok(None) => match self
.inner
.boundary()
.clone()
.virtualize()
.into_virtualpath()
{
Ok(root) => root,
Err(e) => return Err(std::io::Error::other(e)),
},
Err(e) => return Err(std::io::Error::other(e)),
};
match parent.virtual_join(dest_ref) {
Ok(p) => p,
Err(e) => return Err(std::io::Error::other(e)),
}
};
// Perform the actual rename via StrictPath
self.inner.strict_rename(dest_v.inner.path())
}
/// Copy within the same virtual root. Relative destinations are siblings; absolute are clamped to root.
///
/// Accepts `impl AsRef<Path>` for the destination. Absolute paths (starting with `"/"`) are
/// automatically clamped to the virtual root via internal `virtual_join()` call, ensuring the
/// destination cannot escape the virtual boundary. Relative paths are resolved as siblings.
/// Parent directories are not created automatically. Returns the number of bytes copied.
///
/// # Examples
///
/// ```rust
/// # use strict_path::VirtualRoot;
/// # let td = tempfile::tempdir().unwrap();
/// let vroot: VirtualRoot = VirtualRoot::try_new_create(td.path())?;
///
/// let source = vroot.virtual_join("data/source.txt")?;
/// source.create_parent_dir_all()?;
/// source.write(b"data to copy")?;
///
/// // Absolute destination path is clamped to virtual root
/// let dest_dir = vroot.virtual_join("/backup")?;
/// dest_dir.create_dir_all()?;
/// let bytes = source.virtual_copy("/backup/copy.txt")?;
///
/// let copied = vroot.virtual_join("/backup/copy.txt")?;
/// assert_eq!(copied.read_to_string()?, "data to copy");
/// assert_eq!(bytes, 12);
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub fn virtual_copy<P: AsRef<Path>>(&self, dest: P) -> std::io::Result<u64> {
let dest_ref = dest.as_ref();
let dest_v = if dest_ref.is_absolute() {
match self.virtual_join(dest_ref) {
Ok(p) => p,
Err(e) => return Err(std::io::Error::other(e)),
}
} else {
// Resolve as sibling under the current virtual parent (or root if at "/")
let parent = match self.virtualpath_parent() {
Ok(Some(p)) => p,
Ok(None) => match self
.inner
.boundary()
.clone()
.virtualize()
.into_virtualpath()
{
Ok(root) => root,
Err(e) => return Err(std::io::Error::other(e)),
},
Err(e) => return Err(std::io::Error::other(e)),
};
match parent.virtual_join(dest_ref) {
Ok(p) => p,
Err(e) => return Err(std::io::Error::other(e)),
}
};
// Perform the actual copy via StrictPath
std::fs::copy(self.inner.path(), dest_v.inner.path())
}
}