LuciferCore 2.7.2

LuciferCore

LuciferCore is an all-in-one, high-performance Event-Driven Ecosystem engineered explicitly for modern Modulithic architectures—allowing you to build clean, monolithic business modules that can easily decouple into high-speed microservices later. Designed by thuangf45, it flawlessly bridges the structural elegance of Object-Oriented Programming (OOP) with the brutal execution efficiency of Data-Oriented Design (DOD), leveraging a revolutionary Buffer-Model architecture to push .NET performance to pure hardware limits while guaranteeing maximum CPU Cache Locality and zero-allocation execution.

🚀 Advanced Features (Performance First)

LuciferCore is not just another wrapper; it is a meticulously engineered ecosystem designed to push .NET to its absolute physical limits.

• Modulithic Architecture: Built to support highly cohesive Modulith application blueprints. Design your system as independent, self-contained business modules that share data via lock-free in-memory channels during monolith deployment, or split them into isolated microservice units with zero code changes.
• Next-Gen Foundations: Our reactive Server and Session layers are built upon the robust asynchronous socket foundations of NetCoreServer, while the Manager scheduling system inherits the deterministic execution precision of the Unity Loop architecture.
• Lightweight Ultra-Fast DI: Features an internal, zero-overhead Static Generic Dependency Injection Container (LuciferModel). By completely avoiding runtime Dictionary lookups and resolving component hierarchies via pre-compiled Expression Trees, it automates dependency orchestration at native C# speeds.
• Dual-Engine Smart Pooling: Integrates a hybrid memory recycler that pairs DOD-based ArrayPool<byte> abstractions for flat packet layouts with OOP-based ObjectPool<T> lifecycles (utilizing [ThreadStatic] local stacks) to eliminate Garbage Collection (GC) pressure entirely.
• Attribute-Driven Dispatching: High-speed event routing using high-performance stateless metadata tags including [Server], [Handler], and [WsMessage] for clean, maintainable code.
• Built-in Infrastructure Guardrails: Native interceptors with compile-time embedded safety mechanisms via [RateLimiter], [Authorize], and [Safe] attributes at the individual handler method level.
• Unified Transport Pipeline: Seamlessly orchestrates WSS (WebSocket Secure) and HTTPS transport streams inside a single, unified asynchronous polling loop.

🧠 The Core Philosophy: DOD, OOP Hybridization & Cache Locality

LuciferCore doesn't just bypass Garbage Collection; it actively respects the physical layout of modern CPU memory architectures.

📦 Data-Oriented Design (DOD) & The Buffer-Model Pipeline

Traditional Object-Oriented architectures store entity data scattered across the managed Heap, causing massive pointer-chasing delays (CPU Cache Misses). LuciferCore breaks this barrier by flattening raw network payloads into continuous memory segments using our custom Buffer-Model architecture. Backed by aggressively reused ArrayPool<byte> infrastructures, the framework streams socket data as contiguous sequences of bytes. This guarantees that cold RAM latency is avoided and data is almost always pre-loaded in L1/L2/L3 Cache for instant CPU consumption.

🧩 High-Performance OOP & Smart Ref-Counted ObjectPool

While data layout belongs to DOD, architecture and state management belong to OOP. To handle high-level logic (Sessions, Requests, Responses) cleanly, LuciferCore wraps structural objects into a high-speed, thread-local ObjectPool<T>. Utilizing thread-static stacks, every execution thread can instantly rent and return object frames without context switching or resource contention, keeping the heap pristine.

⚡ Static-Generic Dependency Injection (LuciferModel)

To automate infrastructure without introducing the performance penalties of traditional runtime reflection containers, LuciferCore utilizes a compiled DI approach. During bootstrapper execution, LuciferModel dynamically generates factory functions compiled via Expression Trees. When a module, manager, or pooled packet requires system assets (Loggers, Shared States, Security Contexts), they are directly fed through specialized generic registers, operating at kịch trần machine performance.

