feat: add session snapshot persistence and restoration

[chirag-bruno]

Description

Implements automatic session state persistence that saves and restores:

• Open collections with mount status and collapsed/expanded state
• Active workspace and environment selections
• Open tabs with full pane state (active sub-tabs, widths, heights)
• DevTools state (open/closed, active tab, height)

Key features:

• Lazy loading: only mounts collections that were previously mounted
• Stable UIDs: uses hash-based UIDs for reliable item matching across sessions
• Race condition handling: query-based mount completion tracking
• Debounced saves: snapshots saved 1 second after state changes
• Theme-aware loading screen with granular progress messages

Files added:

• AppSnapshotStore for electron-side persistence
• Snapshot middleware for Redux state serialization
• AppLoader component for restore progress display
• Snapshot utilities for serialization/deserialization

Contribution Checklist:

• I've used AI significantly to create this pull request
• The pull request only addresses one issue or adds one feature.
• The pull request does not introduce any breaking changes
• I have added screenshots or gifs to help explain the change if applicable.
• I have read the contribution guidelines.
• Create an issue and link to the pull request.

Note: Keeping the PR small and focused helps make it easier to review and merge. If you have multiple changes you want to make, please consider submitting them as separate pull requests.

Publishing to New Package Managers

Please see here for more information.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 7ff91757-2d4e-4afa-a900-60f2370b8857

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chirag-bruno]

Session Snapshot Architecture

Overview

The Session Snapshot feature provides automatic persistence and restoration of the user's application state across app restarts. This includes open tabs, active workspace, collection states, selected environments, and DevTools configuration.

Design Goals

1. Seamless Experience: Users should be able to close and reopen Bruno without losing their working context
2. Lazy Loading: Collections are mounted on-demand when their workspace is visited, not at startup
3. Race Condition Safety: Handle async IPC message processing during collection mounting
4. Minimal Performance Impact: Debounced saves, efficient serialization

---

Architecture Components

1. Storage Layer (Electron Main Process)

File: packages/bruno-electron/src/store/app-snapshot.js

┌─────────────────────────────────────────────────────────┐
│                    AppSnapshotStore                     │
├─────────────────────────────────────────────────────────┤
│  Storage: ~/Library/Application Support/bruno/         │
│           app-snapshot.json                             │
├─────────────────────────────────────────────────────────┤
│  Methods:                                               │
│    - getSnapshot() → snapshot object                    │
│    - saveSnapshot(snapshot) → persists to disk          │
└─────────────────────────────────────────────────────────┘

Uses electron-store for atomic JSON file operations with automatic error recovery via clearInvalidConfig: true.

2. IPC Handlers

File: packages/bruno-electron/src/ipc/preferences.js

Handler	Direction	Purpose
renderer:get-app-snapshot	Renderer → Main	Load snapshot at startup
renderer:save-app-snapshot	Renderer → Main	Persist snapshot on state changes
renderer:is-collection-mount-complete	Renderer → Main	Check if collection file watcher has finished

---

Snapshot Schema (Version 1)

{
  "version": 1,
  "activeWorkspacePathname": "/path/to/workspace",
  "workspaces": [
    {
      "pathname": "/path/to/workspace",
      "collections": [
        {
          "pathname": "/path/to/collection",
          "isMounted": true,
          "isOpen": true,
          "environment": "production",
          "tabs": [...],
          "activeTabIndex": 0
        }
      ]
    }
  ],
  "collections": [...],  // Flattened for quick lookup
  "extras": {
    "devTools": {
      "open": false,
      "tab": "console",
      "height": 300
    }
  }
}

Tab Schema

Tabs are serialized using relative paths to ensure portability:

{
  "type": "item",           // "item" | "preferences" | "runner" | "variables" | etc.
  "permanent": true,        // Not a preview tab
  "itemPath": "folder/request.bru",  // Relative to collection root
  "layout": "horizontal",
  "request": {
    "tab": "body",
    "width": 0,
    "height": 0
  },
  "response": {
    "tab": "response",
    "format": null,
    "preview": false
  }
}

Tab Type Mappings

Redux Type	Schema Type	Notes
request, http-request, graphql-request, grpc-request, ws-request	item	All request types serialize as "item"
folder-settings	item	Folders also use "item" with folder path
collection-settings	collection
environment-settings	environment
collection-runner	runner
variables	variables
preferences	preferences

---

Serialization Flow

File: packages/bruno-app/src/utils/app-snapshot/index.js

