LuciferCore 5.28.0

LuciferCore

LuciferCore is a high-performance, event-driven framework for .NET.

It is built for modulith architecture: start as one clean monolith, then split modules into microservices later when needed.

LuciferCore combines:

• OOP for clear architecture
• DOD for data speed and memory efficiency

The core idea is a Buffer-Model design to reduce allocations and improve CPU cache usage.

🚀 Key Features

• Modulith-first design
  Build independent business modules in one app. Move to microservices later with minimal changes.

• Fast DI (LuciferModel)
  Uses static-generic patterns and compiled expressions to reduce runtime overhead.

• Smart pooling
  Combines ArrayPool<byte> and ObjectPool<T> to reduce GC pressure.

• Attribute-driven architecture
  Use attributes like [Server], [Handler], [Manager], [Middleware], [Route] for clear structure.

🧠 Design Philosophy (OOP + DOD)

Data-Oriented flow for performance

Network payloads are handled in contiguous buffers to improve memory locality and reduce cache misses.

OOP flow for maintainability

High-level components like Session/Request/Response stay clean and modular.

Compiled DI for low overhead

LuciferModel builds dependency factories ahead of time, avoiding heavy runtime reflection.

⚡ Typical Workflow

1. Decorate classes with attributes ([Server], [Handler], [Manager], [Middleware])
2. Implement your logic
3. Run with:

Lucifer.CMD("/run"u8);

🛠 Quick Start

1) Create server

[Server("ChatServer", 8443)]
public class ChatServer : WssServer
{
    public ChatServer(SslContext context, IPAddress address, int port) : base(context, address, port)
    {
        AddStaticContent(_staticContentPath);
        Cache.Freeze();

        Mapping = new(true)
        {
            { "/", "/index.html" },
            { "/404", "/404.html" }
        };
        Mapping.Freeze();
    }

    public ChatServer(int port) : this(CreateSslContext(), IPAddress.Any, port) { }

    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;

    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) Create session

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

    protected override void OnWsReceived(byte[] buffer, long offset, long size)
    {
        // Handle websocket message
    }

    protected override void OnReceivedRequest(RequestModel request)
        => RouteHandler.Route(request, this);
}

3) Create handler

[Handler("v1", "/api/user")]
internal class HttpsHandler : RouteHandler
{
    [Authorize(UserRole.Guest)]
    [HttpGet("")]
    protected void GetHandle([Data] RequestModel request, [Session] HttpsSession session)
        => throw new NotImplementedException();
}

4) Add middleware

[Middleware("AuthGuard")]
internal sealed class AuthGuardMiddleware : MiddlewareHandler
{
    protected override bool Handle(IRoutable data, SessionTransport session)
        => session.IsAuthenticated;
}

Use it in handler:

[HttpGet("")]
[UseMiddleware("AuthGuard")]
[Authorize(UserRole.Guest)]
public void SendChat([Session] ChatSession session, [Data] PacketModel data)
{
}

5) Add manager

[Manager("MasterManager")]
public class ManagerMaster : ManagerBase
{
    protected override void Setup()
    {
    }

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

6) Program entry point

using LuciferCore.Main;

Lucifer.CMD("/run"u8);

Console Commands

Built-in examples:

• /start managers
• /stop managers
• /restart managers
• /start servers
• /stop servers
• /restart servers

Custom command example:

[ConsoleCommand("/start proxy", "Start proxy")]
private static void CmdStartProxy() => Start();

[ConsoleCommand("/stop proxy", "Stop proxy")]
private static void CmdStopProxy() => Stop();

📦 Installation

dotnet add package LuciferCore

📜 License

LuciferCore uses dual licensing:

• AGPL-3.0 (open-source / evaluation)
• Commercial License (for closed-source or enterprise use)

If your company uses LuciferCore in proprietary products or SaaS, you need a commercial license:

👉 https://bufmod.lemonsqueezy.com/

👤 Author

• Nguyen Minh Thuan (thuangf45)
• Portfolio: https://thuangf45.github.io
• LinkedIn: https://www.linkedin.com/in/thuangf45
• GitHub: https://github.com/thuangf45
• Blog: https://dev.to/thuangf45
• Email: kingnemacc@gmail.com
• NuGet: https://www.nuget.org/profiles/thuangf45
• Repository: https://github.com/thuangf45/LuciferCore
• Documentation: https://bufmod.gitbook.io/lucifercore
• Store: https://bufmod.lemonsqueezy.com/

Pushing .NET performance with practical architecture and efficient memory design.