Documentation

Directive Guard Options

Read time 2 minutes Package: Nalix.Runtime
On this page

Namespace: Nalix.Runtime.Options
Assembly: Nalix.Runtime

DirectiveGuardOptions (public sealed partial class DirectiveGuardOptions : ConfigurationLoader, IValidatableConfiguration) configures the per-connection cooldown enforced by DirectiveGuard before sending repeated inbound failure directives (UNAUTHORIZED, RATE_LIMITED, and TIMEOUT).

Source Mapping

  • src/Nalix.Runtime/Options/DirectiveGuardOptions.cs
  • src/Nalix.Runtime/Internal/RateLimiting/DirectiveGuard.cs
  • src/Nalix.Runtime/Internal/RuntimeConnectionState.cs
  • src/Nalix.Runtime/Extensions/ConnectionExtensions.cs
  • src/Nalix.Runtime/Middleware/Standard/PermissionMiddleware.cs
  • src/Nalix.Runtime/Middleware/Standard/RateLimitMiddleware.cs
  • src/Nalix.Runtime/Middleware/Standard/TimeoutMiddleware.cs

Property Reference

Loaded from the [DirectiveGuard] section of default.ini via ConfigurationManager.Instance.Get<DirectiveGuardOptions>():

PropertyTypeDefaultValidationDescription
DefaultCooldownMsint1_000 (1000 ms)[ValueRange(0, 60000)]Minimum interval in milliseconds between repeated directives of the same category per connection (0 disables suppression).

How DirectiveGuard Works

When an inbound middleware denies or times out a packet, it calls:

DirectiveGuard.TryAcquire(
    IConnection connection,
    Func<RuntimeConnectionState, long> stateSelector,
    Action<RuntimeConnectionState, long> stateUpdater,
    int? cooldownMs = null)
Architecture Diagram
flowchart LR
    A["Middleware Denies Packet"] --> B["DirectiveGuard.TryAcquire(...)"]
    B --> C{"resolvedCooldownMs <= 0?"}
    C -->|Yes| Allow["Return true (Send Directive)"]
    C -->|No| D["Get connection.GetRuntimeState()"]
    D --> E["lock (state.DirectiveGuardLock)"]
    E --> F{"lastSent == 0 || (nowMs - lastSent) >= resolvedCooldownMs?"}
    F -->|Yes| G["stateUpdater(state, nowMs) -> Return true"]
    F -->|No| H["Return false (Suppress Duplicate Directive)"]

Per-Category Timestamps on RuntimeConnectionState

DirectiveGuard tracks three independent Environment.TickCount64 timestamps on each connection’s RuntimeConnectionState (guarded by state.DirectiveGuardLock):

MiddlewareDirective ReasonRuntimeConnectionState Property
PermissionMiddlewareProtocolReason.UNAUTHORIZEDInboundDirectiveUnauthorizedLastSentAtMs
RateLimitMiddlewareProtocolReason.RATE_LIMITEDInboundDirectiveRateLimitedLastSentAtMs
TimeoutMiddlewareProtocolReason.TIMEOUTInboundDirectiveTimeoutLastSentAtMs

Suppressing a duplicate Directive only prevents outbound response amplification—the denied packet is still dropped and never reaches the handler.