┌─────────────────────────────────────────────────────────────────┐
│                     serializeAppSnapshot(state)                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Extract state slices:                                       │
│     - collections, tabs, workspaces, logs, app, preferences     │
│                                                                 │
│  2. Filter collections:                                         │
│     - Exclude scratch/transient collections                     │
│     - Identify by scratchCollectionUid or path patterns         │
│                                                                 │
│  3. Group tabs by collection:                                   │
│     - Skip tabs for scratch collections                         │
│     - Build tabsByCollection map                                │
│                                                                 │
│  4. Serialize each collection:                                  │
│     - pathname (absolute)                                       │
│     - isMounted (from mountStatus)                              │
│     - isOpen (inverse of collapsed)                             │
│     - environment (name lookup from activeEnvironmentUid)       │
│     - tabs (serialized via serializeTab)                        │
│     - activeTabIndex                                            │
│                                                                 │
│  5. Preserve pending restores:                                  │
│     - For workspaces not yet visited, keep their restore data   │
│                                                                 │
│  6. Serialize workspaces with collection references             │
│                                                                 │
│  7. Add extras (DevTools state)                                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Function: serializeTab(tab, collection, preferences)

// For item tabs (requests, folders):
1. Look up item in collection by tab.uid
2. Convert absolute pathname to relative path
3. Capture request/response pane states
4. Return null if item not found (tab won't be saved)

// For non-item tabs (settings, preferences, etc.):
1. Map type to schema type
2. Don't include itemPath

---

Deserialization Flow

File: packages/bruno-app/src/utils/app-snapshot/restore.js

Key Function: deserializeTab(tabSchema, collection)

┌─────────────────────────────────────────────────────────────────┐
│                    deserializeTab(tabSchema, collection)        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  For non-item tabs:                                             │
│    1. Map schema type → Redux tab type                          │
│    2. Generate UID using collection.uid + suffix                │
│       e.g., "abc123-environment-settings"                       │
│                                                                 │
│  For item tabs:                                                 │
│    1. Find item by relative path (findItemByRelativePath)       │
│    2. If folder: set type to "folder-settings", add folderUid   │
│    3. If request: use item.type (http-request, etc.)            │
│    4. Use item.uid as tab UID                                   │
│    5. Restore request/response pane states                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Tab UID Generation

Tab Type	UID Pattern	Example
Request/Folder	item.uid	"a1b2c3d4"
Environment Settings	${collection.uid}-environment-settings	"xyz-environment-settings"
Collection Settings	${collection.uid}-collection-settings	"xyz-collection-settings"
Variables	${collection.uid}-variables	"xyz-variables"
Collection Runner	${collection.uid}-runner	"xyz-runner"
Preferences	${collection.uid}-preferences	"xyz-preferences"

---

Restoration Flow

Startup Sequence

┌─────────────────────────────────────────────────────────────────┐
│                        App Startup                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. App mounts, Redux store initializes                         │
│     - snapshotSaveEnabled = false (prevent saves during load)   │
│     - isRestoringSnapshot = false                               │
│                                                                 │
│  2. workspaceOpenedEvent fires for default workspace            │
│     - Sets isInitialLoadComplete = true                         │
│                                                                 │
│  3. restoreAppSnapshot() is dispatched                          │
│     - Sets isRestoringSnapshot = true                           │
│     - Shows AppLoader overlay                                   │
│                                                                 │
│  4. Wait for initial load complete                              │
│                                                                 │
│  5. Load snapshot from main process                             │
│                                                                 │
│  6. Build restore sequence:                                     │
│     - Parse DevTools state                                      │
│     - Identify collections to mount                             │
│     - Map tabs to restore per collection                        │
│                                                                 │
│  7. Restore DevTools state immediately                          │
│                                                                 │
│  8. Set up pending workspace restores:                          │
│     - For each workspace in snapshot, store its restore data    │
│     - Keyed by workspace pathname                               │
│                                                                 │
│  9. Switch to active workspace from snapshot                    │
│     - Triggers restoreWorkspaceState for that workspace         │
│                                                                 │
│  10. Enable snapshot saving                                     │
│      - snapshotSaveEnabled = true                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Lazy Workspace Restoration

File: packages/bruno-app/src/providers/ReduxStore/slices/workspaces/actions.js

┌─────────────────────────────────────────────────────────────────┐
│                  switchWorkspace(workspaceUid)                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Set active workspace                                        │
│                                                                 │
│  2. Load global environments                                    │
│                                                                 │
│  3. Mount scratch collection                                    │
│                                                                 │
│  4. Load workspace collections (lazy mount)                     │
│                                                                 │
│  5. Check for pending restore:                                  │
│     IF pendingWorkspaceRestores[workspace.pathname]:            │
│       → restoreWorkspaceState(collections)                      │
│       → clearPendingWorkspaceRestore                            │
│     ELSE IF workspace not hydrated:                             │
│       → Show default overview tabs                              │
│     ELSE:                                                       │
│       → Focus existing tab from workspace                       │
│                                                                 │
│  6. Mark workspace as hydrated                                  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Collection Restoration

┌─────────────────────────────────────────────────────────────────┐
│           restoreWorkspaceState(collectionsToRestore)           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  For each collection (parallel, max 4 concurrent):              │
│                                                                 │
│    1. Find or open collection                                   │
│                                                                 │
│    2. Set collapsed state (isOpen)                              │
│                                                                 │
│    3. If was mounted:                                           │
│       a. Trigger mount if not already mounted                   │
│       b. Wait for mount complete (with stability check)         │
│       c. Select environment by name                             │
│       d. Restore tabs via restoreTabsForCollection              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

Mount Completion Detection

File: packages/bruno-app/src/utils/collection-mount.js

The Race Condition Problem

When a collection is mounted:

1. Main process sends IPC messages for each file
2. Renderer processes messages asynchronously
3. collection.isLoading becomes false when main process finishes
4. But renderer may still be processing messages!

Main Process:     [scan files] [send IPCs] [done]
                                            ↓ isLoading = false
Renderer:         [receive] [receive] [receive] [receive] ...
                                       ↑
                        Tab restore attempted here = RACE CONDITION

Solution: Item Count Stability

export const createItemsLoadedChecker = () => {
  let lastItemCount = -1;
  let stableCount = 0;

  return (collection) => {
    // 1. Check mount status and loading state
    if (!collection.mountStatus === 'mounted' || areItemsLoading(collection)) {
      return { ready: false };
    }

    // 2. Check item count stability
    const currentItemCount = flattenItems(collection.items).length;

    if (currentItemCount === lastItemCount) {
      stableCount++;
      if (stableCount >= 3) {  // Stable for 300ms (3 × 100ms polls)
        return { ready: true };
      }
    } else {
      lastItemCount = currentItemCount;
      stableCount = 1;
    }

    return { ready: false, reason: 'stabilizing' };
  };
};

This ensures all IPC messages have been processed before attempting tab restoration.

---

Save Triggering (Middleware)

File: packages/bruno-app/src/providers/ReduxStore/middlewares/snapshot/middleware.js

Debounced Saves

const DEBOUNCE_DELAY = 1000;  // 1 second

const actionsToIntercept = [
  // Tab actions
  'tabs/addTab', 'tabs/focusTab', 'tabs/closeTabs', ...

  // Workspace actions
  'workspaces/setActiveWorkspace',

  // Collection actions
  'collections/selectEnvironment', 'collections/setCollectionCollapsed', ...

  // DevTools actions
  'logs/openConsole', 'logs/closeConsole', ...
];

// Middleware intercepts these actions and schedules a debounced save

Save Flow

Action dispatched → Middleware intercepts → Schedule save (1s debounce)
                                                    ↓
                                            Save still pending?
                                                    ↓
                                            Serialize state
                                                    ↓
                                            IPC to main process
                                                    ↓
                                            Write to disk

---

State Management

App Slice Additions

// packages/bruno-app/src/providers/ReduxStore/slices/app.js

initialState: {
  isInitialLoadComplete: false,    // True after default workspace loads
  isRestoringSnapshot: false,      // True during restore (shows loader)
  snapshotRestoreMessage: null,    // Loading message for UI
  snapshotSaveEnabled: false,      // False during restore to prevent saves
  pendingWorkspaceRestores: {},    // Keyed by workspace pathname
}

Tabs Slice Additions

// New action: restoreTabs
// Bulk adds tabs without triggering individual addTab actions
// Handles folderUid for folder-settings tabs

Workspace Hydration Tracking

// packages/bruno-app/src/utils/workspace-hydration.js

// In-memory Set tracking which workspaces have been restored
// Prevents re-applying default tabs when switching back to a workspace

---

UI Components

AppLoader

File: packages/bruno-app/src/components/AppLoader/index.js

Full-screen overlay shown during snapshot restoration:

• Theme-aware styling
• Animated spinner
• Dynamic message from snapshotRestoreMessage

---

Edge Cases Handled

1. Deleted Files/Folders

• findItemByRelativePath returns null
• Tab is not restored (silently skipped)
• Warning logged for debugging

2. Renamed Collections

• Snapshot uses absolute paths
• Collection won't be found if renamed
• Opens with default state instead

3. Multiple Workspaces

• Each workspace has its own pending restore data
• Lazy loading only restores when workspace is visited
• Prevents heavy startup load

4. Folder Tabs

• Folders require folderUid property in tab
• restoreTabs reducer preserves this property
• UI looks up folder by focusedTab.folderUid

5. Non-Item Tabs

• Settings tabs use deterministic UIDs (collection.uid + suffix)
• Don't require item lookup
• Always restorable if collection exists

---

File Summary

File	Purpose
utils/app-snapshot/index.js	Serialization functions
utils/app-snapshot/restore.js	Deserialization functions
utils/collection-mount.js	Mount completion detection
utils/workspace-hydration.js	Workspace visit tracking
middlewares/snapshot/middleware.js	Save triggering
slices/app.js	Snapshot state management
slices/tabs.js	restoreTabs action
slices/workspaces/actions.js	Restore orchestration
components/AppLoader/index.js	Loading UI
store/app-snapshot.js (electron)	Disk persistence
ipc/preferences.js (electron)	IPC handlers