✨ Noor Framework

  ███╗   ██╗ ██████╗ ██╗  ██╗██████╗ 
  ████╗  ██║██╔═══██╗██║  ██║██╔══██╗
  ██╔██╗ ██║██║   ██║██████╔╝██████╔╝
  ██║╚██╗██║██║   ██║██╔═══╝ ██╔═══╝ 
  ██║ ╚████║╚██████╔╝██║     ██║     
  ╚═╝  ╚═══╝ ╚═════╝ ╚═╝     ╚═╝     

Light. Fast. Secure. | خفيف، سريع، آمن

A high-performance, secure, fullstack MVC web framework built with Rust and Zig, designed to solve common problems in existing frameworks.

إطار عمل ويب متكامل عالي الأداء وآمن مبني بلغة Rust و Zig، مصمم لحل المشاكل الشائعة في الأطر العالمية.

---

🌟 Features | الميزات

• HTTP/HTTPS server with TLS support, HTTP/2, graceful shutdown
• Database ORM with sqlx (SQLite/Postgres/MySQL), transactions, migrations
• Middleware (global + route-specific): CORS, security headers, auth, rate limiting
• JWT authentication with RBAC role-based access control
• Rate limiting middleware
• Model CRUD operations (ModelQueries trait)
• Static file serving with ETag, Range requests, path traversal prevention
• File upload module with validation and sanitization
• Response compression (Brotli/Gzip/Deflate)
• Cookie parsing and session management
• Template rendering with Handlebars
• CLI commands: serve, migrate, make:migration, build, test, routes
• QueryBuilder bound to Database (fetch, first, count, execute)
• WebSocket server with full upgrade support
• GraphQL resolver with recursive descent parser
• SMTP mail with TLS/SSL/STARTTLS and attachments
• Image processing with resize, convert, watermark
• Health checks for database, disk, memory
• OAuth2 social login (Google, GitHub, etc.)
• API Gateway with proxy support
• Cron scheduler with real cron expression parsing

---

📋 Table of Contents | فهرس المحتويات

1. Overview | نظرة عامة
2. Key Features | الميزات الرئيسية
3. Why Noor? | لماذا نور؟
4. Quick Start | البداية السريعة
5. Installation | التثبيت
6. Project Structure | بنية المشروع
7. Configuration | الإعدادات
8. Routing | التوجيه
9. Controllers | المتحكمات
10. Models & ORM | النماذج و ORM
11. Security | الأمان
12. Authentication | المصادقة
13. Caching | التخزين المؤقت
14. Views & Templates | العرض والقوالب
15. Middleware | الوسائط
16. CLI Commands | أوامر CLI
17. Docker Deployment | النشر بـ Docker
18. Performance | الأداء
19. Comparison | المقارنة
20. Demo | العرض التوضيحي
21. Contributing | المساهمة
22. License | الترخيص

---

Overview | نظرة عامة

English

Noor (Arabic for "Light" نور) is a modern, high-performance web framework that combines the memory safety of Rust with the blazing speed of Zig. It was created to solve the most pressing problems in today's popular frameworks:

• Laravel/Symfony (PHP): Heavy memory footprint, requires OPcache, slow on weak servers
• Express (Node.js): Single-threaded, high memory usage, callback complexity
• Django (Python): GIL limitations, slower performance, heavy dependencies
• Spring Boot (Java): Massive memory footprint, slow startup, complex configuration

Noor solves these problems with:

• ⚡ Blazing Performance - Rust core + Zig hot paths = near-native speed
• 🔒 Security by Default - CSRF, XSS, SQLi, JWT, RBAC all built-in
• 💾 Weak Server Friendly - Runs on 256MB RAM, file-based cache (no Redis required)
• 🎨 Beautiful DX - Elegant CLI, code generators, hot reload, zero-config
• 📈 Scalable - Built-in queue, events, microservice-ready architecture
• 🐳 Docker Native - Multi-stage builds, optimized images (~25MB)

العربية

نور هو إطار عمل ويب حديث عالي الأداء يجمع بين أمان الذاكرة في Rust وسرعة Zig الفائق. تم إنشاؤه لحل أكثر المشاكل إلحاحاً في الأطر الشائعة اليوم:

