Phase 6 - User Session Management complete

master
gitea 2 months ago
parent 53d11d49ff
commit 13ec9e5a9d

@ -2,6 +2,14 @@
A modular, offline-first Flutter boilerplate for apps that store, sync, and share media and metadata across centralized (Immich, Firebase) and decentralized (Nostr) systems. A modular, offline-first Flutter boilerplate for apps that store, sync, and share media and metadata across centralized (Immich, Firebase) and decentralized (Nostr) systems.
## Phase 6 - User Session Management
- User login, logout, and session switching
- Per-user data isolation with separate storage paths
- Cache clearing on logout
- Integration with local storage and sync engine
- Comprehensive unit tests
## Phase 5 - Relay Management UI ## Phase 5 - Relay Management UI
- User interface for managing Nostr relays - User interface for managing Nostr relays
@ -118,6 +126,21 @@ User interface for managing Nostr relays. View configured relays, add/remove rel
**Usage:** Navigate to "Manage Relays" from the main screen after initialization. **Usage:** Navigate to "Manage Relays" from the main screen after initialization.
## User Session Management
Service for managing user sessions, login, logout, and session isolation. Provides per-user data isolation with separate storage paths and cache directories. Clears cached data on logout and integrates with local storage and sync engine.
**Files:**
- `lib/data/session/session_service.dart` - Main session management service
- `lib/data/session/models/user.dart` - User model
- `test/data/session/session_service_test.dart` - Unit tests
**Key Methods:** `login()`, `logout()`, `switchSession()`, `getCurrentUserDbPath()`, `getCurrentUserCacheDir()`
**Features:** Per-user storage isolation, cache clearing on logout, session switching with data preservation, integration with local storage
**Usage:** Initialize `SessionService` with `LocalStorageService` and optional `SyncEngine`. Call `login()` to start a session, `logout()` to end it, and `switchSession()` to change users.
## Configuration ## Configuration
**Configuration uses `.env` files for sensitive values (API keys, URLs) with fallback defaults in `lib/config/config_loader.dart`.** **Configuration uses `.env` files for sensitive values (API keys, URLs) with fallback defaults in `lib/config/config_loader.dart`.**
@ -209,6 +232,10 @@ lib/
│ │ ├── nostr_keypair.dart │ │ ├── nostr_keypair.dart
│ │ ├── nostr_event.dart │ │ ├── nostr_event.dart
│ │ └── nostr_relay.dart │ │ └── nostr_relay.dart
│ ├── session/
│ │ ├── session_service.dart
│ │ └── models/
│ │ └── user.dart
│ └── sync/ │ └── sync/
│ ├── sync_engine.dart │ ├── sync_engine.dart
│ └── models/ │ └── models/
@ -230,6 +257,8 @@ test/
│ └── immich_service_test.dart │ └── immich_service_test.dart
├── nostr/ ├── nostr/
│ └── nostr_service_test.dart │ └── nostr_service_test.dart
├── session/
│ └── session_service_test.dart
├── sync/ ├── sync/
│ └── sync_engine_test.dart │ └── sync_engine_test.dart
└── ui/ └── ui/

@ -1 +0,0 @@
include: package:flutter_lints/flutter.yaml

