The Zero-Dependency Optimization Daemon (v5.3)
syv is a hyper-lightweight, multi-threaded optimization engine designed to sit between your raw development code and your production web servers. By natively handling Single Page Application (SPA) payload compression, automatic DOM cache-busting injection, and Static Site Generation (SSG) caching, syv drastically reduces Time-To-First-Byte (TTFB) and network latency without the bloat of modern JS frameworks.
Modern web development suffers from dependency fatigue. Tools like Webpack, Vite, or Next.js are incredibly powerful, but they often require downloading gigabytes of node_modules just to perform basic file compression or routing.
syv was built in defianc
8000
e of this trend, strictly adhering to the following tenets:
- The Zero-Dependency Oath: Written entirely in standard Python 3. No
pip install, nonpm install, no virtual environments. You drop the binary into your system, and it runs instantly. - The UNIX Philosophy: Do one thing, and do it perfectly.
syvis a file-generation middleware that generates hashed payloads and manifests for your actual server (Nginx, Express, FastAPI) to serve.syv serveexists only for local dev/preview with gzip negotiation. - Bare-Metal Performance: By utilizing
concurrent.futuresfor multi-threading, chunked hashing, and incremental builds (skip unchanged files via.gzmtime + manifest), it maximizes hardware utilization (from 8-core desktop CPUs to ARM-based Termux environments). - Enterprise Reliability: Built-in self-healing retries, granular POSIX exit codes, and actionable exception handling make
syva bulletproof, fault-tolerant addition to any CI/CD pipeline.
syv is built to withstand hostile environments and malicious inputs. The daemon includes strict validation layers:
- SSRF Prevention: The SSG scraper strictly validates that all target URLs are localhost-bound (
127.0.0.1or::1), preventing Server-Side Request Forgery attacks. - Symlink & Path Traversal Blocking: Refuses to follow symbolic links during cache removal and rejects manifest keys with
.., absolute paths,~, or\. Relative sub-paths likejs/app.jsare allowed (v5.2). - Pre-flight Checks: Automatically validates directory read/write permissions and checks
shutil.disk_usagebefore initiating massive multi-threaded I/O operations to prevent disk-full crashes.
Network drops and memory spikes are a reality. syv handles them gracefully:
- Exponential Backoff: Network operations (like sitemap scraping) utilize a
@with_retrydecorator with exponential backoff to survive temporary server overloads. - Graceful Degradation: If the multi-core
ThreadPoolExecutortriggers aMemoryErroron massive directories,syvautomatically falls back to sequential processing instead of crashing. - Unicode Fallback Chain: Reads legacy files using a smart decoding chain (
UTF-8→latin-1→cp1252), preventing pipeline failures due to malformed characters. - Chunked Hashing (v5.2): File hashes are computed in 8KB chunks, so multi-GB payloads don't blow up RAM.
Injecting hashed asset URLs into your HTML shouldn't require backend logic. After every syv build, the DOM Rewriter scans all .html files in your build directory and rewrites asset references in-place using the generated build_manifest.json.
Manifest keys are now relative POSIX paths (js/app.js, not just app.js), so same-named files in different folders no longer collide. Re-runs replace stale ?v= hashes instead of stacking them.
Before:
<script src="js/app.js"></script>After syv build:
<script src="js/app.js?v=e3b0c442"></script>When dealing with hundreds of heavy assets, syv maps your build directory to an optimized thread pool to calculate hashes and generate .gz gzip streams simultaneously.
- Expanded types:
.js,.css,.html,.svg,.json,.map,.xml,.txt,.woff/.woff2(was JS/CSS only). - Incremental: unchanged files (fresh
.gz+ matching manifest entry) are skipped. Second run reportsSkipped N unchanged files. - HTML two-phase: assets compress → DOM rewrite → HTML compress, so
.html.gzalways matches injected content.
Instead of relying on heavy third-party filesystem event libraries, syv watch utilizes a highly optimized os.path.getmtime polling loop. It features a MAX_WATCHED_FILES limit (100,000 files) and periodic memory cleanup to ensure zero memory leaks during extended development sessions.
v5.2 note:
watchtracks compressible assets but skips.htmlto avoid rewrite-triggered loops. Runsyv buildafter HTML changes for DOM injection.
syv serve ./dist -p 8080 serves your build on localhost, negotiating Accept-Encoding: gzip and serving prebuilt .gz with Content-Encoding: gzip + correct Content-Type. Dev/preview only — production still belongs to Nginx/CDN.
syv stats ./dist prints original vs compressed sizes, savings %, top-10 files, .gz/manifest counts, and ./syv_cache usage. Pipe it into CI logs to track payload budgets.
syv run update acts as a localized web crawler. It automatically detects /sitemap.xml and utilizes multi-threading to concurrently scrape and freeze your dynamic backend into a flat ./syv_cache/ directory alongside a Time-To-Live (TTL) metadata manifest.
When syv is initialized and running in your project, it manages your workspace efficiently without cluttering it. Here is how your project structure will look:
.
├── syv # The core Zero-Dependency Python Daemon
├── syv.json # Daemon configuration (Generated by `syv init`)
├── installer/
│ └── install.cmd # Windows fast-installer & PATH injector
│ └── uninstall.cmd # Windows fast-uninstaller & PATH uninjector
├── dist/ # Target SPA Build Directory (Your frontend output)
│ ├── build_manifest.json # Auto-generated relative-path version map (v5.2)
│ ├── index.html # DOM-rewritten HTML (auto-injected by syv)
│ ├── index.html.gz # Compressed HTML (matches injected content)
│ ├── js/
│ │ ├── app.js # Raw JS asset
│ │ └── app.js.gz # Multi-thread compressed gzip payload
│ └── css/
│ ├── style.css # Raw CSS asset
│ └── style.css.gz # Compressed payload
└── syv_cache/ # Local SSG Cache (Generated by `syv run update`)
├── manifest.json # TTL metadata & generation stats
├── index.html # Scraped root route
└── dashboard/
└── index.html # Frozen dynamic endpoint
Since syv is a standalone Python script, installation is simply making it executable and moving it to your system's PATH.
For Linux / macOS / Termux:
curl -O [https://raw.githubusercontent.com/kyrtstn/syv/main/syv](https://raw.githubusercontent.com/kyrtstn/syv/main/syv)
chmod +x syv
sudo mv syv /usr/local/bin/For Windows (CMD / PowerShell):
syv is 100% Windows compatible (including native ANSI terminal aesthetics).
- Clone the repo and run the installer:
installer\install.bat
- Open a new terminal and verify:
syv help
syv respects a syv.json file placed in the project root. Generate a template using syv init.
{
"port": 3000,
"ignore": ["node_modules", ".git", ".venv", "tests", "syv_cache"],
"ttl": 3600,
"silent_mode": false,
"workers": 0,
"gzip_level": 9,
"include": [],
"exclude": ["*.map"],
"timeout": 10,
"headers": {},
"allowlist": ["staging.internal"],
"log_file": null
}workers: 0= auto (CPU count, max 16),1-32= fixed pool for build + scrape.gzip_level: 1-9(9 = max compression, 1 = fastest).include/exclude: glob filters (*.map,js/*) applied afterignore.timeout: scraper HTTP seconds (1-120).headers: extra request headers (e.g.Authorization).allowlist: extra non-localhost hosts the scraper may fetch (SSRF guard stays on otherwise).log_file: tee all output to a file as well as the terminal.
syv version # Print syv version (v5.2)
syv init # Generate default syv.json template
syv clean ./dist # Purge .gz files, manifests, and local cache
syv build ./dist --dry-run # Simulate operations without disk I/Osyv build ./dist # Incremental multi-threaded build + DOM injection
syv watch ./dist # Debounced live-reload daemon (deleted files pruned)
syv serve ./dist -p 8080 # Gzip-aware local preview server (New in v5.2)
syv stats ./dist # Compression savings + cache report (New in v5.2)
syv check ./dist # Verify manifest + .gz + HTML hashes, exit 1 on fail (New in v5.3)
syv check ./dist --json # Machine-readable gate for CI (New in v5.3)
syv build ./dist --debug # Enable verbose, actionable execution logssyv run update # Scrapes sitemap.xml / sitemapindex / robots.txt (v5.3)
syv run update -p 5000 # Scrape specific port
syv force run update # Bypass TTL checks and force hard rebuildsyv v5.2 features a highly structured exception hierarchy. It acts as a bulletproof CI/CD citizen by halting deployments on failure and returning granular POSIX exit codes to help automated runners diagnose the exact root cause.
| Exit Code | Classification | Description |
|---|---|---|
0 |
Success | Execution completed flawlessly. |
1 |
Fatal Error | General execution or unexpected thread failure. |
2 |
Config Error | Invalid syv.json syntax or bad CLI parameters (e.g., invalid port). |
3 |
Network Error | Connection timeouts, DNS failures, or completely dead routes. |
7 |
Security Error | SSRF attempts, path traversals, or symlink violations detected. |
8 |
Resource Error | System out of memory or thread explosion. |
13 |
File System Error | Permission denied, disk full (ENOSPC), or missing directories. |
Example GitHub Actions Pipeline:
name: syv Optimization Pipeline
on: [push]
jobs:
build-and-optimize:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Compile Source Code
run: npm run build
- name: Optimize Payloads with syv
run: |
chmod +x ./syv
./syv build ./dist
- name: Gate on consistency
run: |
./syv check ./dist
./syv stats ./dist
- name: Deploy to Production
run: echo "Deploying highly optimized, secure payloads..."Zero dependencies, stdlib only:
python -m unittest discover -s tests -v