refactor(policy): consolidate policy management and evaluation and enhancing PolicyManager

Author: dgarciasquare1

lib/core/interfaces/i_policy_evaluator.dart

@@ -0,0 +1,41 @@
+import 'package:meta/meta.dart';
+
+/// Abstract interface for evaluating policies based on role and content.
+///
+/// This interface defines the contract for policy evaluation implementations
+/// that determine whether a given role has permission to access specific content.
+/// Implementations should provide the logic for checking role-based access control
+/// according to defined policy rules.
+///
+/// Example usage:
+/// ```dart
+/// class SimplePolicyEvaluator implements IPolicyEvaluator {
+///   @override
+///   bool evaluate(String roleName, String content) {
+///     // Implementation logic here
+///     return true;
+///   }
+/// }
+/// ```
+@immutable
+abstract class IPolicyEvaluator {
+  /// Evaluates whether a role has permission to access specific content.
+  ///
+  /// This method performs the core policy evaluation logic by checking
+  /// if the specified role has the necessary permissions to access the
+  /// given content according to the defined policy rules.
+  ///
+  /// [roleName] The name of the role to evaluate permissions for.
+  ///           Must not be null or empty.
+  ///
+  /// [content] The content identifier or path to check access for.
+  ///           Must not be null or empty.
+  ///
+  /// Returns `true` if the role has permission to access the content,
+  /// `false` otherwise.
+  ///
+  /// Throws:
+  /// - [ArgumentError] if [roleName] or [content] is null or empty
+  /// - [StateError] if the policy evaluator is not properly initialized
+  bool evaluate(String roleName, String content);
+}

lib/core/interfaces/i_policy_storage.dart

@@ -0,0 +1,42 @@
+import 'package:meta/meta.dart';
+
+/// Abstract interface for policy storage operations.
+///
+/// This interface defines the contract for storing and retrieving policy data
+/// in the Flutter Policy Engine. Implementations can provide different storage
+/// backends such as local file storage, secure storage, or remote storage.
+///
+/// All methods are asynchronous to support various storage mechanisms that
+/// may require I/O operations.
+@immutable
+abstract class IPolicyStorage {
+  /// Loads all policies from storage.
+  ///
+  /// Returns a [Map<String, dynamic>] containing the policy data where:
+  /// - Keys represent policy identifiers
+  /// - Values represent the policy configuration and rules
+  ///
+  /// Throws a [StateError] if the storage is not accessible or corrupted.
+  /// Returns an empty map if no policies are stored.
+  Future<Map<String, dynamic>> loadPolicies();
+
+  /// Saves policies to storage.
+  ///
+  /// [policies] should be a [Map<String, dynamic>] where:
+  /// - Keys represent policy identifiers
+  /// - Values represent the policy configuration and rules
+  ///
+  /// This method will overwrite any existing policies in storage.
+  /// Throws a [StateError] if the storage is not writable or if the data
+  /// format is invalid.
+  Future<void> savePolicies(Map<String, dynamic> policies);
+
+  /// Removes all policies from storage.
+  ///
+  /// This operation is irreversible and will permanently delete all stored
+  /// policy data. Use with caution.
+  ///
+  /// Throws a [StateError] if the storage is not accessible or if the
+  /// clear operation fails.
+  Future<void> clearPolicies();
+}

lib/core/policy_manager.dart

@@ -0,0 +1,75 @@
+import 'package:flutter_policy_engine/src/core/interfaces/i_policy_storage.dart';
+
+/// An in-memory implementation of [IPolicyStorage] that stores policies
+/// in a Map during the application's runtime.
+///
+/// This storage implementation is suitable for:
+/// - Testing scenarios where persistence is not required
+/// - Temporary policy storage during development
+/// - Cases where policies are loaded at startup and don't need to persist
+///   between application sessions
+///
+/// **Note:** All data stored in this implementation will be lost when the
+/// application is terminated or the object is garbage collected.
+class MemoryPolicyStorage implements IPolicyStorage {
+  /// Internal storage for policies using a Map with String keys and dynamic values.
+  ///
+  /// The Map structure allows for flexible policy storage where keys represent
+  /// policy identifiers and values contain the policy data.
+  Map<String, dynamic> _policies = {};
+
+  /// Loads all stored policies from memory.
+  ///
+  /// Returns a copy of the internal policies map to prevent external
+  /// modifications from affecting the internal state.
+  ///
+  /// **Returns:** A [Future] that completes with a [Map<String, dynamic>]
+  /// containing all stored policies.
+  ///
+  /// **Example:**
+  /// ```dart
+  /// final storage = MemoryPolicyStorage();
+  /// final policies = await storage.loadPolicies();
+  /// print('Loaded ${policies.length} policies');
+  /// ```
+  @override
+  Future<Map<String, dynamic>> loadPolicies() async {
+    return Map.from(_policies);
+  }
+
+  /// Saves the provided policies to memory storage.
+  ///
+  /// Creates a deep copy of the input policies to ensure the internal
+  /// storage is not affected by subsequent modifications to the input map.
+  ///
+  /// **Parameters:**
+  /// - [policies]: A [Map<String, dynamic>] containing the policies to store.
+  ///   Keys should be policy identifiers and values should contain policy data.
+  ///
+  /// **Example:**
+  /// ```dart
+  /// final storage = MemoryPolicyStorage();
+  /// final policies = {'user_policy': {'role': 'admin'}};
+  /// await storage.savePolicies(policies);
+  /// ```
+  @override
+  Future<void> savePolicies(Map<String, dynamic> policies) async {
+    _policies = Map.from(policies);
+  }
+
+  /// Removes all stored policies from memory.
+  ///
+  /// This operation is immediate and irreversible. All policy data
+  /// will be permanently lost after calling this method.
+  ///
+  /// **Example:**
+  /// ```dart
+  /// final storage = MemoryPolicyStorage();
+  /// await storage.clearPolicies();
+  /// // All policies have been removed
+  /// ```
+  @override
+  Future<void> clearPolicies() async {
+    _policies.clear();
+  }
+}

