Skip to main content
Version: Next

1.12.x Release Notes

This page summarizes notable changes in the 1.12 minor series. Patch-level releases are listed below.

1.12 introduces major architectural shifts, including dependency injection via Uber Fx, integrated OpenTelemetry tracing, and a completely refactored OOP-based Redis library.

1.12.0​

Breaking Changes​

Lua Hook Function Signature​

The signature of the Lua hook function nauthilus_run_hook has changed.

  • Old signature: function nauthilus_run_hook(logging, session)
  • New signature: function nauthilus_run_hook(request)

Workaround / Migration: Existing scripts must be updated to accept a single request table. Information previously passed as separate arguments is now part of the request object. Example:

-- Old
function nauthilus_run_hook(logging, session)
    local sess = session
    -- ...
end

-- New
function nauthilus_run_hook(request)
    local sess = request.session
    local logging = request.logging
    -- ...
end

New Features​

OpenTelemetry Tracing​

  • Integrated OpenTelemetry (OTel) tracing across core modules:
    • LDAP operations.
    • Lua Filters.
    • Brute-force detection and sync service.
  • Spans now capture more detailed metadata about the authentication request lifecycle.

Redis & Storage Improvements​

  • Refactored Redis Library: Rewritten using a pure Object-Oriented Programming (OOP) approach for better testability and maintainability.
  • Cluster Alignment: Introduced sharded Redis key generation to improve performance and compatibility with Redis Clusters.
  • Monitoring: Added health and role metrics for Redis instances to enhance observability.
  • RESP3 Identity: Added support for Redis client identity and maintenance notifications in RESP3.

Brute-Force Protection​

  • L1 Decision Engine: Introduced the L1 Decision Engine for faster and more efficient brute-force checks.
  • Sync Service: Added a dedicated brute-force sync service to keep detection states consistent across multiple Nauthilus instances.
  • Improved Detection: Replaced RWPAllowSet with RWPSlidingWindow for more accurate "Repeating Wrong Password" detection.
  • Account Mapping: Added support for protocol-specific and OIDC client ID-specific user account mapping.

LDAP Enhancements​

  • Reliability: Integrated an LDAP circuit breaker and health checks to prevent cascading failures when upstream directory servers are unstable.
  • Performance: Optimized filter handling and improved negative cache logic for faster repeated lookups.
  • Timeouts: Added detailed timeout handling to allow for better error classification and recovery.

Lua API Enhancements​

  • Added WhenNoAuth support for Lua Features, allowing them to run if request.no_auth is true.
  • CommonRequest object extended with method, latency, and http_status fields.
  • New nauthilus_opentelemetry module for custom tracing in Lua scripts.
  • Environment variable handling in Lua now uses nauthilus_util.getenv.

Core Runtime & Performance​

  • Architectural Shift: Migrated the entire application to Uber Fx, enabling robust dependency injection and centralized lifecycle management for all services and background workers.
  • Garbage Collection: Integrated GOEXPERIMENT=greenteagc support to optimize GC performance in high-concurrency environments.
  • Memory Efficiency: Optimized string operations using strings.Builder and implemented sync.Pool for logging to significantly reduce memory allocations.
  • Error Handling: Introduced HandleJSONValidationError for uniform error reporting and added request abortion handling for improved error context and debugging.
  • Internal Refactoring: Streamlined AuthState structures to better separate Request, Runtime, and Security concerns, leading to cleaner code and better maintainability.
  • Observability: Integrated slog-based structured logging and expanded health/role metrics for Redis.
  • Security & Validation: Added validation for empty usernames and passwords in authentication flows; enhanced REST API with status message and HTTP status handling.