starred/deltaglider
1
0
Fork 0
mirror of https://github.com/beshu-tech/deltaglider.git synced 2026-07-11 07:32:46 +02:00
Code Issues 1 Packages Projects Releases Wiki Activity

refactor: Rename Leaf to DeltaSpace for semantic clarity

Browse Source 
- Renamed Leaf class to DeltaSpace throughout the codebase
- Updated all imports, method signatures, and variable names
- Updated documentation and comments to reflect the new naming
- DeltaSpace better represents a container for delta-compressed files

The term "DeltaSpace" is more semantically accurate than "Leaf" as it
represents a space/container for managing related files with delta
compression, not a terminal node in a tree structure.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Simone Scarduzio
2025-09-23 08:05:20 +02:00
parent 0613de9a5e
commit fb3ad0e076
14 changed files with 112 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/deltaglider_specs.txt
+7 -7
View File
@@ -12,14 +12,14 @@ The cost of storing large binary artifacts (e.g., ZIP plugins, deliverables) on
by only a few kilobytes. Current practice redundantly uploads full versions, wasting space and increasing transfer times.
deltaglider is a CLI tool that transparently reduces storage overhead by representing a directory of similar large files as:
- A single reference file (reference.bin) in each leaf S3 prefix.
- A single reference file (reference.bin) in each DeltaSpace S3 prefix.
- A set of delta files (<original>.delta) encoding differences against the reference.
This approach compresses storage usage to near-optimal while retaining simple semantics.
Goals
-----
1. Save S3 space by storing only one full copy of similar files per leaf and small binary deltas for subsequent versions.
1. Save S3 space by storing only one full copy of similar files per DeltaSpace and small binary deltas for subsequent versions.
2. Transparent developer workflow – deltaglider put/get mirrors aws s3 cp.
3. Minimal state management – no manifests, no external databases.
4. Integrity assurance – strong hashing (SHA256) stored in metadata, verified on upload/restore.
@@ -28,19 +28,19 @@ Goals
Non-Goals
---------
- Deduplication across multiple directories/prefixes.
- Streaming delta generation across multiple references (always one reference per leaf).
- Streaming delta generation across multiple references (always one reference per DeltaSpace).
- Automatic background compaction or garbage collection.
Terminology
-----------
- Leaf prefix: An S3 "directory" containing only files, no further sub-prefixes.
- Reference file: The first uploaded file in a leaf, stored as reference.bin.
- DeltaSpace: An S3 prefix containing related files for delta compression.
- Reference file: The first uploaded file in a DeltaSpace, stored as reference.bin.
- Delta file: Result of running xdelta3 against the reference, named <original>.delta.
Architecture
------------
Reference Selection
- First uploaded file in a leaf becomes the reference.
- First uploaded file in a DeltaSpace becomes the reference.
- Stored as reference.bin.
- Original filename preserved in metadata of both reference.bin and zero-diff delta.
@@ -68,7 +68,7 @@ Local Cache
CLI Specification
-----------------
deltaglider put <file> <s3://bucket/path/to/leaf/>
deltaglider put <file> <s3://bucket/path/to/delta_space/>
- If no reference.bin: upload <file> as reference.bin, upload zero-diff <file>.delta.
- If reference.bin exists: create delta, upload <file>.delta with metadata.
- Output JSON summary.