silk/os_filesystem

Native FileSystem provider confined beneath one explicitly owned platform root.

When to use

Construct OsFileSystem at a native application edge and provide it to portable filesystem code. Supply an in-memory FileSystem in tests or on targets without native OS access.

Details

Portable / denotes the provider root rather than the host filesystem root. The native boundary rejects malformed paths, root escape, and symlink traversal outside that confinement. Whole-file reads and writes own or commit complete contents, directory listings retry oversized entries and sort complete child paths deterministically. Low-level failures become portable FileError values with retained native codes.

make copies its root. The root must be an absolute, non-empty, NUL-free native path. A root that violates this precondition traps. Open handles close on success and failure. If an operation and close both fail, the operation's original typed failure remains the reported result.

Constructing the provider performs no filesystem operation beyond owning the root bytes. Portable code uses FileSystem operations after the application supplies &mut OsFileSystem for the &mut FileSystem requirement.

Gotchas

Reachable OS filesystem operations are native-only. Direct WebAssembly compilation rejects them rather than inventing filesystem imports; evaluator execution requires an injected adapter.

Examples

Construct a provider without accessing the filesystem

import silk.allocator { Allocator }

import silk.effect { Effect }

import silk.os_filesystem as OsFileSystem

effect fn program() -> i32
! Allocator.OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let provider = run OsFileSystem.make("/tmp")
    |> Effect.provideMut<Allocator>(&mut allocator)
  drop provider
  return 42
}

effect fn recover(error: Allocator.OutOfMemoryError) -> i32 {
  return 0
}

pub fn main() -> i32 {
  return run Effect.catchAll(program(), recover)
}

Import as OsFileSystem with import silk.os_filesystem.

Public declarations: 2.

OsFileSystem

pub struct OsFileSystem

A native FileSystem provider confined beneath one independently owned platform root.

Details

Portable absolute paths resolve inside this root. The provider never exposes the root as a Path, and operations reject lexical or symbolic-link escape from the root.

make

pub effect fn make(root: string) -> OsFileSystem ! OutOfMemoryError ? &mut Allocator

Copies one absolute native root and creates a confined filesystem provider.

When to use

Use this function at a native application edge. Provide the result as &mut FileSystem to code that uses the portable filesystem service.

Details

Construction owns the root bytes but does not open the directory. Portable / then denotes this provider root instead of the host filesystem root.

Gotchas

root must be non-empty, absolute, and NUL-free. A value that violates this precondition traps. Allocation failure leaves no provider value.

Implementation FileSystem for OsFileSystem

impl FileSystem for OsFileSystem

Operation readFile

readFile = OsFileSystem.readFile

Operation writeFile

writeFile = OsFileSystem.writeFile

Operation stat

stat = OsFileSystem.stat

Operation listDirectory

listDirectory = OsFileSystem.listDirectory

Operation createDirectory

createDirectory = OsFileSystem.createDirectory

Operation removeFile

removeFile = OsFileSystem.removeFile

Operation removeDirectory

removeDirectory = OsFileSystem.removeDirectory

Operation createTemporaryDirectory

createTemporaryDirectory = OsFileSystem.createTemporaryDirectory