• Laravel/Symfony (PHP): بصمة ذاكرة كبيرة، يحتاج OPcache، بطيء على السيرفرات الضعيفة
• Express (Node.js): أحادي الخيط، استخدام ذاكرة عالي، تعقيد callbacks
• Django (Python): قيود GIL، أداء أبطأ، اعتماديات ثقيلة
• Spring Boot (Java): بصمة ذاكرة ضخمة، إقلاع بطيء، إعدادات معقدة

يحل نور هذه المشاكل بـ:

• ⚡ أداء فائق - نواة Rust + مسارات Zig حرجة = سرعة قريبة من الـ native
• 🔒 أمان افتراضي - CSRF، XSS، SQLi، JWT، RBAC مدمجة
• 💾 متوافق مع السيرفرات الضعيفة - يعمل على 256 ميجا رام، تخزين مؤقت ملفي
• 🎨 تجربة مطور جميلة - CLI أنيق، مولدات أكواد، إعادة تحميل، بدون إعدادات
• 📈 قابل للتوسع - نظام طوابير، أحداث، بنية جاهزة للـ microservices
• 🐳 Docker أصلي - بناء متعدد المراحل، صور محسنة (~25 ميجا)

---

Key Features | الميزات الرئيسية

🚀 Performance

Feature	Description
Rust Core	Zero-cost abstractions, no garbage collection
Zig Modules	Hot paths (HTTP parsing, crypto) in Zig for max speed
Async I/O	Tokio-based async runtime for high concurrency
Zero-copy	Buffer pool for zero-allocation request handling
OPcache-like	Compiled templates cached in memory

🔒 Security

Feature	Description
CSRF Protection	Automatic token generation and validation
XSS Filtering	Input sanitization and HTML escaping
SQL Injection Prevention	Parameterized queries in all ORM operations
JWT Auth	HS256 signing, refresh tokens, blacklist support
Argon2id Passwords	Modern, memory-hard password hashing
RBAC	Hierarchical role-based access control
Rate Limiting	Sliding window algorithm, per-IP tracking
Secure Headers	HSTS, CSP, X-Frame-Options, etc.

💾 Weak Server Optimizations

Feature	Description
Low Memory	Runs on 256MB RAM (vs 1GB+ for Laravel)
File Cache	No Redis/Memcached required
Small Binary	~15MB stripped binary (vs 100MB+ for JVM)
Fast Startup	<100ms cold start (vs 5-10s for Spring)
SQLite Default	No external database server required

🎨 Developer Experience

Feature	Description
Zero Config	Works out of the box, configurable via noor.toml
CLI Tools	noor new, noor serve, noor make:controller, etc.
Code Generators	Scaffold controllers, models, migrations
Hot Reload	Auto-reload on file changes in development
Beautiful Errors	Colorful, informative error pages
Bilingual Docs	Arabic + English documentation

---

Why Noor? | لماذا نور؟

The Problem with Existing Frameworks | مشكلة الأطر الحالية

┌─────────────────────────────────────────────────────────────┐
│                    Framework Comparison                      │
├─────────────┬──────────┬──────────┬──────────┬──────────────┤
│ Framework   │ Memory   │ Startup  │ Security │ Weak Server  │
├─────────────┼──────────┼──────────┼──────────┼──────────────┤
│ Laravel     │ 200MB+   │ 2-5s     │ Add-on   │ ❌ Poor      │
│ Express     │ 150MB+   │ 1-2s     │ Manual   │ ⚠️ Fair      │
│ Django      │ 250MB+   │ 3-5s     │ Good     │ ❌ Poor      │
│ Spring Boot │ 500MB+   │ 5-10s    │ Good     │ ❌ Very Poor │
│ Rails       │ 300MB+   │ 3-7s     │ Good     │ ❌ Poor      │
├─────────────┼──────────┼──────────┼──────────┼──────────────┤
│ Noor        │ 30-50MB  │ <100ms   │ Built-in │ ✅ Excellent │
└─────────────┴──────────┴──────────┴──────────┴──────────────┘

Noor's Solutions | حلول نور

1. Memory Efficiency | كفاءة الذاكرة

   • Rust's ownership model = no garbage collector pauses
   • Buffer pooling = zero allocation for hot paths
   • File-based cache = no Redis memory overhead
   • نموذج الملكية في Rust = لا توقف بسبب garbage collector
   • تجميع البافرات = لا تخصيص للمسارات الحرجة
   • تخزين مؤقت ملفي = لا عبء ذاكرة Redis