⚡ Hardware-Scale Parallelism (Fully Asynchronous)

LuciferCore doesn't just run on multiple threads; it scales with your hardware.

• Lock-Free Execution: Built on fully asynchronous, non-blocking pathways. We eliminate traditional thread synchronization to prevent CPU stalls and context switching.
• Max Core Utilization: The engine is designed to saturate all available CPU cores (or a specific max-core configuration), ensuring true parallel processing of event-driven tasks.
• Core-Aware Scheduling: Optimized for modern multi-core processors, leveraging Async Channels and Lock-free Queues to distribute load across the entire silicon without contention.

🎯 The "Zero-Boilerplate" Workflow

LuciferCore is designed so you can stop being a "plumber" and start being an "architect."

1. Decorate: Mark your classes with [Server], [Handler], [Manager], or [Service].
2. Implement: Write your core logic inside the attributed methods.
3. Run: Call Lucifer.Run().

The ecosystem automatically handles Auto-Discovery, Async Orchestration, and Hardware Saturation. Whether you're building a professional game server, a high-speed security tool, or a custom proxy—you only care about the Payload.

🏎 Performance & Hardware Saturation

LuciferCore doesn't just run code; it occupies the hardware.

• Lock-Free Pipeline: We've eliminated traditional thread synchronization. Data flows through lock-free queues and async channels to prevent CPU stalls.
• Core Affinity & Scaling: By using Lucifer.Optimize(), the framework fine-tune the environment to saturate all available CPU cores, minimizing context-switching.
• Democratic Memory: Our Buffer-Model ensures that every CPU core has "hot" data ready in its local cache, preventing the "memory wall" bottleneck.

🛠 Quick Start Example

1. Define your High-Performance Server & Static Mapping

Simply decorate your class with the [Server] attribute to initialize a specialized server instance.

[Server("ChatServer", 8443)]
public class ChatServer : WssServer
{
    /// <summary>Initializes a new instance of the ChatServer class with specified SSL context, IP address, and port.</summary>
    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    public ChatServer(SslContext context, IPAddress address, int port) : base(context, address, port)
    {
        AddStaticContent(_staticContentPath);
        Cache.Freeze();

        Mapping = new(true)
        {
            { "/",          "/index.html"     },
            { "/404",       "/404.html"       },
            { "/home",      "/home.html"      },
            { "/login",     "/login.html"     },
            { "/register",  "/register.html"  },
            { "/dashboard", "/dashboard.html" },
            { "/search",    "/search.html"    }
        };
        Mapping.Freeze();
    }

    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    public ChatServer(int port) : this(CreateSslContext(), IPAddress.Any, port) { }

    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    protected override ChatSession CreateSession() => new(this);

    [Config("WWW", "assets/client/dev")]
    private static string _staticContentPath { get; set; } = string.Empty;

    [Config("CERTIFICATE", "assets/tools/certificates/server.pfx")]
    private static string s_certPath { get; set; } = string.Empty;

    [Config("CERT_PASSWORD", "RootCA!SecureKey@Example2025Strong")]
    private static string s_certPassword { get; set; } = string.Empty;

    /// <summary>Creates an SSL context by loading a certificate from a specified path with a password.</summary>
    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    public static SslContext CreateSslContext()
    {
#if DEBUG
        return SslContext.CreateDevelopmentContext();
#else
        var cert = X509CertificateLoader.LoadPkcs12FromFile(s_certPath, s_certPassword);
        return new(SslProtocols.Tls12, cert);
#endif
    }
}

2. Configure Session & Automatic Dispatching

Apply session-level rate limiting and automatic dispatching to handlers.

[RateLimiter(10, 1)]
public partial class ChatSession : WssSession
{
    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    public ChatSession(ChatServer server) : base(server) { }

