FiloContainer

FILO – Fast, Flexible, Multi-file Container for .NET

Static Badge NuGet Version NuGet Downloads Visitors

FILO

image image image

FILO v1.2.0 Highlights

🧱 Stability & Format Fixes

🔐 Security Improvements

⚙️ Reliability Improvements

Overview

FILO (Files In, Layered & Organized) is a modern multi-file container format for .NET designed for large-scale file storage and streaming.

It supports:

FILO is designed for streaming-first storage systems, not just archive compression.

Why FILO?

Traditional formats like ZIP have limitations:

FILO solves this by:

FILO Container Layout (v1.2)

+------------------------------------------------+
| HEADER (JSON)                                  |
|------------------------------------------------|
| - Format: FILO                                 |
| - Version: 1.2                                 |
| - ChunkSize                                    |
| - FileCount                                    |
| - Encryption Mode (AES-CBC)                    |
| - KDF (PBKDF2)                                 |
+------------------------------------------------+
| FILE CHUNKS                                    |
|  [IV][LEN][DATA] (encrypted)                   |
|  [LEN][DATA] (plain)                           |
+------------------------------------------------+
| INDEX (JSON)                                   |
+------------------------------------------------+
| METADATA (JSON)                                |
+------------------------------------------------+
| CHECKSUM (JSON)                                |
+------------------------------------------------+
| FOOTER                                         |
| - IndexOffset                                  |
| - MetadataOffset                               |
| - ChecksumOffset                               |
| - "FLOF" magic                                 |
+------------------------------------------------+

This design allows streaming large files directly, without full extraction.

Comparison with Other Formats

Feature FILO ZIP JSON Container Raw BLOB
Multi-file support ✅ Yes ✅ Yes ❌ No ❌ No
Streaming large files ✅ Yes, chunked ❌ Needs extraction ❌ Needs parsing ❌ No
Async support ✅ Fully async ❌ Limited ✅ Async with lib ✅ Async
Encryption ✅ Chunk-level AES256 ✅ Whole file ❌ No native ✅ App-level
Metadata storage ✅ Embedded JSON ❌ Limited ✅ Yes ❌ No
Checksums / Integrity ✅ SHA256 per file ❌ Optional ❌ Needs custom ❌ Needs custom
Browser/Blazor streaming ✅ Yes ❌ No ❌ No ❌ No

FILO is ideal for media, backups, and server-side streaming where large files need chunked access.

Installation

Install via NuGet:

dotnet add package Filo --version 1.2.0

Basic Usage

📦 Create Container

using Filo;

var writer = new FiloWriter("backup.filo")
    .AddFile("video.mp4", new FileMetadata { MimeType = "video/mp4" })
    .AddFile("audio.mp3", new FileMetadata { MimeType = "audio/mpeg" })
    .WithChunkSize(5_000_000)
    .WithPassword("1234567890");

await writer.WriteAsync();

Console.WriteLine("FILO container created!");

📖 Read Container

var reader = new FiloReader("backup.filo");
await reader.InitializeAsync();

var key = reader.DeriveKey("1234567890");

foreach (var file in reader.ListFiles())
{
    Console.WriteLine($"{file.Name} ({file.FileSize} bytes)");
}

📡 Stream File (Recommended)

await using var stream = reader.OpenStream("video.mp4", key);
await using var output = File.Create("restored.mp4");

await stream.CopyToAsync(output);

🔁 Chunk-by-chunk processing

await foreach (var chunk in reader.StreamFileAsync("video.mp4", key))
{
    // Process streaming data
}

🔐 Encryption Model (v1.2)

🧠 Integrity System

🌐 ASP.NET Streaming Example

public async Task<IActionResult> GetVideo()
{
    var reader = new FiloReader("media.filo");
    await reader.InitializeAsync();

    var key = reader.DeriveKey("password");

    var stream = new FiloStream(reader, "movie.mp4", key);

    return File(stream, "video/mp4");
}

Supports large files, streaming, and AES256 encrypted chunks. Browser can seek, pause, and resume seamlessly.

Multi-file Container Example

var writer = new FiloWriter("media.filo")
    .AddFile("movie.mp4", new FileMetadata { MimeType = "video/mp4" })
    .AddFile("audio.mp3", new FileMetadata { MimeType = "audio/mpeg" })
    .AddFile("subtitle.srt", new FileMetadata { MimeType = "text/plain" })
    .WithChunkSize(10_000_000)
    .WithPassword("mypassword");

await writer.WriteAsync();

Chunked Streaming

await foreach (var chunk in reader.StreamFileAsync("largevideo.mp4", key))
{
    // Process chunk (send to player or API)
}

⚡ When to Use What

Method Use Case
OpenStream() Direct file streaming
FiloStream ASP.NET / UI streaming
StreamFileAsync() Custom chunk processing
CopyToAsync() Extraction

📦 File Metadata

new FileMetadata
{
    MimeType = "video/mp4",
    Description = "Main movie file"
}

Always verify checksum for large file integrity.

Checksums & Integrity

var checksum = await FiloChecksum.ComputeFileSHA256Async("video.mp4");
Console.WriteLine(checksum);

Fluent API Summary

Class Key Methods
FiloWriter .AddFile(), AddDirectory(), .WithChunkSize(), .WithPassword(), .WriteAsync()
FiloReader .InitializeAsync(), DeriveKey(), FileExists(), GetFileInfo(), .ListFiles(), .StreamFileAsync(), OpenStream(), ExtractFileAsync(), ExtractDirectoryAsync(), ReadHeaderAsync()
FiloStream .ReadAsync() – supports streaming directly to players, Read()
FiloChecksum .ComputeSHA256(), .ComputeSHA256Async(), .ComputeFileSHA256Async(), .ComputeFileSHA256Async(),.Verify(), VerifyFileAsync()
FiloEncryption .Encrypt(), .Decrypt()

🔧 Core Classes

Class Responsibility
FiloWriter Builds container
FiloReader Reads container
FiloStream Streaming abstraction
FiloChecksum Integrity verification
FiloEncryption AES operations

Notes (v1.2 Rules)

License

MIT License

This site is open source. Improve this page.