LuciferCore 2.2.0.1

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], [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 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);
    }

    [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 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.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)]
• /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

📖 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.