Session Storage

File-based session storage that persists session data to the filesystem with automatic expiration handling and secure session ID generation.

Capabilities

Create File Session Storage

Creates a SessionStorage that stores session data on a filesystem with automatic cleanup of expired sessions.

/**
 * Creates a SessionStorage that stores session data on a filesystem
 * @param options - Configuration options for file session storage
 * @returns SessionStorage instance for managing sessions
 */
function createFileSessionStorage<Data = SessionData, FlashData = Data>(
  options: FileSessionStorageOptions
): SessionStorage<Data, FlashData>;

interface FileSessionStorageOptions {
  /** The Cookie used to store the session id on the client, or options used to automatically create one */
  cookie?: SessionIdStorageStrategy["cookie"];
  /** The directory to use to store session files */
  dir: string;
}

Usage Examples:

import { createFileSessionStorage } from "@remix-run/node";

// Basic file session storage
const sessionStorage = createFileSessionStorage({
  dir: "/tmp/sessions"
});

// With custom cookie configuration
const sessionStorage = createFileSessionStorage({
  dir: "./app/sessions",
  cookie: {
    name: "__session",
    maxAge: 86400, // 24 hours
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
    sameSite: "lax",
    secrets: ["session-secret-key"]
  }
});

// Use in a Remix loader
export async function loader({ request }: LoaderFunctionArgs) {
  const session = await sessionStorage.getSession(
    request.headers.get("Cookie")
  );
  
  const userId = session.get("userId");
  
  return json({ userId });
}

// Use in a Remix action
export async function action({ request }: ActionFunctionArgs) {
  const session = await sessionStorage.getSession(
    request.headers.get("Cookie")
  );
  
  session.set("userId", "user123");
  
  return redirect("/dashboard", {
    headers: {
      "Set-Cookie": await sessionStorage.commitSession(session)
    }
  });
}

File Organization:

Session files are organized using a two-level directory structure to optimize filesystem performance:

• Session ID is split into directory (first 4 characters) and filename (remaining characters)
• Maximum of 2^16 directories, each with up to 2^48 files
• Example: Session ID abcd1234567890ef becomes /sessions/abcd/1234567890ef

Security Features:

• Cryptographically secure session IDs: Uses Node.js Web Crypto API for random session ID generation
• Automatic collision avoidance: Regenerates IDs if file already exists
• Automatic cleanup: Expired sessions are automatically removed when accessed
• Large ID space: 2^64 possible session IDs prevent brute force attacks

Storage Operations:

The file session storage handles all standard session operations:

• Create: Generates unique session ID and stores data as JSON
• Read: Retrieves session data and checks expiration
• Update: Updates existing session data with new expiration
• Delete: Removes session file from filesystem
• Commit: Serializes session changes to cookie
• Destroy: Removes session and clears cookie

Error Handling:

• ENOENT errors: Gracefully handled for missing session files
• EEXIST errors: Handled during session ID collision resolution
• Permission errors: Automatically creates directory structure
• Expired sessions: Automatically cleaned up on access

Performance Considerations:

• Lazy evaluation: Sessions are only read when accessed
• Atomic writes: Uses wx flag to prevent race conditions
• Directory structure: Optimized for filesystems with large file counts
• JSON serialization: Simple and efficient session data storage