Upgrade to Zig 0.15.1

Author: habedi

.github/workflows/docs.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Install Zig
         uses: goto-bus-stop/setup-zig@v2
         with:
-          version: '0.14.1'
+          version: '0.15.1'
 
       - name: Install System Dependencies
         run: |

.github/workflows/lints.yml

@@ -27,7 +27,7 @@ jobs:
       - name: Install Zig
         uses: goto-bus-stop/setup-zig@v2
         with:
-          version: '0.14.1'
+          version: '0.15.1'
 
       - name: Install Dependencies
         run: |

.github/workflows/tests.yml

@@ -27,7 +27,7 @@ jobs:
       - name: Install Zig
         uses: goto-bus-stop/setup-zig@v2
         with:
-          version: '0.14.1'
+          version: '0.15.1'
 
       - name: Install Dependencies
         run: |

.gitignore

@@ -97,3 +97,4 @@ uv.lock
 *_output.txt
 public/
 site/
+*.a

Makefile

@@ -1,7 +1,7 @@
 # ################################################################################
 # # Configuration and Variables
 # ################################################################################
-ZIG    ?= $(shell which zig || echo ~/.local/share/zig/0.14.1/zig)
+ZIG    ?= $(shell which zig || echo ~/.local/share/zig/0.15.1/zig)
 BUILD_TYPE    ?= Debug
 BUILD_OPTS      = -Doptimize=$(BUILD_TYPE)
 JOBS          ?= $(shell nproc || echo 2)

README.md

