spark_session

Session management middleware for Spark applications.

Features

• Cookie-based session IDs
• Multiple session stores: in-memory, file-based, SQLite
• Multi-session support (multiple named sessions per request)
• Sliding window expiration (refreshed on each request)
• Automatic cleanup of expired sessions
• Session destruction and cookie clearing
• Migration utility from file store to SQLite

Installation

dependencies:
  spark_session: ^1.0.0

Usage

Single Session

import 'package:spark_session/spark_session.dart';

final handler = Pipeline()
    .addMiddleware(sessionMiddleware(
      store: SqliteSessionStore(path: 'sessions.db'),
      cookieName: 'spark_session',
      maxAge: Duration(hours: 24),
      secure: true,
      httpOnly: true,
      sameSite: SameSite.strict,
    ))
    .addHandler(myRouter);

Multiple Named Sessions

final handler = Pipeline()
    .addMiddleware(multiSessionMiddleware([
      SessionConfig(name: 'user', maxAge: Duration(days: 30)),
      SessionConfig(name: 'cart', maxAge: Duration(hours: 2)),
      SessionConfig(name: 'admin', secure: true),
    ]))
    .addHandler(myRouter);

Working with Session Data

Response handleRequest(Request request) {
  final session = request.session;

  // Set values
  session.set('userId', '123');
  session.set('role', 'admin');

  // Get values (type-safe)
  final userId = session.get<String>('userId');

  // Remove a value
  session.remove('role');

  // Clear all data
  session.clear();

  // Check status
  session.isNew;       // newly created
  session.isChanged;   // modified
  session.data;        // read-only view

  return Response.ok('OK');
}

Destroying a Session (Logout)

Response handleLogout(Request request) {
  request.session.destroy();
  return Response.ok('Logged out');
}

Session Stores

// In-Memory (development)
InMemorySessionStore(cleanupInterval: Duration(minutes: 5))

// File-Based (persistent, single server)
FileSessionStore(path: './sessions')

// SQLite (persistent, scalable)
SqliteSessionStore(path: 'sessions.db')

Migration

// Migrate from file store to SQLite
await migrateFileSessionsToSqlite(
  fileStorePath: './sessions',
  sqlitePath: 'sessions.db',
);