# HTTPMan - HTTP Client Application
## Overview
HTTPMan is a fast, modern HTTP client built with Rust and egui. It provides an intuitive interface for making HTTP requests with features like tab management, request persistence, and a hierarchical file system for organizing saved requests.
## Architecture
### Core Components
#### 1. Main Application (`src/main.rs`)
- **HttprsApp**: Main application state and UI controller
- **TabCtx**: Shared context providing access to storage and request dispatcher
- **RenameDialog**: Modal dialog state for folder renaming
- Handles UI layout, tab management, and user interactions
#### 2. Tab Management (`src/tab.rs`)
- **Tab**: Individual HTTP request tab with request/response data
- **PersistedTab**: Serializable version for file storage
- Features:
- HTTP method selection (GET, POST, PUT, DELETE, etc.)
- URL input with title generation
- Headers management (add/remove key-value pairs)
- Request body editing for methods that support it
- Response display with JSON tree, images, and binary file handling
- Automatic tab persistence on request send and response receipt
#### 3. Storage System (`src/storage.rs`)
- **Storage**: File system abstraction for persistent data
- **StorageItem**: Tree structure representing files and folders
- **TabAction**: Actions that can be performed on tree items
- Directory structure (OS-specific locations):
```
{OS_DATA_DIR}/httpman/
├── settings.json # App settings (active tab, sidebar width)
└── requests/
├── Tabs/ # Temporary tab storage
└── Saved/ # Permanent saved requests
└── Examples/ # Pre-created example requests
```
#### 4. HTTP Client (`src/http_client.rs`)
- Handles actual HTTP request execution using reqwest
- Supports:
- All HTTP methods
- Custom headers
- Request bodies
- Redirect following
- Response body parsing (text, JSON, images, binary)
- Error handling and timeout management
#### 5. Models (`src/models.rs`)
- **Request**: HTTP request data structure
- **DispatchedRequest/Response**: Async request/response wrappers
- **HttpMethod**: Enum for HTTP methods
- **ResponseBody**: Union type for different response formats
#### 6. Settings Management (`src/settings.rs`)
- **AppSettings**: Application configuration
- Persisted as JSON with fields:
- `active_tab_index`: Last active tab position
- `tab_bar_width`: Left sidebar width preference
#### 7. Request List (`src/request_list.rs`)
- Renders the hierarchical file tree in the left sidebar
- Handles tree interactions and returns actions to main app
## Features
### 1. Tab Management
- **Horizontal tab bar** at the top of main content area
- **Multiple tabs** with unique request configurations
- **Tab persistence**: Automatic saving of tab state
- **Context menu** on tabs:
- Close tab
- Save tab permanently to file system
- **Keyboard shortcuts**:
- Middle-click or double-click to close tab
- `+` button to create new tab
### 2. Request Configuration
- **HTTP Methods**: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
- **URL input** with automatic title generation from domain
- **Headers management**:
- Dynamic add/remove of header pairs
- Click "Delete" link to remove headers
- Click "+ New" to add header pairs
- **Request body**: Multi-line editor for methods that support bodies
- **Redirect handling**: Checkbox to follow redirects automatically
### 3. Response Display
- **HTTP status code** prominently displayed
- **Headers section**: Collapsible view of response headers
- **Response body** with intelligent formatting:
- **Text**: Plain text display
- **JSON**: Interactive tree view with expand/collapse
- **Images**: Inline image display
- **Binary files**: Download button with file size
- **Empty responses**: Special handling for redirects
### 4. File System Organization
- **Left sidebar** with resizable width (150-400px)
- **Hierarchical tree structure** for saved requests
- **File tree interactions**:
- 📄 **Files**: Clickable links to load saved requests
- 📁 **Folders**: Expandable/collapsible containers
- **Context menus**:
- **Right-click folder**: New Request, New Folder, Rename
- **Right-click root area**: New Folder
- **Double-click folder**: Rename dialog
### 5. Persistence & State Management
- **Automatic saving**:
- Tab state saved after sending requests
- Tab state saved after receiving responses
- Settings saved on UI changes (active tab, sidebar width)
- **Session restoration**:
- All tabs restored on app restart
- Active tab selection preserved
- Sidebar width preserved
- **File format**: MessagePack (`.httpmand` files) for compact binary storage
### 6. Background Processing
- **Async HTTP requests**: Non-blocking request execution
- **Single request queue**: One active request at a time per design
- **Automatic UI refresh**: Response updates trigger repaint
- **Error handling**: Network errors and timeouts handled gracefully
## Usage Guide
### First Run Experience
When you first launch HTTPMan, it will:
1. Create OS-specific data directories automatically
2. Generate two example tabs:
- **Bitcoin API**: GET request to `https://api.coingecko.com/api/v3/coins/bitcoin`
- **Random Image**: GET request to `https://picsum.photos/800`
3. Save example requests to the `Examples/` folder in the file tree
4. These examples demonstrate JSON API responses and image handling
### Basic HTTP Request
1. Click `+` to create a new tab
2. Select HTTP method from dropdown
3. Enter URL in text field
4. Add headers if needed (click "+ New")
5. Add request body for POST/PUT/PATCH requests
6. Click "Send" button
7. View response in lower panel
### Saving Requests
1. Configure your request in a tab
2. Right-click on the tab
3. Select "Save As..." from context menu
4. Request is saved to the file tree with auto-generated name
5. Access saved request from left sidebar tree
### Organizing Saved Requests
1. Right-click in file tree area → "New Folder"
2. Right-click on folder → "New Request" or "New Folder"
3. Double-click folder name to rename
4. Create hierarchical structure for project organization
### Loading Saved Requests
1. Navigate to saved request in left file tree
2. Click on the 📄 request file link
3. Request loads as new tab with all original data
4. Modify and re-send as needed
## Development
### Building
```bash
cargo build --release
```
### Running
```bash
cargo run
```
### Dependencies
- **egui**: Modern immediate mode GUI framework
- **eframe**: Native app framework for egui
- **reqwest**: HTTP client library
- **serde**: Serialization framework
- **rmp-serde**: MessagePack serialization
- **ulid**: Unique ID generation
- **tokio**: Async runtime
- **anyhow**: Error handling
- **directories**: OS-specific directory paths
### File Structure
```
src/
├── main.rs # Application entry and UI controller
├── tab.rs # Tab management and HTTP request UI
├── storage.rs # File system and persistence layer
├── settings.rs # Application settings management
├── request_list.rs # File tree UI component
├── http_client.rs # HTTP request execution
└── models.rs # Data structures and types
```
## Configuration
### Storage Locations
HTTPMan stores data in OS-specific application data directories:
- **Linux**: `~/.local/share/httpman/`
- **macOS**: `~/Library/Application Support/com.httpman.httpman/`
- **Windows**: `%APPDATA%\httpman\httpman\data\`
If the OS-specific directory cannot be determined, HTTPMan will fall back to creating a `.httpman` folder in the current working directory.
To locate your data directory, you can:
- **Linux**: `ls ~/.local/share/httpman/`
- **macOS**: `ls ~/Library/Application\ Support/com.httpman.httpman/`
- **Windows**: Navigate to `%APPDATA%\httpman\httpman\data\` in File Explorer
### Settings File (`{DATA_DIR}/settings.json`)
```json
{
"active_tab_index": 0,
"tab_bar_width": 200.0
}
```
### Data Directory Structure
```
{OS_DATA_DIR}/httpman/
├── settings.json
└── requests/
├── Tabs/ # Temporary tab storage (session restore)
│ ├── 01HXZ17JVMTG8V9PZFE7G24G8T.httpmand
│ └── ...
└── Saved/ # Permanent saved requests
├── Examples/ # Pre-created examples (first run)
│ ├── Bitcoin_Price_API.httpmand
│ └── Random_Image.httpmand
├── API_Tests/ # User-created folders
│ ├── login_request.httpmand
│ └── user_profile.httpmand
├── Development/
└── Production/
```
## Keyboard Shortcuts & Mouse Actions
| New tab | Click `+` button |
| Close tab | Right-click → Close, or double-click, or middle-click |
| Save tab | Right-click tab → Save As... |
| Switch tab | Click on tab |
| Rename folder | Double-click folder name, or right-click → Rename |
| New folder | Right-click in tree area → New Folder |
| New request in folder | Right-click folder → New Request |
| Load saved request | Click on 📄 file link in tree |
| Resize sidebar | Drag sidebar border |
## Error Handling
The application handles various error conditions gracefully:
- **Network errors**: Connection failures, timeouts, DNS resolution
- **File system errors**: Permission issues, disk full, invalid paths
- **Serialization errors**: Corrupted save files, version incompatibility
- **UI errors**: Invalid input, state corruption
Errors are logged to stderr and displayed as user-friendly messages where appropriate.
## Future Enhancements
Potential areas for expansion:
- Custom request naming instead of auto-generated names
- Request history and replay functionality
- Environment variable support for URLs and headers
- Authentication helpers (Basic, Bearer token, OAuth)
- Request scripting and testing capabilities
- Export/import of request collections
- Themes and customization options
- Performance monitoring and metrics
## Contributing
When contributing to HTTPMan:
1. **Follow Rust conventions**: Use `cargo fmt` and `cargo clippy`
2. **Maintain separation of concerns**: Keep UI, storage, and HTTP logic separate
3. **Handle errors gracefully**: Use `anyhow::Result` for error propagation
4. **Test thoroughly**: Verify both happy path and error conditions
5. **Update documentation**: Keep CLAUDE.md current with changes
6. **Consider backward compatibility**: Maintain save file format compatibility