    /// <summary>Handles incoming WebSocket binary messages by dispatching them to the Lucifer dispatcher.</summary>
    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    protected override void OnWsReceived(byte[] buffer, long offset, long size)
        => Lucifer.Dispatch(this, buffer, offset, size);

    /// <summary>Handles incoming HTTP requests by dispatching them to the Lucifer dispatcher.</summary>
    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    protected override void OnReceivedRequest(RequestModel request)
        => Lucifer.Dispatch(this, request);
}

3. Implement a custom Handler with Attribute-Driven Routing

Use attributes to handle messaging, security roles, and rate limiting automatically.

// WebSocket
[Handler("v1", "wss")]
internal class WssHandler : RouteHandler
{
    public ConcurrentQueue<(byte[], long, long)> Messages = new();

    [WsMessage("GetMessage")]
    [Safe("")]
    [RateLimiter(10, 1)]
    [Authorize(UserRole.Guest)]
    public void GetMessage([Session] ChatSession session, [Data] PacketModel data)
    {
        foreach (var (buffer, offset, length) in Messages)
            session.SendBinaryAsync(buffer.AsSpan((int)offset, (int)length));
    }

    [WsMessage("ChatMessage")]
    [Safe("")]
    [RateLimiter(20, 1)]
    [Authorize(UserRole.Guest)]
    public void SendChat([Session] ChatSession session, [Data] PacketModel data)
    {
        using var _ = data;
        ((WssServer)session.Server).MulticastBinary(data.Buffer);
    }

    [WsMessage("Default")]
    [Safe("")]
    [RateLimiter(20, 1)]
    [Authorize(UserRole.Guest)]
    public void Default([Session] ChatSession session, [Data] PacketModel data)
        => throw new NotImplementedException();
}

// HTTP
[Handler("v1", "/api/user")]
internal class HttpsHandler : RouteHandler
{
    [Safe("")][Authorize(UserRole.Guest)][RateLimiter(100, 1)][HttpHead("")]
    protected void HeadHandle([Data] RequestModel request, [Session] HttpsSession session)
        => throw new NotImplementedException();

    [Safe("")][Authorize(UserRole.Guest)][RateLimiter(100, 1)][HttpGet("")]
    protected void GetHandle([Data] RequestModel request, [Session] HttpsSession session)
        => throw new NotImplementedException();

    [Safe("")][Authorize(UserRole.Guest)][RateLimiter(100, 1)][HttpPost("")]
    protected void PostHandle([Data] RequestModel request, [Session] HttpsSession session)
        => throw new NotImplementedException();

    [Safe("")][Authorize(UserRole.Guest)][RateLimiter(100, 1)][HttpPut("")]
    protected void PutHandle([Data] RequestModel request, [Session] HttpsSession session)
        => throw new NotImplementedException();

    [Safe("")][Authorize(UserRole.Guest)][RateLimiter(100, 1)][HttpDelete("")]
    protected void DeleteHandle([Data] RequestModel request, [Session] HttpsSession session)
        => throw new NotImplementedException();

    [Safe("")][Authorize(UserRole.Guest)][RateLimiter(100, 1)][HttpTrace("")]
    protected void TraceHandle([Data] RequestModel request, [Session] HttpsSession session)
        => throw new NotImplementedException();

    [Safe("")][Authorize(UserRole.Guest)][RateLimiter(100, 1)][HttpOptions("")]
    protected void OptionsHandle([Data] RequestModel request, [Session] HttpsSession session)
        => throw new NotImplementedException();
}

4. Manage System Logic with Managers

Extend ManagerBase for heavy, continuously running background tasks with adaptive scheduling.

[Manager("MasterManager")]
public class ManagerMaster : ManagerBase
{
    protected override void Setup()
    {
        TimeDelay  = 1000;
        ErrorDelay = 1000;
    }

    protected override void Update()
    {
        Lucifer.Log(this, "Master is running....");
    }

    protected override void Dispose(bool disposing)
    {
        base.Dispose(disposing);
    }
}

