LuciferCore.Platforms 1.1.1

LuciferCore.Platforms

LuciferCore.Platforms is the application-runtime and orchestration layer built on top of the LuciferCore microkernel.

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

Where LuciferCore gives you raw buffers, pooling, DI, and transports, Platforms gives you the attribute-driven ergonomics to actually build servers, handlers, and background workers with them.

Key Features

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

• Ready-made middlewares FirewallMiddleware, RateLimitMiddleware, SessionMiddleware out of the box.

• Life-cycle managers ManagerBase, LogManager, SimulationManager, ManagerWorkerPool for background/orchestration workloads.

• Interactive CLI (LuciferCMD) Console commands like /start servers, /stop managers, plus your own via [ConsoleCommand].

• Bootstrap & config [Config], [Bootstrap], [Plugin] attributes for declarative startup wiring.

Design Philosophy (OOP + DOD, generator + reflection working together)

Convention over inheritance

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.

Compiled hot path

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.

Reflection where it earns its keep

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

This pulls in LuciferCore (>= 6.1.4) as a dependency automatically.

License

LuciferCore.Platforms uses dual licensing:

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

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://lucifercore.pages.dev/
• Store: https://bufmod.lemonsqueezy.com/

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