RFC: This RFC contains the changes proposed for major version update v2

[lakhansamani]

Summary

This RFC outlines the major improvements and architectural changes for v2 of authorizer.dev. The proposed updates focus on removing global variables, simplifying configuration management, enhancing logging, and improving overall performance and project structure.

Motivation

Version 1 of authorizer.dev contains a number of limitations that affect performance, code maintainability, and scalability. The primary issues include reliance on global variables for configuration and secrets, non-standard logging practices, and a suboptimal project structure. This RFC aims to address these concerns in a comprehensive manner for a cleaner and more efficient codebase.

Key Issues Addressed

1. Global variables for environment/configs/secrets: Global variables introduce complexity in testing and debugging and can lead to unexpected behaviors in different environments.

2. Environment variables stored in DB/Memory: Storing environment variables in a database or in-memory creates multiple sources of truth. This introduces unnecessary complexity and potential security risks.

3. Logging improvements: The existing logging system uses Logrus. To improve standardization, better format logs, and ensure structured logging, we propose switching to Zerolog with JSON format.

4. Project structure: The current project structure does not follow the standard Go project structure, leading to difficulty in maintaining and scaling the application.

5. Performance issues: The current architecture can be optimized by adopting a dependency injection pattern and reducing unnecessary resource usage.

---

Detailed Design

1. Removal of Global Variables

In v1, global variables are used for environment, configurations, and secrets. This RFC proposes moving away from global state management to pass dependencies through constructors or context. This will:

• Improve testability by allowing mocking of dependencies.
• Make the codebase more predictable and easier to debug.

Proposed changes:

• Use dependency injection to pass required services and configurations.
• No usage of global environment variables for secrets or configs.

2. Single Source of Truth for Environment Variables

Instead of storing environment variables in the database or memory, the new version will take these values as CLI arguments at startup. This ensures that environment configurations come from a single, trusted source.

Proposed changes:

• Use environment variables or CLI flags exclusively for all configurations.
• Remove storage of these values in memory or database.

Benefits:

• Easier configuration management.
• No need to persist sensitive environment details, improving security.

3. Logging with Zerolog and JSON Format

The current logging system uses Logrus, which does not support advanced structured logging in a standard JSON format. We propose switching to Zerolog, which provides:

• Lightweight and fast logging.
• Native JSON format for better integration with logging systems.

Proposed changes:

• Replace Logrus with Zerolog.
• Default log format will be JSON for compatibility with log aggregators and standard log formatting.

Benefits:

• Reduced log size and overhead.
• Standardized logging for better monitoring and debugging.

4. Standardized Project Structure

The current project structure can be improved to align with Go's standard project layout. This makes the project easier to navigate and maintain for developers.

Proposed changes:

• Adopt a more modular approach to separate concerns.
• Move to a more standard project layout (cmd, pkg, internal, etc.).

Benefits:

• Easier maintainability and readability.
• Better support for scaling and future development.

5. Performance Enhancements via Dependency Architecture

By using dependency injection (DI) for passing services and configurations, performance can be optimized as follows:

• Lazy loading of dependencies.
• Avoid unnecessary global state or singleton patterns.

Proposed changes:

• Refactor the architecture to introduce DI patterns.
• Ensure that only necessary dependencies are instantiated, improving startup time and memory usage.

Benefits:

• Improved performance and resource usage.
• Cleaner and more scalable architecture.

---

Drawbacks

• The refactoring will require significant changes to the codebase and may introduce breaking changes for users relying on existing configurations.
• Transitioning to a new logging framework may require changes to log parsing in external systems.

Alternatives

• Continue using global variables but refactor to better manage them. However, this would not address the fundamental issues of complexity and security.
• Use Logrus with custom formatters to mimic the Zerolog behavior, but this would still be less efficient than adopting a native JSON logger like Zerolog.

---