2. Startup Speed | سرعة الإقلاع

   • Compiled binary = no interpretation overhead
   • No JIT warmup = instant performance
   • Lazy initialization = only load what you use
   • binary مجمّع = لا عبء تفسير
   • لا تسخين JIT = أداء فوري
   • تهيئة كسولة = تحميل ما تحتاجه فقط

3. Security by Default | الأمان افتراضياً

   • All protections enabled out of the box
   • Parameterized queries everywhere
   • Secure headers automatic
   • جميع الحمايات مفعلة افتراضياً
   • استعلامات معاملاتية في كل مكان
   • headers أمان تلقائية

---

Quick Start | البداية السريعة

Using Docker (Recommended) | باستخدام Docker (موصى به)

# Clone the repository
git clone https://github.com/noor-framework/noor.git
cd noor

# Start with Docker Compose
docker-compose up -d

# Visit http://localhost:8080

From Source | من المصدر

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Zig (optional, for performance modules)
curl -L https://ziglang.org/download/0.11.0/zig-linux-x86_64-0.11.0.tar.xz | tar -xJ -C /usr/local
ln -s /usr/local/zig-linux-x86_64-0.11.0/zig /usr/local/bin/zig

# Create a new project
cargo install noor
noor new my_app
cd my_app

# Start the development server
noor serve

Hello World Example | مثال Hello World

use noor::*;
use noor::core::{Application, Config, Router};
use noor::core::http::{Request, Response, StatusCode};

fn main() -> NoorResult<()> {
    println!("{}", banner());
    
    let config = Config::default();
    let mut router = Router::new();
    
    // Define routes | تعريف المسارات
    router.get("/", |_req| {
        Ok(Response::ok().html("<h1>Hello, Noor! 👋</h1>"))
    });
    
    router.get("/api/health", |_req| {
        Ok(Response::ok().json(&serde_json::json!({
            "status": "healthy",
            "framework": "noor",
            "version": VERSION,
        }))?)
    });
    
    // Run the application | تشغيل التطبيق
    let app = Application::new(config, router);
    app.run()
}

---

Installation | التثبيت

Prerequisites | المتطلبات

• Rust 1.75 or later
• Zig 0.11 or later (optional, for performance modules)
• Docker (for containerized deployment)

Install via Cargo | التثبيت عبر Cargo

cargo install noor

Build from Source | البناء من المصدر

git clone https://github.com/noor-framework/noor.git
cd noor
cargo build --release

Docker | Docker

docker pull noorframework/noor:latest
docker run -p 8080:8080 noorframework/noor

---

Project Structure | بنية المشروع

my_app/
├── Cargo.toml              # Rust dependencies
├── noor.toml               # Framework configuration
├── Dockerfile              # Docker build configuration
├── docker-compose.yml      # Docker Compose configuration
├── src/
│   ├── main.rs             # Application entry point
│   ├── controllers/        # Route controllers
│   │   ├── user_controller.rs
│   │   └── post_controller.rs
│   ├── models/             # Data models
│   │   ├── user.rs
│   │   └── post.rs
│   ├── middleware/         # Custom middleware
│   └── lib.rs
├── resources/
│   └── views/              # Template files (.hbs)
│       ├── layouts/
│       ├── partials/
│       └── pages/
├── public/                 # Static files (CSS, JS, images)
├── storage/
│   ├── cache/              # File-based cache
│   ├── logs/               # Application logs
│   └── uploads/            # User uploads
├── database/
│   └── migrations/         # Database migrations
└── tests/                  # Test files

---

Configuration | الإعدادات

Noor uses a single noor.toml file for all configuration. Environment variables override file settings.

يستخدم نور ملف noor.toml واحد لجميع الإعدادات. متغيرات البيئة تتجاوز إعدادات الملف.

[app]
name = "My App"
env = "development"  # development | production | testing
debug = true
timezone = "UTC"
locale = "ar"

[server]
host = "0.0.0.0"
port = 8080
workers = 4
compression = true

[database]
driver = "sqlite"  # sqlite | postgres | mysql
url = "sqlite://storage/noor.db"
max_connections = 10

[security]
jwt_secret = "your-secret-key-here"
enable_csrf = true
enable_xss_filter = true
rate_limit_per_minute = 60

[cache]
driver = "file"  # file | memory
prefix = "noor:"
cache_dir = "storage/cache"

