LuciferCore 2.1.8

LuciferCore

LuciferCore is an all-in-one, high-performance Event-Driven Ecosystem built on the principles of Data-Oriented Design (DOD). Designed by thuangf45, it leverages a revolutionary Buffer-Model architecture to push .NET performance to hardware limits, ensuring 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 limits.

• Next-Gen Foundations: Our Server and Session layers are built upon the robust principles of NetCoreServer, while the Manager system inherits the precision of the Unity Loop architecture.
• Cutting-Edge Tech Stack: We've evolved these concepts with modern .NET innovations including Async Channels, advanced Object Pooling, and SIMD-accelerated memory copying.
• Zero-Allocation Buffer-Model: Features a custom Span<T> virtualization and pooling system to virtually eliminate Garbage Collection (GC) pressure.
• Attribute-Driven Routing: High-speed dispatching using [Server], [Handler], and [WsMessage] for clean, maintainable code.
• Built-in Security & Control: Native defense mechanisms with [RateLimiter], [Authorize], and [Safe] attributes at the handler level.
• Hybrid Protocols: Seamlessly handle WSS (WebSocket Secure) and HTTPS within the same unified logic.

🧠 The Core Philosophy: DOD & Cache Locality

LuciferCore doesn't just avoid Garbage Collection; it respects the CPU Cache.

• Data-Oriented Design (DOD): We focus on data streams rather than object hierarchies, minimizing pointer chasing and memory fragmentation.
• Buffer-Model Architecture: By treating memory as a contiguous, virtualized pool, we achieve "democratic" memory access. This ensures data is almost always ready in L1/L2/L3 Cache, virtually eliminating RAM latency.
• Zero-Allocation Pipeline: From the raw socket byte to your HandleAction method, the data travels through a pre-pooled, zero-copy pathway.

⚡ 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], or [Manager].
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 Secured WebSocket and Http Handler

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

// WebSocket 
[Handler("v1", "wss")]
internal class WssHandler : WssHandlerBase
{
    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);
        //session.SendBinaryAsync(data.Buffer.AsSpan());
    }

    [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 : HttpsHandlerBase
    {
        [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 automated background tasks and system updates.

 [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. The Optimized Entry Point

One line to rule them all.

In Program.cs:

using LuciferCore.Main;

// Auto-discover and start all decorated Servers/Handlers and run console host
Lucifer.Run();       

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)]

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

📖 Official Documentation: LuciferCore

📜 License & Community

LuciferCore is released under the MIT 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.

📖 Contact & Daily Activity

Stay updated with my daily research, performance benchmarks, and development journey:

• NuGet: thuangf45
• Repository: LuciferCore

👤 Author

• Nguyen Minh Thuan (thuangf45)
• Portfolio: thuangf45
• LinkedIn: thuangf45
• GitHub: thuangf45
• Blog: thuangf45
• Email: thuangf45

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