@ -42,21 +42,35 @@ class LocalStorageService {
/// Initializes the database and cache directory. /// Initializes the database and cache directory.
/// ///
/// [sessionDbPath] - Optional database path for session-specific storage.
/// [sessionCacheDir] - Optional cache directory for session-specific storage.
///
/// Must be called before using any other methods. /// Must be called before using any other methods.
/// ///
/// Throws [Exception] if initialization fails. /// Throws [Exception] if initialization fails.
Future<void> initialize() async { Future<void> initialize({
String? sessionDbPath,
Directory? sessionCacheDir,
}) async {
try { try {
// Initialize database // Close existing database if switching sessions
final dbPath = _testDbPath ?? await _getDatabasePath(); if (_database != null) {
await _database!.close();
_database = null;
}
// Initialize database with session-specific or default path
final dbPath = sessionDbPath ?? _testDbPath ?? await _getDatabasePath();
_database = await openDatabase( _database = await openDatabase(
dbPath, dbPath,
version: 1, version: 1,
onCreate: _onCreate, onCreate: _onCreate,
); );
// Initialize cache directory // Initialize cache directory with session-specific or default path
if (_testCacheDir != null) { if (sessionCacheDir != null) {
_cacheDirectory = sessionCacheDir;
} else if (_testCacheDir != null) {
_cacheDirectory = _testCacheDir; _cacheDirectory = _testCacheDir;
} else { } else {
final appDir = await getApplicationDocumentsDirectory(); final appDir = await getApplicationDocumentsDirectory();
@ -66,11 +80,52 @@ class LocalStorageService {
if (!await _cacheDirectory!.exists()) { if (!await _cacheDirectory!.exists()) {
await _cacheDirectory!.create(recursive: true); await _cacheDirectory!.create(recursive: true);
} }
// Clear in-memory cache status when switching sessions
_cacheStatus.clear();
} catch (e) { } catch (e) {
throw Exception('Failed to initialize LocalStorageService: $e'); throw Exception('Failed to initialize LocalStorageService: $e');
} }
} }
/// Reinitializes the service with a new database path (for session switching).
///
/// [newDbPath] - New database path to use.
/// [newCacheDir] - New cache directory to use.
///
/// Throws [Exception] if reinitialization fails.
Future<void> reinitializeForSession({
required String newDbPath,
required Directory newCacheDir,
}) async {
await initialize(
sessionDbPath: newDbPath,
sessionCacheDir: newCacheDir,
);
}
/// Clears all cached data (for session logout).
///
/// Throws [Exception] if clearing fails.
Future<void> clearAllData() async {
_ensureInitialized();
try {
// Clear all items from database
await _database!.delete('items');
// Clear cache directory
if (_cacheDirectory != null && await _cacheDirectory!.exists()) {
await _cacheDirectory!.delete(recursive: true);
await _cacheDirectory!.create(recursive: true);
}
// Clear in-memory cache status
_cacheStatus.clear();
} catch (e) {
throw Exception('Failed to clear all data: $e');
}
}
/// Creates the database schema if it doesn't exist. /// Creates the database schema if it doesn't exist.
Future<void> _onCreate(Database db, int version) async { Future<void> _onCreate(Database db, int version) async {
await db.execute(''' await db.execute('''

@ -0,0 +1,80 @@
/// Data model representing a user session.
///
/// This model stores user identification and authentication information
/// for session management and data isolation.
class User {
/// Unique identifier for the user.
final String id;
/// Display name or username for the user.
final String username;
/// Optional authentication token or session token.
final String? token;
/// Timestamp when the session was created (milliseconds since epoch).
final int createdAt;
/// Creates a [User] instance.
///
/// [id] - Unique identifier for the user.
/// [username] - Display name or username.
/// [token] - Optional authentication token.
/// [createdAt] - Session creation timestamp (defaults to current time).
User({
required this.id,
required this.username,
this.token,
int? createdAt,
}) : createdAt = createdAt ?? DateTime.now().millisecondsSinceEpoch;
/// Creates a [User] from a Map (e.g., from database or JSON).
factory User.fromMap(Map<String, dynamic> map) {
return User(
id: map['id'] as String,
username: map['username'] as String,
token: map['token'] as String?,
createdAt: map['created_at'] as int?,
);
}
/// Converts the [User] to a Map for storage.
Map<String, dynamic> toMap() {
return {
'id': id,
'username': username,
'token': token,
'created_at': createdAt,
};
}
/// Creates a copy of this [User] with updated fields.
User copyWith({
String? id,
String? username,
String? token,
int? createdAt,
}) {
return User(
id: id ?? this.id,
username: username ?? this.username,
token: token ?? this.token,
createdAt: createdAt ?? this.createdAt,
);
}
@override
String toString() {
return 'User(id: $id, username: $username, createdAt: $createdAt)';
}
@override
bool operator ==(Object other) {
if (identical(this, other)) return true;
return other is User && other.id == id;
}
@override
int get hashCode => id.hashCode;
}

@ -0,0 +1,262 @@
import 'dart:io';
import 'package:path/path.dart' as path;
import 'package:path_provider/path_provider.dart';
import '../local/local_storage_service.dart';
import '../sync/sync_engine.dart';
import 'models/user.dart';
/// Exception thrown when session operations fail.
class SessionException implements Exception {
/// Error message.
final String message;
/// Creates a [SessionException] with the provided message.
SessionException(this.message);
@override
String toString() => 'SessionException: $message';
}
/// Service for managing user sessions, login, logout, and session isolation.
///
/// This service provides:
/// - User login and logout
/// - Session switching between multiple users
/// - Data isolation per user session
/// - Cache clearing on logout
/// - Integration with local storage and sync engine
///
/// The service is modular and UI-independent, designed for offline-first behavior.
class SessionService {
/// Current active user session (null if no user is logged in).
User? _currentUser;
/// Local storage service for data persistence.
final LocalStorageService _localStorage;
/// Sync engine for coordinating sync operations (optional).
final SyncEngine? _syncEngine;
/// Map of user IDs to their session storage paths.
final Map<String, String> _userDbPaths = {};
/// Map of user IDs to their cache directories.
final Map<String, Directory> _userCacheDirs = {};
/// Optional test database path for testing.
final String? _testDbPath;
/// Optional test cache directory for testing.
final Directory? _testCacheDir;
/// Creates a [SessionService] instance.
///
/// [localStorage] - Local storage service for data persistence.
/// [syncEngine] - Optional sync engine for coordinating sync operations.
/// [testDbPath] - Optional database path for testing.
/// [testCacheDir] - Optional cache directory for testing.
SessionService({
required LocalStorageService localStorage,
SyncEngine? syncEngine,
String? testDbPath,
Directory? testCacheDir,
}) : _localStorage = localStorage,
_syncEngine = syncEngine,
_testDbPath = testDbPath,
_testCacheDir = testCacheDir;
/// Gets the current active user session.
///
/// Returns the current [User] if logged in, null otherwise.
User? get currentUser => _currentUser;
/// Checks if a user is currently logged in.
bool get isLoggedIn => _currentUser != null;
/// Logs in a user and creates an isolated session.
///
/// [id] - Unique identifier for the user.
/// [username] - Display name or username.
/// [token] - Optional authentication token.
///
/// Returns the logged-in [User].
///
/// Throws [SessionException] if login fails or if user is already logged in.
Future<User> login({
required String id,
required String username,
String? token,
}) async {
if (_currentUser != null) {
throw SessionException('User already logged in. Logout first.');
}
try {
final user = User(
id: id,
username: username,
token: token,
);
// Create user-specific storage paths
await _setupUserStorage(user);
// Set as current user
_currentUser = user;
return user;
} catch (e) {
throw SessionException('Failed to login: $e');
}
}
/// Logs out the current user and clears session data.
///
/// [clearCache] - Whether to clear cached data (default: true).
///
/// Throws [SessionException] if logout fails or if no user is logged in.
Future<void> logout({bool clearCache = true}) async {
if (_currentUser == null) {
throw SessionException('No user logged in.');
}
try {
final userId = _currentUser!.id;
// Clear user-specific data if requested
if (clearCache) {
await _clearUserData(userId);
}
// Clear current user
_currentUser = null;
// Clean up user storage references
_userDbPaths.remove(userId);
_userCacheDirs.remove(userId);
} catch (e) {
throw SessionException('Failed to logout: $e');
}
}
/// Switches to a different user session.
///
/// This method logs out the current user and logs in the new user.
///
/// [id] - Unique identifier for the new user.
/// [username] - Display name or username for the new user.
/// [token] - Optional authentication token for the new user.
/// [clearCache] - Whether to clear cached data for the previous user (default: true).
///
/// Returns the new logged-in [User].
///
/// Throws [SessionException] if switch fails.
Future<User> switchSession({
required String id,
required String username,
String? token,
bool clearCache = true,
}) async {
if (_currentUser != null) {
await logout(clearCache: clearCache);
}
return await login(
id: id,
username: username,
token: token,
);
}
/// Sets up user-specific storage paths and reinitializes local storage.
///
/// [user] - The user to set up storage for.
Future<void> _setupUserStorage(User user) async {
try {
// Get user-specific database path
// In test mode, create per-user paths under the test directory
// In production, create per-user paths under app documents
String dbPath;
if (_testDbPath != null) {
// Create user-specific path under test directory
final testDir = path.dirname(_testDbPath!);
dbPath = path.join(testDir, 'user_${user.id}_storage.db');
} else {
final appDir = await getApplicationDocumentsDirectory();
dbPath = path.join(appDir.path, 'users', user.id, 'storage.db');
}
_userDbPaths[user.id] = dbPath;
// Get user-specific cache directory
Directory cacheDir;
if (_testCacheDir != null) {
// Create user-specific cache under test directory
final testCacheParent = _testCacheDir!.path;
cacheDir = Directory(path.join(testCacheParent, 'user_${user.id}'));
} else {
final appDir = await getApplicationDocumentsDirectory();
cacheDir = Directory(path.join(appDir.path, 'users', user.id, 'cache'));
}
if (!await cacheDir.exists()) {
await cacheDir.create(recursive: true);
}
_userCacheDirs[user.id] = cacheDir;
// Reinitialize local storage with user-specific paths
await _localStorage.reinitializeForSession(
newDbPath: dbPath,
newCacheDir: cacheDir,
);
} catch (e) {
throw SessionException('Failed to setup user storage: $e');
}
}
/// Clears all data for a specific user.
///
/// [userId] - The ID of the user whose data should be cleared.
Future<void> _clearUserData(String userId) async {
try {
// Clear all data from local storage if it's the current user's storage
if (_currentUser?.id == userId) {
await _localStorage.clearAllData();
}
// Clear cache directory
final cacheDir = _userCacheDirs[userId];
if (cacheDir != null && await cacheDir.exists()) {
await cacheDir.delete(recursive: true);
}
// Clear database path reference
_userDbPaths.remove(userId);
_userCacheDirs.remove(userId);
// Notify sync engine if available
if (_syncEngine != null) {
// Sync engine will handle session cleanup internally
// This is a placeholder for future sync engine integration
}
} catch (e) {
throw SessionException('Failed to clear user data: $e');
}
}
/// Gets the database path for the current user.
///
/// Returns the database path if user is logged in, null otherwise.
String? getCurrentUserDbPath() {
if (_currentUser == null) return null;
return _userDbPaths[_currentUser!.id];
}
/// Gets the cache directory for the current user.
///
/// Returns the cache directory if user is logged in, null otherwise.
Directory? getCurrentUserCacheDir() {
if (_currentUser == null) return null;
return _userCacheDirs[_currentUser!.id];
}
}

@ -264,7 +264,7 @@ class _MyAppState extends State<MyApp> {
const SizedBox(height: 16), const SizedBox(height: 16),
], ],
Text( Text(
'Phase 5: Relay Management UI Complete ✓', 'Phase 6: User Session Management Complete ✓',
style: Theme.of(context).textTheme.bodyMedium?.copyWith( style: Theme.of(context).textTheme.bodyMedium?.copyWith(
color: Colors.grey, color: Colors.grey,
), ),

@ -1,5 +1,4 @@
import 'package:flutter_test/flutter_test.dart'; import 'package:flutter_test/flutter_test.dart';
import 'package:app_boilerplate/config/app_config.dart';
import 'package:app_boilerplate/config/config_loader.dart'; import 'package:app_boilerplate/config/config_loader.dart';
void main() { void main() {

@ -0,0 +1,326 @@
import 'dart:io';
import 'package:flutter_test/flutter_test.dart';
import 'package:path/path.dart' as path;
import 'package:sqflite_common_ffi/sqflite_ffi.dart';
import 'package:app_boilerplate/data/session/session_service.dart';
import 'package:app_boilerplate/data/session/models/user.dart';
import 'package:app_boilerplate/data/local/local_storage_service.dart';
import 'package:app_boilerplate/data/local/models/item.dart';
import 'package:app_boilerplate/data/sync/sync_engine.dart';
void main() {
// Initialize Flutter bindings and sqflite for testing
TestWidgetsFlutterBinding.ensureInitialized();
sqfliteFfiInit();
databaseFactory = databaseFactoryFfi;
late LocalStorageService localStorage;
late SessionService sessionService;
late Directory tempDir;
late String tempDbPath;
setUp(() async {
// Create temporary directory for test files
tempDir = await Directory.systemTemp.createTemp('session_test_');
tempDbPath = path.join(tempDir.path, 'test_storage.db');
// Initialize local storage service
localStorage = LocalStorageService(
testDbPath: tempDbPath,
testCacheDir: Directory(path.join(tempDir.path, 'cache')),
);
await localStorage.initialize();
// Initialize session service with test paths
// Each user will get their own subdirectory under tempDir
sessionService = SessionService(
localStorage: localStorage,
syncEngine: null, // No sync engine for basic tests
testDbPath: path.join(tempDir.path, 'user_storage.db'),
testCacheDir: Directory(path.join(tempDir.path, 'user_cache')),
);
});
tearDown(() async {
// Close and cleanup
try {
await localStorage.close();
} catch (_) {
// Ignore cleanup errors
}
// Clean up temporary directory
if (await tempDir.exists()) {
await tempDir.delete(recursive: true);
}
});
group('SessionService - Login', () {
test('login - success', () async {
// Arrange
const userId = 'user1';
const username = 'testuser';
// Act
final user = await sessionService.login(
id: userId,
username: username,
);
// Assert
expect(sessionService.isLoggedIn, isTrue);
expect(sessionService.currentUser, isNotNull);
expect(sessionService.currentUser!.id, equals(userId));
expect(sessionService.currentUser!.username, equals(username));
expect(user.id, equals(userId));
expect(user.username, equals(username));
});
test('login - with token', () async {
// Arrange
const userId = 'user1';
const username = 'testuser';
const token = 'auth-token-123';
// Act
final user = await sessionService.login(
id: userId,
username: username,
token: token,
);
// Assert
expect(sessionService.currentUser!.token, equals(token));
expect(user.token, equals(token));
});
test('login - fails when already logged in', () async {
// Arrange
await sessionService.login(id: 'user1', username: 'user1');
// Act & Assert
expect(
() => sessionService.login(id: 'user2', username: 'user2'),
throwsA(isA<SessionException>()),
);
});
});
group('SessionService - Logout', () {
test('logout - success', () async {
// Arrange
await sessionService.login(id: 'user1', username: 'user1');
expect(sessionService.isLoggedIn, isTrue);
// Act
await sessionService.logout();
// Assert
expect(sessionService.isLoggedIn, isFalse);
expect(sessionService.currentUser, isNull);
});
test('logout - clears cache when clearCache is true', () async {
// Arrange
await sessionService.login(id: 'user1', username: 'user1');
// Add some data to storage
final item = Item(
id: 'item1',
data: {'test': 'data'},
);
await localStorage.insertItem(item);
// Verify data exists
final itemsBefore = await localStorage.getAllItems();
expect(itemsBefore.length, equals(1));
// Act
await sessionService.logout(clearCache: true);
// Assert - data should be cleared
// Note: We need to reinitialize storage to check since it was cleared
await localStorage.initialize();
final itemsAfter = await localStorage.getAllItems();
expect(itemsAfter.length, equals(0));
});
test('logout - preserves cache when clearCache is false', () async {
// Arrange
await sessionService.login(id: 'user1', username: 'user1');
// Add some data to storage
final item = Item(
id: 'item1',
data: {'test': 'data'},
);
await localStorage.insertItem(item);
// Act
await sessionService.logout(clearCache: false);
// Assert - data should still exist (in user-specific storage)
// Note: Since we're using test paths, the data persists
expect(sessionService.isLoggedIn, isFalse);
});
test('logout - fails when no user logged in', () async {
// Act & Assert
expect(
() => sessionService.logout(),
throwsA(isA<SessionException>()),
);
});
});
group('SessionService - Session Switching', () {
test('switchSession - success', () async {
// Arrange
await sessionService.login(id: 'user1', username: 'user1');
expect(sessionService.currentUser!.id, equals('user1'));
// Act
final newUser = await sessionService.switchSession(
id: 'user2',
username: 'user2',
);
// Assert
expect(sessionService.isLoggedIn, isTrue);
expect(sessionService.currentUser!.id, equals('user2'));
expect(newUser.id, equals('user2'));
});
test('switchSession - clears previous user data when clearCache is true', () async {
// Arrange
await sessionService.login(id: 'user1', username: 'user1');
// Add data for user1
final item1 = Item(
id: 'item1',
data: {'user': 'user1'},
);
await localStorage.insertItem(item1);
// Act - switch to user2 with cache clearing
await sessionService.switchSession(
id: 'user2',
username: 'user2',
clearCache: true,
);
// Assert - user1 data should be cleared
// Reinitialize to check
await localStorage.initialize();
final items = await localStorage.getAllItems();
expect(items.length, equals(0));
});
test('switchSession - preserves previous user data when clearCache is false', () async {
// Arrange
await sessionService.login(id: 'user1', username: 'user1');
// Add data for user1
final item1 = Item(
id: 'item1',
data: {'user': 'user1'},
);
await localStorage.insertItem(item1);
// Act - switch to user2 without clearing cache
await sessionService.switchSession(
id: 'user2',
username: 'user2',
clearCache: false,
);
// Assert - user1 data should still exist in user1's storage
// (Note: user2 will have a different storage path)
expect(sessionService.currentUser!.id, equals('user2'));
});
test('switchSession - works when no user logged in', () async {
// Arrange
expect(sessionService.isLoggedIn, isFalse);
// Act
final user = await sessionService.switchSession(
id: 'user1',
username: 'user1',
);
// Assert
expect(sessionService.isLoggedIn, isTrue);
expect(user.id, equals('user1'));
});
});
group('SessionService - Data Isolation', () {
test('data isolation - users have separate storage', () async {
// Arrange & Act - Login user1 and add data
await sessionService.login(id: 'user1', username: 'user1');
final item1 = Item(
id: 'item1',
data: {'user': 'user1'},
);
await localStorage.insertItem(item1);
final user1Items = await localStorage.getAllItems();
expect(user1Items.length, equals(1));
expect(user1Items.first.id, equals('item1'));
// Switch to user2 (this will create a new database for user2)
await sessionService.switchSession(
id: 'user2',
username: 'user2',
clearCache: false, // Don't clear to test isolation
);
// Add data for user2 (should be in user2's database)
final item2 = Item(
id: 'item2',
data: {'user': 'user2'},
);
await localStorage.insertItem(item2);
final user2Items = await localStorage.getAllItems();
expect(user2Items.length, equals(1));
expect(user2Items.first.id, equals('item2'));
// Switch back to user1 (this will reload user1's database)
await sessionService.switchSession(
id: 'user1',
username: 'user1',
clearCache: false,
);
// Assert - user1 should only see their data (item1, not item2)
final user1ItemsAfter = await localStorage.getAllItems();
expect(user1ItemsAfter.length, equals(1));
expect(user1ItemsAfter.first.id, equals('item1'));
expect(user1ItemsAfter.first.data['user'], equals('user1'));
});
});
group('SessionService - Cache Clearing', () {
test('cache clearing - clears all items on logout', () async {
// Arrange
await sessionService.login(id: 'user1', username: 'user1');
// Add multiple items
await localStorage.insertItem(Item(id: 'item1', data: {'test': '1'}));
await localStorage.insertItem(Item(id: 'item2', data: {'test': '2'}));
await localStorage.insertItem(Item(id: 'item3', data: {'test': '3'}));
final itemsBefore = await localStorage.getAllItems();
expect(itemsBefore.length, equals(3));
// Act
await sessionService.logout(clearCache: true);
// Assert
await localStorage.initialize();
final itemsAfter = await localStorage.getAllItems();
expect(itemsAfter.length, equals(0));
});
});
}
Loading…
Cancel
Save

Powered by TurnKey Linux.