ekv-fs 0.2.0

A chunked, #![no_std] Virtual File System built on top of the Embassy ekv key-value store.
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

# ekv-fs

[![crates.io](https://img.shields.io/crates/v/ekv-fs.svg)](https://crates.io/crates/ekv-fs)
[![docs.rs](https://docs.rs/ekv-fs/badge.svg)](https://docs.rs/ekv-fs)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE-MIT)

A chunked, `#![no_std]`, fully asynchronous virtual file system on top of [Embassy `ekv`](https://github.com/embassy-rs/ekv) for embedded Rust.

## Why

Flash on microcontrollers needs wear leveling. `ekv` provides a safe KV store, but not paths, large blobs, or streaming reads. **ekv-fs** maps path strings to chunked keys so you can store and read files with bounded RAM—pure Rust, no C FFI.

## Features

- **no_std** with `heapless` paths and const-generic `MAX_PATH_LEN` / `CHUNK_SIZE`
- **Async** API aligned with Embassy
- **Streaming reads** via [`EkvFile`](https://docs.rs/ekv-fs/latest/ekv_fs/struct.EkvFile.html)
- **Replace-safe writes** — overwriting a file removes old chunks in one transaction

## Quick start

```toml
[dependencies]
ekv-fs = "0.2"
ekv = { version = "1", default-features = false }
embassy-sync = { version = "0.6", default-features = false }
```

```rust
use ekv::{Config, Database};
use ekv_fs::EkvFs;

// After you have a formatted `Database` on your flash driver:
let fs = EkvFs::<_, _, 64, 512>::new(&db);

fs.write_file("/notes.txt", b"hello").await?;
let meta = fs.stat("/notes.txt").await?;
let mut file = fs.open("/notes.txt").await?;
let mut buf = [0u8; 32];
let n = file.read(&mut buf).await?;
fs.delete_file("/notes.txt").await?;
```

Pick `MAX_PATH_LEN` and `CHUNK_SIZE` to match your MCU RAM budget. `MAX_PATH_LEN` must be at most `KEY_BUF_CAP - KEY_SUFFIX_OVERHEAD` (104 bytes with the default `KEY_BUF_CAP` of 128).

## API scope (v0.2)

| Supported | Not yet |
|-----------|---------|
| Whole-file write / replace | Append, partial write |
| Stat, open, sequential read | Seek |
| Delete | Directory listing, rename |

Paths are opaque strings (e.g. `/photos/cat.jpg`); there is no directory tree.

## Errors

Operations return [`ekv_fs::Error`](https://docs.rs/ekv-fs/latest/ekv_fs/enum.Error.html): `NotFound`, `PathTooLong`, `KeyTooLong`, `Database`, `Serialize`.

## MSRV

Rust **1.87** or newer (edition **2024**; required by `heapless` 0.9; see `rust-version` in `Cargo.toml`).

## License

Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or [MIT license](LICENSE-MIT) at your option.