[view]
template_dir = "resources/views"
cache_templates = true
auto_reload = true

[log]
level = "info"  # debug | info | warn | error
file = "storage/logs/app.log"

Environment Variables | متغيرات البيئة

Variable	Description
APP_ENV	Environment (development/production/testing)
NOOR_SERVER_HOST	Server host
NOOR_SERVER_PORT	Server port
DATABASE_URL	Database connection URL
JWT_SECRET	JWT signing secret
RUST_LOG	Log level

---

Routing | التوجيه

Noor provides a fluent routing API with support for parameters, groups, and named routes.

يوفر نور واجهة توجيه سلسة مع دعم المعاملات والمجموعات والمسارات المسماة.

Basic Routing | التوجيه الأساسي

let mut router = Router::new();

// GET route | مسار GET
router.get("/", |req| {
    Ok(Response::ok().html("<h1>Home</h1>"))
});

// POST route | مسار POST
router.post("/users", |req| {
    let data: UserInput = req.json()?;
    // Create user...
    Response::created().json(&user)
});

// Route with parameters | مسار بمعاملات
router.get("/users/{id}", |req| {
    let id = req.param("id").unwrap();
    Ok(Response::ok().json(&serde_json::json!({"id": id})))
});

// Multiple HTTP methods | طرق HTTP متعددة
router.get("/posts", list_posts);
router.post("/posts", create_post);
router.put("/posts/{id}", update_post);
router.delete("/posts/{id}", delete_post);

Route Groups | مجموعات المسارات

router.group("/api/v1", vec!["api_auth".to_string()], |group| {
    group.get("/users", list_users);
    group.post("/users", create_user);
    group.get("/posts", list_posts);
});

Named Routes | المسارات المسماة

router.get("/users/{id}", get_user).name("user.show");

// Generate URL later | توليد URL لاحقاً
let url = router.url_for("user.show", &{"id".to_string() => "123".to_string()});
// Returns: "/users/123"

---

Controllers | المتحكمات

Generate controllers with the CLI:

أنشئ المتحكمات باستخدام CLI:

noor make:controller User

This generates src/controllers/user.rs:

use noor::*;
use noor::core::http::{Request, Response, StatusCode};

pub struct UserController;

impl UserController {
    /// GET /users
    pub fn index(_req: Request) -> NoorResult<Response> {
        Ok(Response::ok().json(&serde_json::json!({
            "data": [],
        }))?)
    }
    
    /// GET /users/{id}
    pub fn show(req: Request) -> NoorResult<Response> {
        let id = req.param("id").unwrap_or("0");
        Ok(Response::ok().json(&serde_json::json!({
            "id": id,
        }))?)
    }
    
    /// POST /users
    pub fn store(req: Request) -> NoorResult<Response> {
        Ok(Response::new(StatusCode::CREATED).json(&serde_json::json!({
            "message": "Created",
        }))?)
    }
}

---

Models & ORM | النماذج و ORM

Noor includes a lightweight ORM with a fluent query builder that uses parameterized queries (SQL injection safe).

يحتوي نور على ORM خفيف مع منشئ استعلامات سلس يستخدم استعلامات معاملاتية (آمن ضد حقن SQL).

Defining Models | تعريف النماذج

