pub struct WorkspaceRoot { /* private fields */ }Expand description
Validated authority to resolve tool paths beneath one canonical directory.
Construction resolves symlinks in the supplied host path and requires an existing directory. Model-supplied paths are never interpreted relative to the process current directory.
§TOCTOU limits
Path-based host APIs cannot make resolution and a later open or rename one
atomic operation. Callers performing mutations must invoke
Self::revalidate_mutation immediately before commit. Executors should
additionally prefer descriptor-relative operations where a safe portable
implementation is available. Unix identity checks use device/inode. The
portable stable Windows metadata APIs used here provide a best-effort
fingerprint instead of a file index. This capability fails closed on
detected replacement, but it does not claim to eliminate every filesystem
race.
Implementations§
Source§impl WorkspaceRoot
impl WorkspaceRoot
Sourcepub fn new(path: impl AsRef<Path>) -> Result<Self, WorkspacePathError>
pub fn new(path: impl AsRef<Path>) -> Result<Self, WorkspacePathError>
Constructs a capability from an existing host directory.
§Errors
Returns a stable bounded error if the path is absent, is not a directory, or cannot be resolved safely.
Sourcepub fn host_path(&self) -> &Path
pub fn host_path(&self) -> &Path
Returns the canonical host directory represented by this capability.
Sourcepub fn resolve_existing(
&self,
path: &str,
) -> Result<ResolvedExistingPath, WorkspacePathError>
pub fn resolve_existing( &self, path: &str, ) -> Result<ResolvedExistingPath, WorkspacePathError>
Resolves a model path that must already exist.
The returned display path is normalized and workspace-relative. The host path is canonical and has passed a component-wise containment check against this capability.
§Errors
Rejects malformed, absolute, traversing, missing, unresolvable, or workspace-escaping paths.
Sourcepub fn revalidate_existing(
&self,
target: &ResolvedExistingPath,
) -> Result<(), WorkspacePathError>
pub fn revalidate_existing( &self, target: &ResolvedExistingPath, ) -> Result<(), WorkspacePathError>
Revalidates an existing target immediately before opening it.
§Errors
Returns CapabilityMismatch for a value from another workspace and
PathChanged if resolution or filesystem identity changed.
Sourcepub fn verify_opened_existing(
&self,
target: &ResolvedExistingPath,
metadata: &Metadata,
) -> Result<(), WorkspacePathError>
pub fn verify_opened_existing( &self, target: &ResolvedExistingPath, metadata: &Metadata, ) -> Result<(), WorkspacePathError>
Verifies that an opened file handle identifies the resolved target.
Call this with metadata obtained from the opened file handle, not by looking up its path again. It closes the validation-to-open race for the object identity on platforms that expose stable file identifiers.
§Errors
Returns PathChanged if the opened object differs from the resolved
target, or CapabilityMismatch for a token from another workspace.
Sourcepub fn resolve_mutation(
&self,
path: &str,
) -> Result<ResolvedMutationPath, WorkspacePathError>
pub fn resolve_mutation( &self, path: &str, ) -> Result<ResolvedMutationPath, WorkspacePathError>
Resolves an existing or prospective mutation target.
The workspace root itself is not a valid mutation target. Existing targets are canonicalized. For a prospective target, the nearest existing ancestor is canonicalized, checked as a directory, and checked for workspace containment before unresolved components are appended.
§Errors
Rejects malformed, absolute, traversing, unresolvable, root-targeting, non-directory-parent, or workspace-escaping paths.
Sourcepub fn revalidate_mutation(
&self,
target: &ResolvedMutationPath,
) -> Result<(), WorkspacePathError>
pub fn revalidate_mutation( &self, target: &ResolvedMutationPath, ) -> Result<(), WorkspacePathError>
Revalidates a mutation target immediately before its commit operation.
This detects containment changes, target appearance/disappearance, and nearest-existing-ancestor replacement on supported platforms. A caller must discard the old value and resolve again after any failure.
§Errors
Returns CapabilityMismatch for a value from another workspace and a
stable path error when the target no longer has the same resolution.
Trait Implementations§
Source§impl Clone for WorkspaceRoot
impl Clone for WorkspaceRoot
Source§impl Debug for WorkspaceRoot
impl Debug for WorkspaceRoot
impl Eq for WorkspaceRoot
Source§impl PartialEq for WorkspaceRoot
impl PartialEq for WorkspaceRoot
impl StructuralPartialEq for WorkspaceRoot
Auto Trait Implementations§
impl Freeze for WorkspaceRoot
impl RefUnwindSafe for WorkspaceRoot
impl Send for WorkspaceRoot
impl Sync for WorkspaceRoot
impl Unpin for WorkspaceRoot
impl UnsafeUnpin for WorkspaceRoot
impl UnwindSafe for WorkspaceRoot
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key and return true if they are equal.