@@ -8,29 +8,72 @@
 
 [![Tests](https://img.shields.io/github/actions/workflow/status/CogitatorTech/helium/tests.yml?label=tests&style=flat&labelColor=282c34&logo=github)](https://github.com/CogitatorTech/helium/actions/workflows/tests.yml)
 [![CodeFactor](https://img.shields.io/codefactor/grade/github/CogitatorTech/helium?label=code%20quality&style=flat&labelColor=282c34&logo=codefactor)](https://www.codefactor.io/repository/github/CogitatorTech/helium)
-[![Zig Version](https://img.shields.io/badge/Zig-0.14.1-orange?logo=zig&labelColor=282c34)](https://ziglang.org/download/)
+[![Zig Version](https://img.shields.io/badge/Zig-0.15.1-orange?logo=zig&labelColor=282c34)](https://ziglang.org/download/)
 [![Docs](https://img.shields.io/github/v/tag/CogitatorTech/helium?label=docs&color=blue&style=flat&labelColor=282c34&logo=read-the-docs)](https://habedi.github.io/helium/)
 [![Examples](https://img.shields.io/github/v/tag/CogitatorTech/helium?label=examples&color=green&style=flat&labelColor=282c34&logo=zig)](https://github.com/CogitatorTech/helium/tree/main/examples)
 [![Release](https://img.shields.io/github/release/CogitatorTech/helium.svg?label=release&style=flat&labelColor=282c34&logo=github)](https://github.com/CogitatorTech/helium/releases/latest)
 [![License](https://img.shields.io/badge/license-MIT-007ec6?label=license&style=flat&labelColor=282c34&logo=open-source-initiative)](https://github.com/CogitatorTech/helium/blob/main/LICENSE)
 
-A lightweight web framework for Zig
+A lightweight, fast web framework for Zig
 
 </div>
 
 ---
 
-Helium is a small, asynchronous web framework for Zig programming language.
-Its goal is to make it easy to build fast and efficient web applications and services in Zig.
+Helium is a small, configurable web framework for Zig programming language.
+It provides the basic building blocks for creating fast and efficient web applications and services in Zig by composing
+a set of reusable components.
+Helium follows a micro-framework design philosophy, with a small core feature set that could be extended via optional
+middleware and utilities.
 
-### Features
+- **Nothing Hardcoded**: All features are opt-in and configurable
+- **Composable**: Build your application from small, reusable components
+- **Flexible**: Use what you need, ignore what you don't
+- **Minimal Core**: A small, focused API that doesn't get in your way
+- **Zero Magic**: Explicit and predictable behavior
 
-- Full asynchronous operations support
-- Cross-platform compatibility
-- JSON and CBOR support
-- Cookie management and optional session-based authentication mechanism
-- Flexible middleware support (route-specific and global)
-- Express.js-like routing mechanism
+### Core Features
+
+**Routing & Request Handling**
+
+- Express.js-like routing with HTTP method support (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
+- Dynamic route parameters (e.g., `/users/:id`)
+- Query parameter parsing
+- Route grouping with shared prefixes
+- Request body parsing
+
+**Middleware System**
+
+- Global middleware applied to all routes
+- Group-scoped middleware for route collections
+- Route-specific middleware chains
+- Custom middleware support with simple function signatures
+
+**Server Modes**
+
+- Thread pool mode for high concurrency
+- Minimal thread pool with event-driven I/O
+- Configurable worker thread counts
+
+**Built-in Utilities** (all optional)
+
+- **CORS middleware**: Cross-origin resource sharing (allow-all)
+- **Static file serving**: Secure file server with path traversal protection
+- **Logging middleware**: Common log format with timing information
+- **JSON responses**: Built-in JSON serialization support
+
+**Flexibility**
+
+- Generic context type for application state
+- Custom error handlers per application
+- Memory allocator control
+- Type-safe handler functions
+
+See the [ROADMAP.md](ROADMAP.md) for the list of implemented and planned features.
+
+> [!IMPORTANT]
+> Helium is in early development, so bugs and breaking changes are expected.
+> Please use the [issues page](https://github.com/CogitatorTech/Helium/issues) to report bugs or request features.
 
 ---
 

ROADMAP.md

@@ -0,0 +1,180 @@
+## Helium Web Framework Roadmap
+
+This document outlines the development roadmap for Helium, a lightweight, configurable micro web framework for Zig.
+
+> [!IMPORTANT]
+> This roadmap is a living document and may change based on community feedback and evolving needs.
+
+### Philosophy & Design Goals
+
+Helium is designed as a **micro-framework** with these core principles:
+- **Configurability First**: Nothing is hardcoded; everything is opt-in and customizable
+- **Minimal Core**: Keep the core API small and focused
+- **Composability**: Features should be independent and composable
+- **Zero Magic**: Explicit, predictable behavior without hidden abstractions
+- **Performance**: Efficient use of resources with multiple concurrency models
+
+---
+
+### ✅ Implemented Features
+
+#### Core Framework
+- [x] Generic `App` type with custom context support
+- [x] Type-safe request handlers and middleware
+- [x] Configurable memory allocator per application
+- [x] Custom error handler support
+- [x] Multi-mode server (thread pool and event-driven I/O)
+
+#### Routing System
+- [x] Express.js-like routing API
+- [x] HTTP method support (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
+- [x] Dynamic route parameters (e.g., `/users/:id`)
+- [x] Query parameter parsing
+- [x] Route grouping with shared path prefixes
+- [x] Tree-based router for efficient path matching
+
+#### Middleware System
+- [x] Global middleware (applied to all routes)
+- [x] Group-scoped middleware (applied to route groups)
+- [x] Route-specific middleware chains
+- [x] Middleware composition with `next()` pattern
+- [x] Type-safe middleware signatures
+
+#### Built-in Utilities
+- [x] CORS middleware (allow-all origins)
+- [x] Static file server with path traversal protection
+- [x] Common log format middleware with timing
+- [x] JSON response helpers
+
+#### Request/Response
+- [x] Request parameter access (path params, query params)
+- [x] Request body string access
+- [x] Response status code setting
+- [x] Response header management
+- [x] JSON response serialization
+- [x] Plain text responses
+
+---
+
+### 📋 Planned Features
+
+#### 1. Enhanced Routing
+- [ ] Route wildcards (e.g., `/files/*`)
+- [ ] Route matching with regular expressions
+- [ ] Route priority/ordering control
+- [ ] Nested route groups
+- [ ] Route metadata and tagging
+- [ ] Automatic OPTIONS handling per route
+
+#### 2. Request Handling
+- [ ] Multipart form data parsing
+- [ ] File upload handling
+- [ ] Request body size limits (configurable)
+- [ ] Content negotiation helpers
+- [ ] Cookie parsing and setting
+- [ ] Request validation helpers
+- [ ] Custom body parsers (pluggable)
+
+#### 3. Response Enhancements
+- [ ] Response streaming API for large payloads
+- [ ] Request body streaming for file uploads
+- [ ] Template rendering support (pluggable)
+- [ ] Response compression (gzip, deflate, brotli)
+- [ ] ETag support for caching
+- [ ] Conditional requests (If-None-Match, If-Modified-Since)
+- [ ] Server-Sent Events (SSE) support
+- [ ] Chunked transfer encoding
+
+#### 4. Middleware Ecosystem
+- [ ] Configurable CORS middleware (custom origins, methods, headers)
+- [ ] Rate limiting middleware
+- [ ] Authentication middleware (JWT, Bearer, Basic Auth)
+- [ ] Session management middleware
+- [ ] Cookie parsing and management
+- [ ] Request ID tracking
+- [ ] Body parser middleware (JSON, form-urlencoded, multipart)
+- [ ] CSRF protection
+- [ ] Security headers middleware (helmet-style)
+- [ ] Request timeout middleware
+- [ ] Circuit breaker pattern
+
+#### 5. Performance & Scaling
+- [ ] Connection pooling
+- [ ] Request/response pooling
+- [ ] Zero-copy optimizations
+- [ ] HTTP keep-alive connection management
+- [ ] Graceful shutdown support
+- [ ] Health check endpoints
+- [ ] Metrics and monitoring hooks
+
+#### 6. Error Handling
+- [ ] Error recovery middleware
+- [ ] Detailed error responses (development mode)
+- [ ] Error logging integration points
+- [ ] Panic recovery
+- [ ] Structured error types
+
+#### 7. Testing & Development
+- [ ] Test client for integration testing
+- [ ] Mock request/response builders
+- [ ] Development mode with hot reload (external tool integration)
+- [ ] Request/response logging levels
+- [ ] Debug middleware
+
+#### 8. Security
+- [ ] HTTPS/TLS support
+- [ ] Certificate management helpers
+- [ ] Input sanitization helpers
+- [ ] SQL injection prevention utilities
+- [ ] XSS prevention utilities
+- [ ] Rate limiting by IP/user
+- [ ] Request size limits
+
+#### 9. Documentation & Examples
+- [x] Basic examples (simple server, error handling)
+- [x] Route grouping example
+- [ ] REST API example
+- [ ] WebSocket chat example
+- [ ] File upload example
+- [ ] Authentication example
+- [ ] Microservices example
+- [ ] Real-time SSE example
+- [ ] Comprehensive API documentation
+- [ ] Best practices guide
+- [ ] Migration guide from other frameworks
+
+#### 10. Ecosystem Integration
+- [ ] Database connection pooling patterns
+- [ ] ORM integration examples
+- [ ] Message queue integration patterns
+- [ ] Cache integration (Redis, Memcached)
+- [ ] Logging framework integration
+- [ ] OpenTelemetry/tracing support
+
+---
+
+### 🎯 Future Considerations
+
+These features are being considered but not yet prioritized:
+
+- WebSocket support
+- HTTP/2 support
+- HTTP/3 (QUIC) support
+- GraphQL support
+- gRPC support
+- CBOR serialization support
+- Built-in API documentation generation
+- Load balancing support
+- Service mesh integration
+- Admin panel/dashboard
+- Plugin system architecture
+
+---
+
+### Contributing
+
+Want to help implement a feature? Check our [CONTRIBUTING.md](CONTRIBUTING.md) guide!
+
+### Feedback
+
+Have suggestions for the roadmap? Open an issue or discussion on our [GitHub repository](https://github.com/CogitatorTech/helium).