monofs 0.2.0

`monofs` is an immutable distributed file system.
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
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

<div align="center">
  <h1 align="center">monofs</h1>

  <p>
    <a href="https://github.com/appcypher/monocore/actions?query=">
      <img src="https://github.com/appcypher/monocore/actions/workflows/tests_and_checks.yml/badge.svg" alt="Build Status">
    </a>
    <a href="https://github.com/appcypher/monocore/blob/main/LICENSE">
      <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License">
    </a>
  </p>
</div>

**`monofs`** is a powerful, distributed filesystem designed for distributed workloads. It provides a simple and intuitive API for managing files and directories in a content-addressed storage system.

> [!WARNING]
> This project is in early development and is not yet ready for production use.

##

## Features

- Content-addressed storage
- Immutable data structures with copy-on-write semantics
- Support for files, directories, and symbolic links
- Asynchronous API for efficient I/O operations
- Versioning support for tracking file and directory history

## Usage

Here are some examples of how to use the `monofs` API:

### Working with Files

```rust
use monofs::filesystem::{File, FileInputStream, FileOutputStream};
use monoutils_store::{MemoryStore, Storable};
use tokio::io::{AsyncReadExt, AsyncWriteExt};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let store = MemoryStore::default();

    // Create a new file
    let mut file = File::new(store.clone());

    // Write content to the file
    let mut output_stream = FileOutputStream::new(&mut file);
    output_stream.write_all(b"Hello, monofs!").await?;
    output_stream.shutdown().await?;

    // Read content from the file
    let input_stream = FileInputStream::new(&file).await?;
    let mut buffer = Vec::new();
    input_stream.read_to_end(&mut buffer).await?;

    println!("File content: {}", String::from_utf8_lossy(&buffer));

    // Store the file
    let file_cid = file.store().await?;
    println!("Stored file with CID: {}", file_cid);

    Ok(())
}
```

### Working with Directories

```rust
use monofs::filesystem::{Dir, File, FsResult};
use monoutils_store::{MemoryStore, Storable};

#[tokio::main]
async fn main() -> FsResult<()> {
    let store = MemoryStore::default();

    // Create a new root directory
    let mut root = Dir::new(store.clone());

    // Create a file in the directory
    root.put_file("example.txt", File::new(store.clone()))?;

    // Create a subdirectory
    root.put_dir("subdir", Dir::new(store.clone()))?;

    // List directory contents
    for (name, entity) in root.get_entries() {
        println!("- {}: {:?}", name, entity);
    }

    // Store the directory
    let root_cid = root.store().await?;
    println!("Stored root directory with CID: {}", root_cid);

    Ok(())
}
```

## API Overview

- `File`: Represents a file in the filesystem
- `Dir`: Represents a directory in the filesystem
- `FileInputStream`: Provides read access to file contents
- `FileOutputStream`: Provides write access to file contents
- `Metadata`: Stores metadata for files and directories
- `Storable`: Trait for storing and loading entities from the content-addressed store

For more detailed examples and API usage, check out the `examples` directory and the API documentation.

## Development

To set up `monofs` for development:

1. Ensure you have Rust installed (latest stable version)
2. Clone the monocore repository:
   ```sh
   git clone https://github.com/appcypher/monocore
   cd monocore/monofs
   ```
3. Build the project:
   ```sh
   cargo build
   ```
4. Run tests:
   ```sh
   cargo test
   ```

## Contributing

Contributions are welcome! Please read the [CONTRIBUTING.md](../CONTRIBUTING.md) file for guidelines on how to contribute to this project.

## License

This project is licensed under the [Apache License 2.0](../LICENSE).

## Acknowledgements

monofs draws inspiration from the [WNFS (Webnative File System)](https://github.com/wnfs-wg/rs-wnfs) project.