5. Schedule Periodic Tasks with Services

Extend ServiceBase for lightweight periodic work — cleanup, eviction, sync — that runs on a fixed timer without holding a dedicated thread between ticks.

[Service("CleanupService")]
internal sealed class CleanupService : ServiceBase
{
    private readonly int _batchSize = 5_000;
    private readonly ConcurrentDictionary<long, CacheEntry> _entries = new();

    protected override void Setup()
    {
        Interval = TimeSpan.FromMinutes(30);
    }

    protected override void Update()
    {
        var removed = Cleanup(_batchSize);
        Workload = _entries.Count;
    }

    private int Cleanup(int batchSize)
    {
        var now = Lucifer.Time;
        var removed = 0;

        foreach (var kv in _entries)
        {
            if (removed >= batchSize) break;
            if (now - kv.Value.LastAccess > 600)
            {
                if (_entries.TryRemove(kv.Key, out _))
                    removed++;
            }
        }

        return removed;
    }

    protected override void Dispose(bool disposing)
    {
        _entries.Clear();
        base.Dispose(disposing);
    }
}

6. The Optimized Entry Point

One line to rule them all.

In Program.cs:

using LuciferCore.Main;

// Auto-discover and start all [Server], [Handler], [Manager], [Service]
Lucifer.CMD("/run"u8);

This runs a console host. Extend with [ConsoleCommand] attributes for interactive commands, such as:

• /start host – Start host (system)
• /stop host – Stop host (system)
• /restart host – Restart host (system)
• /start servers – Start all servers decorated with [Server(name, port)]
• /stop servers – Stop all servers decorated with [Server(name, port)]
• /restart servers – Restart all servers decorated with [Server(name, port)]
• /start managers – Start all managers decorated with [Manager(name)]
• /stop managers – Stop all managers decorated with [Manager(name)]
• /restart managers – Restart all managers decorated with [Manager(name)]
• /start services – Start all services decorated with [Service(name)]
• /stop services – Stop all services decorated with [Service(name)]
• /restart services – Restart all services decorated with [Service(name)]

Alternatively, you can also define your own command as follows:

/// <summary>Console command to start proxy.</summary>
[ConsoleCommand("/start proxy", "Start proxy")]
[MethodImpl(MethodImplOptions.AggressiveInlining)]
private static void CmdStartProxy() => Start();

/// <summary>Console command to stop proxy.</summary>
[ConsoleCommand("/stop proxy", "Stop proxy")]
[MethodImpl(MethodImplOptions.AggressiveInlining)]
private static void CmdStopProxy() => Stop();

📦 Installation

dotnet add package LuciferCore

📜 License & Community

📜 DUAL-LICENSING NOTICE: LuciferCore is dual-licensed under the strict copyleft AGPL-3.0 License (Open-Source/Evaluation) and a proprietary Commercial License (Enterprise/Closed-Source).

🛒 COMMERCIAL ENTERPRISE LICENSING: If your organization intends to embed LuciferCore within closed-source commercial applications, proprietary products, or SaaS infrastructure, you are legally required to acquire a Commercial License to exempt your codebase from AGPL copyleft obligations. Purchase Commercial License via Lemon Squeezy.

LuciferCore is released under the AGPL-3.0 License by thuangf45.

A sincere thank you to everyone who has trusted and used this framework. Your support is the fuel that keeps this project evolving. I am eagerly looking forward to your contributions—whether through feedback, issue reporting, or pull requests—to help us build a stronger, faster .NET community together.

👤 Author

• Nguyen Minh Thuan (thuangf45)
• Portfolio: thuangf45
• LinkedIn: thuangf45
• GitHub: thuangf45
• Blog: thuangf45
• Email: thuangf45
• NuGet: thuangf45
• Repository: LuciferCore
• Official Documentation: LuciferCore

Pushing the boundaries of .NET performance, one buffer at a time.