feat: server-side restriction system driven by LicenseHub heartbeat response

The Hub can now return a ServerRestrictions object on each heartbeat response.
Restrictions are non-blocking but create operational friction to enforce ToS/license compliance.

Implemented restrictions:
  - OperationDelayMs: artificial delay injected before every gRPC and REST call.
    Applied by RestrictionInterceptor (gRPC) and RestrictionMiddleware (REST).
    Even 30-50ms is severe at production throughput.
  - DisableQueryCache: bypasses the query result cache completely, forcing every
    read to hit the storage engine (higher latency + CPU usage).
    Applied in QueryCacheService.Enabled.
  - WarnBannerMessage: displays a persistent warning banner in the Blazor Studio
    UI so the server administrator sees a compliance/license message.
  - QueryResultLimit: defined in RestrictionSnapshot for future wiring into
    the query execution path (QueryDescriptorExecutor).

Hub side: HeartbeatEndpoints always returns Restrictions with all defaults
(zero delay, no cache bypass, no banner) — no restrictive logic applied yet.
Future: analyze instance telemetry and selectively apply restrictions.

Components:
  - RestrictionService: singleton holding the current RestrictionSnapshot
  - RestrictionInterceptor: gRPC server interceptor (runs before TelemetryInterceptor)
  - RestrictionMiddleware: ASP.NET middleware for REST/Studio delay
  - HeartbeatWorker: parses Restrictions from heartbeat response and calls
    RestrictionService.Update(); logs a warning when any restriction is active

Author: mrdevrobot

src/BLite.Server/Caching/QueryCacheService.cs

@@ -5,6 +5,7 @@
 // CancellationChangeToken-based invalidation.
 
 using System.Collections.Concurrent;
+using BLite.Server.License;
 using Microsoft.Extensions.Caching.Memory;
 using Microsoft.Extensions.Options;
 using Microsoft.Extensions.Primitives;
@@ -16,15 +17,16 @@ namespace BLite.Server.Caching;
 /// </summary>
 public sealed class QueryCacheService(
     IMemoryCache cache,
-    IOptions<QueryCacheOptions> opts)
+    IOptions<QueryCacheOptions> opts,
+    RestrictionService restrictions)
 {
     private readonly QueryCacheOptions _opts = opts.Value;
 
     // One CTS per canonical (dbId, collection) key.
     // Cancelling it expires all cache entries tagged with that collection.
     private readonly ConcurrentDictionary<string, CancellationTokenSource> _tokens = new();
 
-    public bool Enabled => _opts.Enabled;
+    public bool Enabled => _opts.Enabled && !restrictions.Current.DisableQueryCache;
 
     // ── Read ──────────────────────────────────────────────────────────────────
 

src/BLite.Server/Components/Layout/StudioLayout.razor

@@ -2,6 +2,7 @@
 @inject StudioService Studio
 @inject NavigationManager Nav
 @inject AuthenticationStateProvider AuthStateProvider
+@inject BLite.Server.License.RestrictionService Restrictions
 @using Microsoft.AspNetCore.Components.Authorization
 
 @if (Studio.IsSetupComplete && _isAuthenticated)
@@ -32,6 +33,13 @@
         </div>
     </nav>
     <main class="studio-main">
+        @if (Restrictions.Current.WarnBannerMessage is { } msg)
+        {
+            <div class="restriction-banner">
+                <span class="restriction-banner-icon">⚠️</span>
+                @msg
+            </div>
+        }
         @Body
     </main>
 </div>

src/BLite.Server/License/HeartbeatWorker.cs

@@ -3,6 +3,8 @@
 
 using System.Net.Http.Json;
 using System.Runtime.InteropServices;
+using System.Text.Json;
+using System.Text.Json.Serialization;
 
 namespace BLite.Server.License;
 
@@ -15,10 +17,13 @@ public sealed class HeartbeatWorker : BackgroundService
     // any restriction on server functionality — the heartbeat is telemetry only.
     private static readonly TimeSpan Interval = TimeSpan.FromMinutes(60);
 
+    private static readonly JsonSerializerOptions JsonOpts = new(JsonSerializerDefaults.Web);
+
     private readonly ILogger<HeartbeatWorker> _log;
     private readonly LicenseManager           _license;
     private readonly InstanceIdProvider       _instance;
     private readonly IHttpClientFactory       _httpFactory;
+    private readonly RestrictionService       _restrictions;
     private readonly string                   _hubUrl;
     private readonly string                   _licenseFilePath;
     private readonly DateTime                 _startedAt = DateTime.UtcNow;
@@ -28,12 +33,14 @@ public HeartbeatWorker(
         LicenseManager license,
         InstanceIdProvider instance,
         IHttpClientFactory httpFactory,
+        RestrictionService restrictions,
         ILogger<HeartbeatWorker> log)
     {
         _log             = log;
         _license         = license;
         _instance        = instance;
         _httpFactory     = httpFactory;
+        _restrictions    = restrictions;
         _hubUrl          = cfg.GetValue<string>("License:HubUrl")   ?? "https://licensehub.blitedb.com";
         _licenseFilePath = cfg.GetValue<string>("License:FilePath") ?? string.Empty;
     }
@@ -75,9 +82,34 @@ private async Task SendHeartbeatAsync(CancellationToken ct)
                 payload, ct);
 
             if (!resp.IsSuccessStatusCode)