lib/core/role_evaluator.dart

@@ -0,0 +1,132 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter_policy_engine/src/core/interfaces/i_policy_evaluator.dart';
+import 'package:flutter_policy_engine/src/core/interfaces/i_policy_storage.dart';
+import 'package:flutter_policy_engine/src/core/memory_policy_storage.dart';
+import 'package:flutter_policy_engine/src/core/role_evaluator.dart';
+import 'package:flutter_policy_engine/src/models/policy.dart';
+import 'package:flutter_policy_engine/src/utils/json_handler.dart';
+import 'package:flutter_policy_engine/src/utils/log_handler.dart';
+
+/// Manages policy lifecycle and provides centralized access to policy operations.
+///
+/// The [PolicyManager] serves as the main entry point for policy-related operations,
+/// coordinating between storage, evaluation, and policy state management. It extends
+/// [ChangeNotifier] to notify listeners of policy state changes.
+///
+/// Example usage:
+/// ```dart
+/// final policyManager = PolicyManager(
+///   storage: MyPolicyStorage(),
+///   evaluator: MyPolicyEvaluator(),
+/// );
+///
+/// await policyManager.initialize(policyJsonData);
+/// ```
+class PolicyManager extends ChangeNotifier {
+  /// Creates a new [PolicyManager] instance.
+  ///
+  /// [storage] is responsible for persisting and retrieving policy data.
+  /// [evaluator] handles policy evaluation logic and decision making.
+  PolicyManager({
+    IPolicyStorage? storage,
+    IPolicyEvaluator? evaluator,
+  })  : _storage = storage ?? MemoryPolicyStorage(),
+        _evaluator = evaluator;
+
+  /// The storage implementation for policy persistence.
+  final IPolicyStorage _storage;
+
+  /// The evaluator implementation for policy decision making.
+  IPolicyEvaluator? _evaluator;
+
+  /// Internal cache of loaded policies, keyed by policy identifier.
+  Map<String, Policy> _policies = {};
+
+  /// Indicates whether the policy manager has been initialized with policy data.
+  bool _isInitialized = false;
+
+  /// Returns whether the policy manager has been initialized.
+  ///
+  /// Returns `true` if [initialize] has been called successfully, `false` otherwise.
+  bool get isInitialized => _isInitialized;
+
+  /// Returns an unmodifiable view of all loaded policies.
+  ///
+  /// The returned map cannot be modified directly. Use [initialize] to update
+  /// the policy collection.
+  Map<String, Policy> get policies => Map.unmodifiable(_policies);
+
+  /// Initializes the policy manager with policy data from JSON.
+  ///
+  /// Parses the provided [jsonPolicies] and loads them into the internal cache.
+  /// This method should be called before using any policy-related functionality.
+  ///
+  /// [jsonPolicies] should be a map where keys are policy identifiers and values
+  /// are JSON representations of [Policy] objects.
+  ///
+  /// Throws:
+  /// - [JsonParseException] if policy parsing fails completely
+  /// - [FormatException] if the JSON data is malformed
+  /// - [ArgumentError] if policy parsing fails
+  Future<void> initialize(Map<String, dynamic> jsonPolicies) async {
+    try {
+      LogHandler.info(
+        'Initializing policy manager',
+        context: {
+          'policy_count': jsonPolicies.length,
+          'policy_keys': jsonPolicies.keys.take(5).toList(),
+        },
+        operation: 'policy_manager_initialize',
+      );
+
+      _policies = JsonHandler.parseMap(
+        jsonPolicies,
+        (json) => Policy.fromJson(json),
+        context: 'policy_manager',
+        allowPartialSuccess:
+            true, // Allow partial success for graceful degradation
+      );
+
+      // Only create evaluator if we have at least some policies
+      if (_policies.isNotEmpty) {
+        _evaluator = RoleEvaluator(_policies);
+        await _storage.savePolicies(_policies);
+        _isInitialized = true;
+
+        LogHandler.info(
+          'Policy manager initialized successfully',
+          context: {
+            'loaded_policies': _policies.length,
+            'total_policies': jsonPolicies.length,
+          },
+          operation: 'policy_manager_initialized',
+        );
+      } else {
+        LogHandler.warning(
+          'Policy manager initialized with no valid policies',
+          context: {
+            'total_policies': jsonPolicies.length,
+          },
+          operation: 'policy_manager_empty',
+        );
+        // Still mark as initialized but with empty policies
+        _isInitialized = true;
+      }
+
+      notifyListeners();
+    } catch (e, stackTrace) {
+      LogHandler.error(
+        'Failed to initialize policy manager',
+        error: e,
+        stackTrace: stackTrace,
+        context: {
+          'policy_count': jsonPolicies.length,
+        },
+        operation: 'policy_manager_initialize_error',
+      );
+
+      // Re-throw to allow caller to handle the error
+      rethrow;
+    }
+  }
+}