feat: added throttle and execution logger

[petruki]

This pull request introduces a new throttling mechanism with Stale-While-Revalidate (SWR) behavior for feature flag evaluations, adds an execution logger for caching and retrieving evaluation results, and exposes new methods to interact with cached executions. These enhancements are designed to improve performance and observability, especially under high-traffic scenarios, and are accompanied by comprehensive documentation and tests.

Throttling and Caching Enhancements:

• Added a Throttle method to the Switcher struct, enabling SWR caching for feature flag evaluations. When throttling is enabled, cached results are returned immediately while a background refresh updates the cache, reducing latency and API load. The cache respects the Freeze option and can be cleared via ClearLogger. (switcher.go, client.go, README.md) [1] [2] [3] [4]
• Introduced a throttleTokens mechanism and runBackgroundTask in Client to limit concurrent background refreshes, configurable via context options. (client.go) [1] [2] [3] [4]

Execution Logging and API:

• Implemented an executionLogger for storing and retrieving cached execution results, including input criteria and metadata (e.g., whether a result was cached). Exposed new API methods: GetExecution (to retrieve cached results) and ClearLogger (to clear the cache), both as client methods and package-level functions. (execution_logger.go, client.go) [1] [2]
• Updated the logic for logging executions to support both local and remote evaluations, and to ensure thread safety and correct cache invalidation. (switcher.go)

Documentation and Testing:

• Expanded the README with detailed documentation and usage examples for the new throttling and caching features, including code samples for retrieving cached executions. (README.md)
• Added comprehensive tests for the execution logger, covering logging, retrieval, and clearing of cached executions in various scenarios (local, remote, and nil switchers). (execution_logger_test.go)

Concurrency and Safety Improvements:

• Added mutexes to Switcher to ensure thread-safe access to mutable fields, especially for throttling and input criteria management. (switcher.go) [1] [2]
• Refactored methods to use snapshots of switcher state for consistent and safe evaluation and caching. (switcher.go)

Other Minor Updates:

• Added a Snyk badge to the README for vulnerability monitoring. (README.md)
• Minor refactoring for clarity and maintainability, including moving and renaming methods and improving code comments. (multiple files)

These changes collectively improve the SDK's efficiency, scalability, and usability for high-throughput applications.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud