Bevezetés

A KonaBox2 egy átfogó enterprise .NET framework és NuGet csomag könyvtár, amelyet ASP.NET Core alkalmazások fejlesztésének gyorsítására terveztünk. Moduláris, production-ready alapot biztosít modern webalkalmazások építéséhez.

• Authentikáció és token kezelés (OIDC, Keycloak integráció)
• Backend-for-Frontend (BFF) pattern YARP reverse proxy-val
• Entity Framework Core alapú adathozzáférés soft-delete és audit támogatással
• Globális exception handling és szabványosított hibaválaszok
• Production-ready naplózás Serilog és Grafana Loki integrációval
• FluentValidation integráció

A KonaBox2 keretrendszerben összegyűjtött és kidolgozott komponensek felgyorsítják a fejlesztést, és elkerülhetővé teszik az ismétlődő boilerplate kód írását. A modulok külön-külön vagy együtt is használhatók.

KonaBox2.Core - Alapvető absztrakciók

A Core csomag az alapvető absztrakciókat és kivételeket tartalmazza, külső függőségek nélkül. Ez biztosítja az összes többi modul alapját.

using KonaBox2.Core;

Kivétel Hierarchia

ICurrentUser Interface

Absztrakció az authentikált felhasználói kontextus eléréséhez:

public interface ICurrentUser
{
    int UserId { get; }
    int TenantId { get; }
}

IAuditableEntity Interface

Standard interfész az audit tracking-et igénylő entitásokhoz:

public interface IAuditableEntity
{
    DateTime LetrehozasDatuma { get; set; }
    int LetrehozoId { get; set; }
    DateTime UtolsoModositasDatuma { get; set; }
    int UtolsoModositoId { get; set; }
}

KonaBox2.Data - Adathozzáférési réteg

Entity Framework Core 9 alapú adathozzáférési réteg, beépített soft-delete támogatással, automatikus audit tracking-gel és hasznos LINQ kiterjesztésekkel.

using KonaBox2.Data;

BaseEntity

Alapentitás beépített funkciókkal:

public abstract class BaseEntity : IAuditableEntity
{
    public int Id { get; set; }
    public bool ToroltFl { get; set; }  // Soft-delete flag
    public DateTime LetrehozasDatuma { get; set; }
    public int LetrehozoId { get; set; }
    public DateTime UtolsoModositasDatuma { get; set; }
    public int UtolsoModositoId { get; set; }
}

AuditableDbContext

EF Core alaposztály, amely automatikusan rögzíti a létrehozás/módosítás időbélyegeit, nyomon követi a felhasználót, és globális soft-delete query filtereket alkalmaz.

Query Extensions

Használati példa

// Entitás lekérése NotFoundException-nel, ha nem létezik
var user = await _context.Users
    .Where(u => u.Id == userId)
    .SingleOrNotFoundAsync();

// Lapozás
var pagedResult = await _context.Products
    .OrderBy(p => p.Name)
    .Paginate(page: 1, pageSize: 20)
    .ToListAsync();

KonaBox2.Api - Middleware és Validáció

ASP.NET Core middleware-ek és segédeszközök, beleértve a globális exception handling-et, current user middleware-t és JSON konvertereket.

using KonaBox2.Api;

Exception Handling Middleware

Globális kivételkezelés szabványosított JSON hibaválaszokkal:

public void Configure(IApplicationBuilder app)
{
    app.UseExceptionHandling();  // Első middleware legyen!
}

Current User Middleware

Felhasználói identitás kinyerése HTTP header-ekből:

app.UseCurrentUser(options =>
{
    options.UserIdHeaderName = "X-User-Id";
    options.TenantIdHeaderName = "X-Tenant-Id";
});

JSON Konverterek

FluentValidation Integráció

services.AddFluentValidationExtensions();

KonaBox2.Auth - Token Kezelés

Token kezelés és frissítés middleware, amely proaktívan frissíti a tokeneket a lejárat előtt, nem blokkoló módon működik.

using KonaBox2.Auth;

Token Refresh Middleware

• Konfigurálható buffer idő a frissítési döntésekhez
• Nem blokkoló design (frissítési hibák nem buktatják el a kérést)
• Invalid grant detektálás és kezelés
• Automatikus session kijelentkezés invalid grant esetén (opcionális)

services.AddTokenRefresh(options =>
{
    options.RefreshBufferSeconds = 60;  // Frissítés 60 mp-cel lejárat előtt
    options.SignOutOnInvalidGrant = true;
});

app.UseTokenRefresh();

KonaBox2.BFF - Backend-for-Frontend

Teljes Backend-for-Frontend implementáció OIDC authentikációval, Keycloak integrációval és YARP reverse proxy támogatással.

using KonaBox2.BFF;

OIDC Authentikáció Keycloak-kal

• Teljes OpenID Connect flow integráció
• Szerver-oldali session kezelés in-memory ticket store-ral
• Cookie-alapú authentikáció (HttpOnly, SecurePolicy konfigurálható)
• Sliding session expiration támogatás
• Backchannel logout (elkerüli az URI hossz problémákat nagy ID tokenekkel)

YARP Reverse Proxy Integráció

• Access token továbbítás backend szolgáltatásokhoz
• Claim-to-header mapping felhasználói kontextus propagáláshoz
• Token caching fix az ASP.NET Core auth result caching problémákra

BFF Végpontok

Konfiguráció

services.AddBff(options =>
{
    options.Authority = "https://keycloak.example.com/realms/myrealm";
    options.ClientId = "my-client";
    options.ClientSecret = "my-secret";
    options.CookieName = "MyApp.Auth";
    options.SessionTimeout = TimeSpan.FromHours(8);
});

app.UseBff();

User Sync Handler

Bővíthető interface egyéni felhasználói szinkronizálási logikához:

public class MyUserSyncHandler : IUserSyncHandler
{
    public async Task<IEnumerable<Claim>> OnUserAuthenticated(
        ClaimsPrincipal principal,
        CancellationToken ct)
    {
        // Egyéni claim-ek hozzáadása OIDC authentikáció után
        var userId = principal.FindFirstValue("sub");
        var dbUser = await _userService.GetOrCreateUser(userId);

        return new[]
        {
            new Claim("db_user_id", dbUser.Id.ToString()),
            new Claim("tenant_id", dbUser.TenantId.ToString())
        };
    }
}

KonaBox2.Logging - Naplózás

Serilog integráció production-ready naplózáshoz, konzol, fájl és Grafana Loki sink támogatással.

using KonaBox2.Logging;

Támogatott Sink-ek

Konfiguráció

services.AddKonaLogging(options =>
{
    options.MinimumLevel = LogEventLevel.Information;
    options.AppLabel = "MyApp";

    options.Console.Enabled = true;

    options.File.Enabled = true;
    options.File.Path = "logs/app.log";
    options.File.RollingInterval = RollingInterval.Day;
    options.File.RetainedFileCountLimit = 30;

    options.Loki.Enabled = true;
    options.Loki.Url = "http://loki:3100";
});