LuciferCore 6.0.0-debug

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, hybrid dispatch
  Handlers and Middleware are plain classes — no base class to extend. Decorate them with attributes like [Server], [Handler], [Manager], [Middleware], [Route]. The hot path — route discovery and dispatch — is resolved by a Roslyn Source Generator at compile time; broader wiring such as DI container resolution and config binding still uses reflection where flexibility matters more than raw throughput.

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

Convention over inheritance, generator + reflection working together

Handlers and Middleware are ordinary classes with ordinary constructors — including constructor-injected dependencies like other [Singleton] services. There is no RouteHandler or MiddlewareHandler to derive from. For the request-handling hot path, the LuciferCore.Generators source generator scans your code at compile time, resolves the attributes, and emits a compiled routing table into a [StoreRoute]-marked partial class — no reflection at dispatch time. Outside that hot path, LuciferModel and other extensibility points (dependency resolution, [Config] binding, [Manager]/[ConsoleCommand] discovery) still rely on reflection, since that flexibility matters more there than the last bit of throughput. The two approaches are complementary, not a single blanket choice.

⚡ Typical Workflow

1. Decorate classes with attributes ([Server], [Handler], [Manager], [Middleware], [Singleton])
2. Implement your logic — no base class required
3. Anchor the generated routing table with a single [StoreRoute] partial class
4. 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

public class AgentSession : WsSession
{
    public AgentSession(AgentServer server) : base(server) { }

    protected override void OnReceivedRequest(RequestModel request)
    {
        Lucifer.Info<char>($"[Server Received]: {request.MethodRoute} {request.UrlRoute}");
        AppRoute.Route(request, this); // Generated entry point (see step 5)
    }
}

3) Create handler

Handlers are plain classes — no inheritance required. Dependencies (such as [Singleton] services) are injected through the constructor. Endpoint parameters no longer need [Session]/[Data] markers either — the generator resolves them automatically by type: session-like types (anything assignable to SessionTransport) bind to the current session, and model-like types (RequestModel, PacketModel, or any *Model/*Dto) bind to the incoming payload.

[Handler("v1", "/api/auth")]
public class AuthHandler
{
    private readonly AuthService _authService;

    public AuthHandler(AuthService authService)
    {
        _authService = authService;
    }

    [HttpPost("/login")]
    [Log]
    public void HandleLogin(AgentSession session, RequestModel request)
    {
        using var response = _authService.Login(session, request);
        session.SendResponseAsync(response);
    }

    [HttpPost("/register")]
    [Log]
    public void HandleRegister(AgentSession session, RequestModel request)
    {
        using var response = _authService.Register(session, request);
        session.SendResponseAsync(response);
    }
}

Parameter order doesn't matter — only the type does:

[Handler("v1", "/api/user")]
internal class HttpsHandler
{
    [Authorize("Guest")]
    [HttpGet("")]
    public void GetHandle(RequestModel request, HttpsSession session)
    {
        using var response = Lucifer.Rent<ResponseModel>().MakeGetResponse<char>("Hello");
        session.SendResponseAsync(response);
    }

    [Authorize("Guest")]
    [HttpPost("")]
    public void PostHandle(RequestModel request, HttpsSession session)
        => throw new NotImplementedException();
}

WebSocket/message-based routes work the same way, using [Message("...")] instead of an HTTP verb attribute:

[Handler("v1", "wss")]
internal class WssHandler
{
    [Message("ChatMessage")]
    [Authorize("Guest")]
    public void SendChat(ChatSession session, PacketModel data)
    {
        ((WssServer)session.Server).MulticastBinary<byte>(data.Buffer);
    }
}

4) Add middleware

Middleware is also a plain class — just implement a bool Handle(...) (or Invoke) method. The generator matches it to the middleware name declared in [Middleware("...")] and wires it directly into the compiled dispatch pipeline at compile time; no interface or base class involved. Instance resolution for that middleware (via LuciferModel) still goes through the reflection-based DI container, same as any other registered service.

[Middleware("LogMiddleware")]
public class LogMiddleware
{
    public bool Handle(IRoutable data, SessionTransport session)
    {
        Info<char>("Hello World");
        return true;
    }
}

For frequently reused middleware, wrap it in your own attribute derived from UseMiddlewareAttribute for a cleaner call site:

[AttributeUsage(AttributeTargets.Method, AllowMultiple = true)]
public class LogAttribute : UseMiddlewareAttribute
{
    public LogAttribute() : base("LogMiddleware") { }
}

Use it directly on the handler method:

[HttpGet("/ping")]
[Log]
public void Ping(AgentSession session, RequestModel request)
{
    using var response = Rent<ResponseModel>().MakeCustomResponse<char, char, char>(
        200,
        "HTTP/1.1",
        "application/json",
        new { status = "healthy", framework = "LuciferCore" }.ToJson()
    );

    session.SendResponseAsync(response);
}

Or reference it by name directly via [UseMiddleware("LogMiddleware")] if you don't need a dedicated attribute.

5) Anchor route generation with [StoreRoute]

Declare exactly one partial class and mark it with [StoreRoute]. The generator emits the compiled route maps, DI singleton fields, and the Route(...) entry point into it:

[StoreRoute]
public static partial class AppRoute
{
    // Generated: route maps, compiled pipelines, bootstrap registration
}

6) 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;
    }
}

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