+            {
                 _log.LogWarning("Heartbeat returned {Status}.", (int)resp.StatusCode);
+                return;
+            }
+
+            var body = await resp.Content.ReadFromJsonAsync<HeartbeatResponseDto>(JsonOpts, ct);
+            if (body?.Restrictions is { } r)
+            {
+                var snapshot = new RestrictionSnapshot
+                {
+                    OperationDelayMs  = Math.Max(0, r.OperationDelayMs),
+                    QueryResultLimit  = Math.Max(0, r.QueryResultLimit),
+                    DisableQueryCache = r.DisableQueryCache,
+                    WarnBannerMessage = r.WarnBannerMessage,
+                };
+                _restrictions.Update(snapshot);
+                if (snapshot.HasAny)
+                    _log.LogWarning("Restrictions active: delay={Delay}ms, resultLimit={Limit}, cacheOff={CacheOff}, banner={Banner}",
+                        snapshot.OperationDelayMs, snapshot.QueryResultLimit,
+                        snapshot.DisableQueryCache, snapshot.WarnBannerMessage is not null);
+            }
             else
-                _log.LogDebug("Heartbeat sent for instance {Id}.", _instance.InstanceId[..8]);
+            {
+                // Hub returned no restrictions — clear any previously active ones
+                _restrictions.Update(RestrictionSnapshot.None);
+            }
+
+            _log.LogDebug("Heartbeat sent for instance {Id}.", _instance.InstanceId[..8]);
         }
         catch (OperationCanceledException) { /* shutting down */ }
         catch (Exception ex)
@@ -89,6 +121,22 @@ private async Task SendHeartbeatAsync(CancellationToken ct)
     private static string GetVersion()
         => typeof(HeartbeatWorker).Assembly.GetName().Version?.ToString() ?? "0.0.0";
 