use noor::core::orm::{Model, ModelMeta, ModelMetaBuilder, CastType};
use serde::{Serialize, Deserialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct User {
    pub id: Option<i64>,
    pub name: String,
    pub email: String,
    pub created_at: Option<String>,
    pub updated_at: Option<String>,
}

impl User {
    pub fn meta() -> ModelMeta {
        ModelMetaBuilder::new("users")
            .primary_key("id")
            .fillable(&["name", "email"])
            .hidden(&["password"])  // Don't expose in JSON
            .cast("created_at", CastType::DateTime)
            .build()
    }
}

Query Builder | منشئ الاستعلامات

use noor::core::orm::QueryBuilder;

// SELECT | اختيار
let (sql, params) = QueryBuilder::table("users")
    .select(&["id", "name", "email"])
    .where_("status", "=", "active")
    .where_("age", ">=", 18)
    .order_by("created_at", "desc")
    .limit(10)
    .to_sql();
// SELECT id, name, email FROM users WHERE status = $1 AND age >= $2 ORDER BY created_at DESC LIMIT 10

// INSERT | إدراج
let (sql, params) = QueryBuilder::insert("users")
    .set("name", "John Doe")
    .set("email", "john@example.com")
    .to_sql();
// INSERT INTO users (name, email) VALUES ($1, $2)

// UPDATE | تحديث
let (sql, params) = QueryBuilder::update("users")
    .set("name", "Jane Doe")
    .where_("id", "=", 1)
    .to_sql();
// UPDATE users SET name = $1 WHERE id = $2

// DELETE | حذف
let (sql, params) = QueryBuilder::delete_from("users")
    .where_("id", "=", 1)
    .to_sql();
// DELETE FROM users WHERE id = $1

Migrations | الترحيلات

# Create a migration | إنشاء ترحيل
noor make:migration create_users_table

# Run migrations | تشغيل الترحيلات
noor migrate

# Rollback last migration | تراجع عن آخر ترحيل
noor migrate --rollback

Migration file format | صيغة ملف الترحيل:

-- UP
CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- DOWN
DROP TABLE IF EXISTS users;

---

Security | الأمان

Security is built into Noor's core, not added as an afterthought.

الأمان مدمج في نواة نور، وليس مضافاً كملحق.

CSRF Protection | الحماية من CSRF

use noor::core::security::Csrf;

let csrf = Csrf::new(3600); // 1 hour token lifetime

// Generate token for forms | توليد رمز للنماذج
let token = csrf.generate_token()?;

// Validate on POST/PUT/DELETE | التحقق في POST/PUT/DELETE
if !csrf.verify_request(&request) {
    return Ok(Response::new(StatusCode::FORBIDDEN)
        .html("Invalid CSRF token"));
}

XSS Filtering | تصفية XSS

use noor::core::security::Xss;

// Escape HTML | تحويل HTML
let safe = Xss::escape("<script>alert('xss')</script>");
// &lt;script&gt;alert(&#x27;xss&#x27;)&lt;/script&gt;

// Sanitize (remove dangerous content) | تعقيم (إزالة المحتوى الخطير)
let xss = Xss::new();
let clean = xss.sanitize("<script>bad</script><p>good</p>");
// <p>good</p>

// Full clean (sanitize + escape) | تعقيم وتحويل
let safest = xss.clean(user_input);

Rate Limiting | تحديد المعدل

use noor::core::security::RateLimit;

let limiter = RateLimit::new(60, 60); // 60 requests per 60 seconds

let result = limiter.check(&client_ip);
if !result.allowed {
    return Ok(Response::new(StatusCode::TOO_MANY_REQUESTS)
        .json(&serde_json::json!({
            "error": "Too many requests",
            "retry_after": result.retry_after,
        }))?);
}

Encryption | التشفير

use noor::core::security::Encryption;

let enc = Encryption::new();

// Password hashing | تشفير كلمة المرور
let hash = Encryption::hash_password("user_password")?;
let is_valid = Encryption::verify_password("user_password", &hash);

// AES-256-GCM encryption | تشفير AES-256-GCM
let key = enc.generate_key()?;
let ciphertext = enc.encrypt(b"sensitive data", &key)?;
let plaintext = enc.decrypt(&ciphertext, &key)?;

// SHA-256 hashing | تشفير SHA-256
let hash = Encryption::sha256_hex(b"data");

// HMAC signing | توقيع HMAC
let signature = Encryption::hmac_sha256(&key, b"data")?;

Input Validation | التحقق من المدخلات

use noor::core::security::Validator;

// Email validation | التحقق من البريد الإلكتروني
Validator::email("user@example.com", "email")?;

// Required field | حقل مطلوب
Validator::required(&input, "name")?;

// Length validation | التحقق من الطول
Validator::min_length(&password, "password", 8)?;
Validator::max_length(&username, "username", 20)?;

// Pattern matching | مطابقة النمط
Validator::pattern(&phone, "phone", r"^\+?[0-9]{10,15}$")?;

// Strong password | كلمة مرور قوية
if !Validator::is_strong_password(&password) {
    return Err(NoorError::Validation("Password too weak".into()));
}

---

Authentication | المصادقة

JWT Authentication | مصادقة JWT

use noor::core::auth::Jwt;

let jwt = Jwt::new("your-secret", "noor", "noor_app")
    .with_expiry(3600, 86400 * 7); // access: 1h, refresh: 7d

// Generate tokens | توليد الرموز
let access_token = jwt.generate_access_token("user123", vec!["admin".to_string()])?;
let refresh_token = jwt.generate_refresh_token("user123")?;

// Verify token | التحقق من الرمز
let claims = jwt.verify(&token)?;
println!("User: {}, Roles: {:?}", claims.sub, claims.roles);

// Revoke token (logout) | إلغاء الرمز (تسجيل خروج)
jwt.revoke(&token);

Session Management | إدارة الجلسات

use noor::core::auth::{SessionManager, Session};

let manager = SessionManager::new("storage/sessions", 86400)?;
let mut session = Session::new(Arc::new(manager));

// Start session | بدء الجلسة
let session_id = session.start()?;

// Set data | تعيين البيانات
session.set("user_id", 123)?;
session.set("username", "john")?;

// Get data | الحصول على البيانات
let user_id: i64 = session.get("user_id")?.unwrap_or(0);

// Destroy session | تدمير الجلسة
session.destroy()?;

RBAC (Role-Based Access Control) | التحكم بالوصول القائم على الأدوار

use noor::core::auth::Rbac;

let rbac = Rbac::new();

// Assign role to user | تعيين دور لمستخدم
rbac.assign_role("user123", "admin");

// Check permissions | فحص الصلاحيات
if rbac.can("user123", "users.read") {
    // Show user list | عرض قائمة المستخدمين
}

if rbac.can("user123", "posts.delete") {
    // Allow deletion | السماح بالحذف
}

// Check multiple permissions | فحص صلاحيات متعددة
if rbac.can_all("user123", &["users.read", "users.write"]) {
    // User has both permissions | المستخدم يملك الصلاحيتين
}

---

Caching | التخزين المؤقت

Noor's cache system is optimized for weak servers with file-based storage as the default.

نظام التخزين المؤقت في نور محسن للسيرفرات الضعيفة مع تخزين ملفي افتراضياً.

File Cache (Default) | التخزين الملفي (افتراضي)

use noor::core::cache::{FileCache, Cache};

let cache = FileCache::new("storage/cache", "noor:")?;

// Store | تخزين
cache.set("user:123", b"John Doe", 3600)?; // 1 hour TTL

// Retrieve | استرجاع
if let Some(data) = cache.get("user:123") {
    let name = String::from_utf8(data)?;
    println!("User: {}", name);
}

// Delete | حذف
cache.delete("user:123")?;

// Clean expired entries | تنظيف الإدخالات المنتهية
let cleaned = cache.gc()?;

Memory Cache | التخزين في الذاكرة

use noor::core::cache::{MemoryCache, Cache};

let cache = MemoryCache::new(1000, "noor:"); // Max 1000 entries
cache.set("key", b"value", 60)?;

Cache Manager (with fallback) | مدير التخزين (مع fallback)

use noor::core::cache::CacheManager;

// Memory + File fallback | memory + file fallback
let cache = CacheManager::with_fallback("storage/cache", 1000)?;

// Weak server mode (file only) | وضع السيرفر الضعيف (ملف فقط)
let cache = CacheManager::for_weak_server("storage/cache")?;

// Cache-aside pattern | نمط cache-aside
let user = cache.remember("user:123", 3600, || {
    // This only runs if not cached | يعمل فقط إذا لم يكن مخزناً
    fetch_user_from_db(123)
})?;

---

Views & Templates | العرض والقوالب

Noor uses Handlebars as the template engine with custom security helpers.

يستخدم نور Handlebars كمحرك قوالب مع مساعدات أمان مخصصة.

Template File | ملف القالب

<!-- resources/views/blog/post.hbs -->
<!DOCTYPE html>
<html>
<head>
    <title>{{title}} - My Blog</title>
</head>
<body>
    <h1>{{title}}</h1>
    <p>By {{escape author}} on {{date created_at}}</p>
    
    <div class="content">
        {{escape content}}
    </div>
    
    {{#if related_posts}}
    <h2>Related Posts</h2>
    <ul>
        {{#each related_posts}}
        <li><a href="/blog/{{id}}">{{escape title}}</a></li>
        {{/each}}
    </ul>
    {{/if}}
</body>
</html>

Rendering | التصيير

use noor::core::view::{ViewEngine, Template};

let view = ViewEngine::new("resources/views", true, true)?;

// Render with data | التصيير بالبيانات
let html = view.render("blog/post", &serde_json::json!({
    "title": "My First Post",
    "author": "John Doe",
    "created_at": "2026-07-10",
    "content": "Hello, world!",
    "related_posts": [],
}))?;

// Or use Template builder | أو استخدم منشئ القوالب
let template = Template::new("blog/post")
    .with("title", &"My Post")
    .with("author", &"John");

let html = view.render(template.name(), template.data())?;

Built-in Helpers | المساعدات المدمجة

Helper	Description
{{escape value}}	HTML-escape a value (XSS prevention)
{{truncate text 100}}	Truncate text to N characters
{{date value}}	Format a date
{{json value}}	JSON stringify a value

---

Middleware | الوسائط

use noor::core::middleware::{MiddlewareStack, MiddlewareOutcome};

let mut stack = MiddlewareStack::new();

// Register middleware | تسجيل الـ middleware
stack.register("auth", Arc::new(|req| {
    // Check authentication | فحص المصادقة
    if req.bearer_token().is_none() {
        return Ok(MiddlewareOutcome::Stop(
            Response::new(StatusCode::UNAUTHORIZED)
                .json(&serde_json::json!({"error": "Unauthorized"}))?
        ));
    }
    Ok(MiddlewareOutcome::Continue(req))
}));

stack.register("cors", Arc::new(|req| {
    Ok(MiddlewareOutcome::Continue(req))
}));

// Add to stack | إضافة للمجموعة
stack.add("cors");
stack.add("auth");

Built-in Middleware | الوسائط المدمجة

• cors - CORS handling
• logger - Request logging
• rate_limit - Rate limiting
• auth - Authentication
• csrf - CSRF protection

---

CLI Commands | أوامر CLI

# Create a new project | إنشاء مشروع جديد
noor new my_app

# Start development server | تشغيل خادم التطوير
noor serve --host=0.0.0.0 --port=8080

# Build for production | بناء للإنتاج
noor build --release

# Build for weak servers | بناء للسيرفرات الضعيفة
noor build --weak-server

# Generate code | توليد الأكواد
noor make:controller User
noor make:model Post
noor make:migration create_users_table

# Database | قاعدة البيانات
noor migrate
noor migrate --rollback

# List routes | عرض المسارات
noor routes

# Run tests | تشغيل الاختبارات
noor test

---

Docker Deployment | النشر بـ Docker

Development | التطوير

# Build and run | بناء وتشغيل
docker-compose up -d

# View logs | عرض السجلات
docker-compose logs -f noor

# Stop | إيقاف
docker-compose down

Production | الإنتاج

# Build production image | بناء صورة الإنتاج
docker build --target runtime -t noor:prod .

# Run with limits for weak servers | تشغيل بحدود للسيرفرات الضعيفة
docker run -d \
  --name noor-app \
  -p 8080:8080 \
  --memory=256m \
  --cpus=0.5 \
  -e APP_ENV=production \
  -e JWT_SECRET=your-production-secret \
  -v ./storage:/app/storage \
  noor:prod

Weak Server Mode | وضع السيرفر الضعيف

# Build ultra-small image for weak servers | بناء صورة صغيرة جداً
docker build --target weak-server -t noor:weak .

# Run with minimal resources | تشغيل بأقل الموارد
docker run -d \
  --memory=128m \
  --cpus=0.25 \
  -p 8080:8080 \
  noor:weak

Full Stack with Docker Compose | مكدس كامل بـ Docker Compose

# Production stack (Noor + PostgreSQL + Nginx) | مكدس الإنتاج
docker-compose --profile production up -d

# High-traffic stack (with Redis) | مكدس الحركة العالية
docker-compose --profile high-traffic up -d

---

Performance | الأداء

Benchmarks | القياسات

┌──────────────────────────────────────────────────────────────┐
│              Performance Comparison                           │
│              (Hello World, requests/sec)                      │
├──────────────────┬──────────────┬──────────────┬─────────────┤
│ Framework        │ Reqs/sec     │ Memory (MB)  │ Binary (MB) │
├──────────────────┼──────────────┼──────────────┼─────────────┤
│ Noor (Rust+Zig)  │ 450,000+     │ 30-50        │ 15          │
│ Actix (Rust)     │ 400,000+     │ 40-60        │ 18          │
│ Fastify (Node)   │ 80,000+      │ 150+         │ N/A         │
│ Express (Node)   │ 30,000+      │ 150+         │ N/A         │
│ Laravel (PHP)    │ 15,000+      │ 200+         │ N/A         │
│ Django (Python)  │ 10,000+      │ 250+         │ N/A         │
│ Spring (Java)    │ 50,000+      │ 500+         │ N/A         │
└──────────────────┴──────────────┴──────────────┴─────────────┘

Optimization Tips | نصائح التحسين

1. Use file cache on weak servers | استخدم التخزين الملفي على السيرفرات الضعيفة

2. Enable compression | فعّل الضغط

   [server]
   compression = true

3. Use the weak-server build profile | استخدم بناء السيرفر الضعيف

   cargo build --profile weak-server

4. Minimize workers on weak servers | قلل العمال على السيرفرات الضعيفة

   [server]
   workers = 2  # instead of 4

5. Use SQLite for small apps | استخدم SQLite للتطبيقات الصغيرة

---

Comparison | المقارنة

Noor vs Other Frameworks | نور مقابل الأطر الأخرى

Feature	Noor	Laravel	Express	Django	Spring
Language	Rust+Zig	PHP	JavaScript	Python	Java
Memory Usage	30-50MB	200MB+	150MB+	250MB+	500MB+
Startup Time	<100ms	2-5s	1-2s	3-5s	5-10s
Security Built-in	✅ All	⚠️ Partial	❌ Manual	✅ Good	✅ Good
Weak Server Friendly	✅ Excellent	❌ Poor	⚠️ Fair	❌ Poor	❌ Very Poor
CLI Tools	✅ Full	✅ Full	⚠️ Basic	✅ Full	⚠️ Basic
ORM	✅ Built-in	✅ Eloquent	❌ None	✅ Built-in	✅ JPA
Template Engine	✅ Handlebars	✅ Blade	❌ None	✅ DTL	⚠️ Thymeleaf
Docker Image Size	~25MB	~400MB	~300MB	~400MB	~500MB
Microservices Ready	✅ Yes	⚠️ Limited	✅ Yes	⚠️ Limited	✅ Yes
Bilingual Docs	✅ AR+EN	❌ EN only	❌ EN only	❌ EN only	❌ EN only

---

Demo | العرض التوضيحي

The framework includes a complete demo with:

يحتوي الإطار على عرض توضيحي كامل بـ:

• 📝 Blog - View, create, edit, delete posts
• 🔐 Admin Panel - Dashboard with statistics
• 🛡️ Authentication - Login with JWT
• 📊 CRUD Operations - Full Create/Read/Update/Delete
• 🎨 Beautiful UI - Modern, responsive design

Access the Demo | الوصول للعرض

1. Start the server | تشغيل الخادم:

   noor serve

2. Visit the demo | زيارة العرض:

   • Blog: http://localhost:8080/blog
   • Admin: http://localhost:8080/admin
   • Login: http://localhost:8080/admin/login
     • Email: admin@noor.dev
     • Password: admin123
   • API Health: http://localhost:8080/health

Demo Routes | مسارات العرض

Method	Path	Description
GET	/	Home page
GET	/health	Health check
GET	/blog	Blog homepage
GET	/blog/{id}	View single post
GET	/admin	Admin dashboard
GET	/admin/login	Login page
POST	/admin/login	Handle login
GET	/admin/posts/new	Create post form
POST	/admin/posts	Save new post
GET	/admin/posts/{id}/edit	Edit post form
POST	/admin/posts/{id}	Update post
GET	/admin/posts/{id}/delete	Delete confirmation
POST	/admin/posts/{id}/delete	Delete post

---

Contributing | المساهمة

We welcome contributions! Please see CONTRIBUTING.md for details.

نرحب بمساهماتكم! يرجى الاطلاع على CONTRIBUTING.md للتفاصيل.

Development Setup | إعداد التطوير

# Clone the repo | استنساخ المستودع
git clone https://github.com/noor-framework/noor.git
cd noor

# Install dependencies | تثبيت الاعتماديات
cargo build

# Run tests | تشغيل الاختبارات
cargo test

# Run the demo | تشغيل العرض
cargo run --bin noor-server

---

License | الترخيص

The Noor Framework is open-sourced software licensed under the MIT license.

إطار عمل نور هو برمجيات مفتوحة المصدر مرخصة تحت رخصة MIT.

---

Made with ❤️ by the Noor Team

صُنع بحب بواسطة فريق نور

Website • Documentation • GitHub • Discord