+    // Minimal DTO to deserialise only what we need from the heartbeat response
+    private sealed class HeartbeatResponseDto
+    {
+        public string? LicenseStatus { get; set; }
+        public string? Message { get; set; }
+        public RestrictionsDto? Restrictions { get; set; }
+    }
+
+    private sealed class RestrictionsDto
+    {
+        public int    OperationDelayMs  { get; set; } = 0;
+        public int    QueryResultLimit  { get; set; } = 0;
+        public bool   DisableQueryCache { get; set; } = false;
+        public string? WarnBannerMessage { get; set; } = null;
+    }
+
     private sealed record HeartbeatPayload(
         string InstanceId,
         string LicenseJwt,

src/BLite.Server/License/RestrictionInterceptor.cs

@@ -0,0 +1,42 @@
+// BLite.Server — gRPC interceptor that applies active server-side restrictions
+// Copyright (C) 2026 Luca Fabbri — AGPL-3.0
+//
+// Restrictions (delay, etc.) are set remotely by LicenseHub and stored in
+// RestrictionService. This interceptor runs before TelemetryInterceptor.
+
+using Grpc.Core;
+using Grpc.Core.Interceptors;
+
+namespace BLite.Server.License;
+
+/// <summary>
+/// gRPC server interceptor that enforces the operational restrictions received
+/// from LicenseHub (delay per call, etc.).
+/// </summary>
+public sealed class RestrictionInterceptor(RestrictionService restrictions) : Interceptor
+{
+    public override async Task<TResponse> UnaryServerHandler<TRequest, TResponse>(
+        TRequest request,
+        ServerCallContext context,
+        UnaryServerMethod<TRequest, TResponse> continuation)
+    {
+        await ApplyDelayAsync(context.CancellationToken);
+        return await continuation(request, context);
+    }
+
+    public override async Task ServerStreamingServerHandler<TRequest, TResponse>(
+        TRequest request,
+        IServerStreamWriter<TResponse> responseStream,
+        ServerCallContext context,
+        ServerStreamingServerMethod<TRequest, TResponse> continuation)
+    {
+        await ApplyDelayAsync(context.CancellationToken);
+        await continuation(request, responseStream, context);
+    }
+
+    private Task ApplyDelayAsync(CancellationToken ct)
+    {
+        var delay = restrictions.Current.OperationDelayMs;
+        return delay > 0 ? Task.Delay(delay, ct) : Task.CompletedTask;
+    }
+}

src/BLite.Server/License/RestrictionMiddleware.cs

@@ -0,0 +1,21 @@
+// BLite.Server — ASP.NET Core middleware that applies active restrictions to REST calls
+// Copyright (C) 2026 Luca Fabbri — AGPL-3.0
+
+namespace BLite.Server.License;
+
+/// <summary>
+/// Injects a per-request delay on all REST/API paths when an OperationDelayMs
+/// restriction is active. Must be registered before authentication middleware
+/// so it covers every request on the REST port.
+/// </summary>
+public sealed class RestrictionMiddleware(RequestDelegate next, RestrictionService restrictions)
+{
+    public async Task InvokeAsync(HttpContext context)
+    {
+        var delay = restrictions.Current.OperationDelayMs;
+        if (delay > 0)
+            await Task.Delay(delay, context.RequestAborted);
+
+        await next(context);
+    }
+}

src/BLite.Server/License/RestrictionService.cs

@@ -0,0 +1,63 @@
+// BLite.Server — singleton that holds the current server-side restrictions
+// Copyright (C) 2026 Luca Fabbri — AGPL-3.0
+//
+// Restrictions are set by the LicenseHub heartbeat response and applied
+// across all gRPC calls, REST calls, query cache, and the Studio UI.
+// All fields default to zero / false (no restrictions active).
+
+namespace BLite.Server.License;
+
+/// <summary>
+/// Thread-safe holder for the operational restrictions received from LicenseHub.
+/// Updated by <see cref="HeartbeatWorker"/> after every successful heartbeat.
+/// </summary>
+public sealed class RestrictionService
+{
+    // Volatile read is safe for reading a reference type on all current .NET
+    // memory models; writes go through Interlocked.Exchange for atomicity.
+    private volatile RestrictionSnapshot _current = RestrictionSnapshot.None;
+
+    public RestrictionSnapshot Current => _current;
+
+    /// <summary>Atomically replaces the active restriction set.</summary>
+    public void Update(RestrictionSnapshot snapshot) =>
+        Interlocked.Exchange(ref _current, snapshot);
+}
+
+/// <summary>
+/// Immutable snapshot of the restrictions in force at a given point in time.
+/// </summary>
+public sealed class RestrictionSnapshot
+{
+    public static readonly RestrictionSnapshot None = new();
+
+    /// <summary>
+    /// Artificial delay added to every gRPC and REST API call (milliseconds).
+    /// 0 = no delay. Even a small value (30–50 ms) is severe at production throughput.
+    /// </summary>
+    public int OperationDelayMs { get; init; } = 0;
+
+    /// <summary>
+    /// Hard cap on the number of documents any query may return.
+    /// 0 = no cap. Overrides any higher limit set by the caller.
+    /// </summary>
+    public int QueryResultLimit { get; init; } = 0;
+
+    /// <summary>
+    /// When true the query result cache is fully bypassed.
+    /// Forces every read to hit the storage engine, increasing latency and CPU usage.
+    /// </summary>
+    public bool DisableQueryCache { get; init; } = false;
+
+    /// <summary>
+    /// Non-null = a warning banner displayed in the Blazor Studio UI to alert
+    /// the administrator about a license or compliance issue.
+    /// </summary>
+    public string? WarnBannerMessage { get; init; } = null;
+
+    public bool HasAny =>
+        OperationDelayMs > 0 ||
+        QueryResultLimit > 0 ||
+        DisableQueryCache    ||
+        WarnBannerMessage is not null;
+}

src/BLite.Server/Program.cs

@@ -13,6 +13,7 @@
 using BLite.Server.Services;
 using BLite.Server.Caching;
 using BLite.Server.Studio;
+using BLite.Server.License;
 using BLite.Server.Telemetry;
 using BLite.Server.Transactions;
 using Microsoft.AspNetCore.Authentication;
@@ -79,6 +80,7 @@ static string ResolveAppPath(string path) =>
 builder.Services.AddHttpClient("heartbeat");
 builder.Services.AddSingleton<BLite.Server.License.InstanceIdProvider>();
 builder.Services.AddSingleton<BLite.Server.License.LicenseManager>();
+builder.Services.AddSingleton<RestrictionService>();
 builder.Services.AddHostedService<BLite.Server.License.HeartbeatWorker>();
 
 // Embedding service
@@ -174,6 +176,7 @@ static string ResolveAppPath(string path) =>
 // gRPC
 builder.Services.AddGrpc(options =>
 {
+    options.Interceptors.Add<RestrictionInterceptor>();  // must run first — applies delay
     options.Interceptors.Add<TelemetryInterceptor>();
     options.EnableDetailedErrors = builder.Environment.IsDevelopment();
     options.MaxReceiveMessageSize = 16 * 1024 * 1024; // 16 MB
@@ -294,6 +297,11 @@ static string ResolveAppPath(string path) =>
     ctx => ctx.Request.ContentType?.StartsWith("application/grpc") == true,
     branch => branch.UseMiddleware<ApiKeyMiddleware>());
 
+// REST operation delay restriction (applied to all non-gRPC paths)
+app.UseWhen(
+    ctx => ctx.Request.ContentType?.StartsWith("application/grpc") != true,
+    branch => branch.UseMiddleware<RestrictionMiddleware>());
+
 // Cookie auth for Studio UI
 if (studioEnabled)
     app.UseAuthentication();

src/BLite.Server/wwwroot/css/studio.css

@@ -373,6 +373,25 @@ select.input {
     color: var(--red);
 }
 
+/* ── Restriction warning banner ─────────────────────────────────────────────── */
+
+.restriction-banner {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    padding: 10px 16px;
+    background: rgba(210,153,34,.12);
+    border-bottom: 1px solid rgba(210,153,34,.4);
+    color: var(--orange);
+    font-size: 13px;
+    font-family: var(--sans);
+}
+
+.restriction-banner-icon {
+    font-size: 16px;
+    flex-shrink: 0;
+}
+
 /* ── Collapsible panels (details/summary) ───────────────────────────────────── */
 
 .panel {