Metadata-Version: 2.4
Name: aird
Version: 0.4.3
Summary: Aird - A lightweight web-based file browser, editor, and streamer with real-time capabilities
Home-page: https://github.com/blinkerbit/aird
Author: Viswantha Srinivas P
Author-email: psviswanatha@gmail.com
License: Custom
Classifier: Programming Language :: Python :: 3
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tornado>=6.5.1
Requires-Dist: ldap3>=2.9.1
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: argon2-cffi>=23.1.0
Provides-Extra: test
Requires-Dist: pytest>=8.3.3; extra == "test"
Requires-Dist: pytest-asyncio>=0.25.0; extra == "test"
Requires-Dist: pytest-mock>=3.14.0; extra == "test"
Requires-Dist: pytest-cov>=6.0.0; extra == "test"
Requires-Dist: pytest-tornado>=0.8.1; extra == "test"
Requires-Dist: coverage>=7.6.9; extra == "test"
Requires-Dist: mock>=5.1.0; extra == "test"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Aird - A Lightweight Web-Based File Browser, Editor and Share

**v0.4.2** - 🎨 **Custom HTML/CSS Popups + Enhanced Share Management + File Browser Navigation!**

A modern, lightweight, and fast web-based file browser, editor, and streamer built with Python and Tornado. It provides a comprehensive file management solution with real-time streaming, in-browser editing, and mobile-responsive design through a clean and intuitive web interface.

Note: Currently using this in conjunction with WireGuard to handle file management and sharing for internal/private cloud.

## 🆕 What's New in v0.4.2

### 🎨 **Custom HTML/CSS Popups (NEW!)**
- **Modern Dialog System:** Replaced all native browser alerts, confirms, and prompts with custom HTML/CSS modals
- **Consistent UI/UX:** Beautiful, responsive popups that match the application's design language
- **Enhanced User Experience:** Better visual feedback with styled buttons, proper spacing, and smooth animations
- **Cross-browser Compatibility:** Custom popups work consistently across all browsers and devices
- **Keyboard Support:** Full keyboard navigation with Enter to confirm and Escape to cancel
- **Accessibility:** Improved accessibility with proper focus management and screen reader support

### 🔗 **Enhanced Share Management (NEW!)**
- **Dynamic File Management:** Add and remove files from existing shares without recreating them
- **Interactive File Browser:** Navigate through directories to select additional files for sharing
- **Real-time Share Updates:** Instantly modify share contents with live preview of changes
- **Improved Share Modal:** Enhanced share management interface with better organization and controls
- **File Selection Preview:** See selected files before adding them to shares
- **Directory Navigation:** Full directory tree navigation within the share management interface

### 🗂️ **Advanced File Browser Navigation (NEW!)**
- **Full Directory Tree Access:** Navigate through all accessible directories when managing shares
- **Smart Path Handling:** Proper path construction and navigation for complex directory structures
- **File Type Recognition:** Enhanced file icons and type detection for better visual organization
- **Breadcrumb Navigation:** Clear path display showing current location in the directory tree
- **Error Handling:** Robust error handling with user-friendly messages for navigation issues

### 🛠️ **Backend API Enhancements (NEW!)**
- **Share Update API:** New endpoint for modifying existing shares with file additions/removals
- **Database Migration:** Automatic database schema updates for new share management features
- **Improved Error Handling:** Better error messages and status codes for API operations
- **Path Validation:** Enhanced security with proper path validation and sanitization

---

## 🆕 What's New in v0.4.1

### ⚙️ **WebSocket Admin Configuration (NEW!)**
- **Dynamic Settings:** Adjust WebSocket connection limits and timeouts through admin UI
- **Real-time Changes:** Settings apply instantly without server restart
- **Granular Control:** Separate limits for feature flags, file streaming, and search handlers
- **Performance Tuning:** Optimize for your specific traffic patterns and system resources
- **Live Statistics:** View connection stats at `/admin/websocket-stats`

### 🔍 **Super Search (NEW!)**
- **Powerful File Content Search:** Search through file contents across your entire directory tree
- **Real-time WebSocket Results:** Live search results as you type with instant feedback
- **Advanced Pattern Matching:** Support for regex patterns and multiple search terms
- **Path-aware Search:** Automatically filters results based on current directory context
- **Performance Optimized:** Fast searching even in large codebases using memory-mapped operations

### 🐍 **Enhanced Python File Icons (NEW!)**
- **Smart Python File Recognition:** Distinctive icons for different Python file types
- **Source Files (.py, .pyw):** Enhanced snake with gem (🐍💎) indicating precious/valuable source code
- **Compiled Files (.pyc, .pyo):** Snake with lightning (🐍⚡) representing fast/optimized compiled code
- **Better Visual Distinction:** Easily differentiate between source and compiled Python files at a glance
- **Consistent Branding:** Maintains Python's snake identity while adding meaningful visual context

### ⚡ **Performance & Usability Upgrades**
- **Direct Executable:** Run with simple `aird` command instead of `python -m aird`
- **50-80% Faster:** Memory-mapped file operations for massive performance gains
- **Enhanced Security:** CSRF protection, XSS prevention, and improved input validation
- **Memory Efficient:** Handle GB-sized files with constant ~64KB memory usage

---

## 🚀 Installation

### Option 1: Install from PyPI (Recommended)
```bash
pip install aird
```

### Option 2: Install from Source
1. **Clone the repository:**
   ```bash
   git clone https://github.com/blinkerbit/aird.git
   cd aird
   ```

2. **Create a virtual environment (recommended):**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

4. **Install the package:**
   ```bash
   pip install .
   ```

Run directly:
```bash
aird --help
```

<img width="1696" height="715" alt="image" src="https://github.com/user-attachments/assets/95a9569d-5d0c-4d96-aab9-69e0b4cd98bf" />

<img width="1599" height="1126" alt="image" src="https://github.com/user-attachments/assets/1551cafc-1d6e-4668-86fb-b1acb5fdb7b2" />

## ✨ Features

### 🔍 Super Search (NEW!)
- **Powerful Content Search:** Search through file contents across your entire directory tree with real-time results
- **WebSocket-powered:** Live search results as you type with instant feedback and progress indicators
- **Advanced Pattern Matching:** Support for regex patterns, case-sensitive/insensitive search, and multiple search terms
- **Path-aware Filtering:** Automatically filters results based on current directory context for focused searching
- **Smart Result Display:** Shows matching lines with context, file paths, and line numbers for easy navigation
- **Performance Optimized:** Fast searching even in large codebases using memory-mapped file operations
- **Interactive Interface:** Click any result to instantly navigate to the file and line

### 📁️ File Management
- **Smart File Browser:** Navigate through your server's directory structure with resizable columns and mobile-friendly design
- **Enhanced File Icons:** Intelligent file type recognition with special Python file icons:
  - **Python Source (\*.py, \*.pyw):** 🐍💎 Snake with gem (precious source code)
  - **Python Compiled (\*.pyc, \*.pyo):** 🐍⚡ Snake with lightning (optimized/fast)
  - **50+ File Types:** Comprehensive icon coverage for all common file formats
- **Advanced File Operations:**
  - Download files with progress indicators and compression support
  - Upload files with drag-and-drop support (can be disabled)
  - Delete files and directories (can be disabled)
  - Rename files and directories (can be disabled)
  - **In-browser File Editing:** Full-featured editor with syntax highlighting, line numbers, and memory safety
  - **Range-based Viewing:** View specific line ranges (start/end) without loading entire files
  - **Line-by-line Streaming:** Real-time file streaming for monitoring logs and large files
- **File Sharing:** Create secure, temporary public links for files and directories
  - Select multiple files and folders to share together
  - Generate unique, time-limited shareable URLs
  - No login required for shared link access
  - Manage active shares with easy revocation

### 📡 Real-time Streaming & Editing
- **WebSocket-based File Streaming:** Stream large files with animated progress indicators
- **Configurable Tail Lines:** Control how many recent lines to display when streaming (customizable Last N parameter)
- **Live File Monitoring:** Real-time updates as files change, perfect for log monitoring
- **Range-based File Viewing:** View specific line ranges without loading entire files
- **Dedicated Edit Mode:** Full-featured in-browser editor with:
  - Syntax highlighting and line numbers
  - Memory-safe editing (prevents loading huge files)
  - Save/Cancel operations with confirmation
  - Separate edit view for focused editing experience
- **Performance Optimized:** Stream line-by-line without loading entire files into memory
- **Memory Efficient:** Handles large files gracefully with size limits and streaming

### 🔐 Security & Authentication
- **Token-based Authentication:** Secure access with customizable access tokens
- **LDAP/Active Directory Integration:** Enterprise-grade authentication support
- **Path Traversal Protection:** Built-in security measures to prevent unauthorized access

### ⚙️ Administration
- **Admin Panel:** Dedicated admin interface to toggle features on the fly
- **Feature Flags:** Granular control over file operations (upload, delete, rename, edit, download)
- **Real-time Configuration:** Changes apply instantly without server restart

### 📱 Modern UI/UX
- **Mobile-Responsive Design:** Optimized for smartphones and tablets with touch-friendly controls
- **Real-time Search Interface:** Modern Super Search with live results and WebSocket updates
- **Resizable Columns:** Customize the file browser layout to your preference
- **Animated Indicators:** Visual feedback for streaming, searching, and loading operations
- **Intuitive Interface:** Clean, minimalist design with well-organized toolbars
- **Streaming Controls:** Dedicated streaming toolbar with configurable options (Last N lines, play/stop controls)
- **Interactive Results:** Click-to-navigate search results with context highlighting
- **Keyboard Shortcuts:** Efficient navigation and operations via keyboard
- **Clean Layout:** Left-aligned file actions, right-aligned streaming controls for better organization
- **Custom HTML/CSS Popups (NEW!):** Modern dialog system replacing all native browser popups
- **Enhanced Share Management UI (NEW!):** Improved share management interface with better organization
- **File Browser Navigation (NEW!):** Full directory tree navigation with breadcrumb display

## 📖 Usage

### Quick Start

After installation, you can run Aird using the `aird` command:

```bash
# Basic usage with a specific port
aird --port 8000

# A token will be generated and printed. To specify one:
aird --port 8000 --token "your-secret-token"

# With admin capabilities
aird --port 8000 --token "user-token" --admin-token "admin-token"

# Serve from a specific directory
aird --root "/path/to/files" --token "your-token"
```

Navigate to `http://localhost:8000` and enter your access token to start browsing files.

### 🎮 Command-Line Arguments

| Argument        | Description                                         | Default                               |
| --------------- | --------------------------------------------------- | ------------------------------------- |
| `--port`        | The port to listen on                               | `8000`                                |
| `--root`        | The root directory to serve files from              | Current directory                     |
| `--token`       | The token required for user login                   | (auto-generated)                      |
| `--admin-token` | The token required for admin login                  | (auto-generated)                      |
| `--hostname`    | Host name for the server, used for display          | (auto-detected)                       |
| `--config`      | Path to a JSON configuration file                   | `None`                                |
| `--ldap`        | Enable LDAP authentication                          | `False`                               |
| `--ldap-server` | The LDAP server address (required if --ldap)        | `None`                                |
| `--ldap-base-dn`| The base DN for LDAP searches (required if --ldap)  | `None`                                |

### ⚙️ Configuration File

For advanced setups, use a JSON configuration file to define all settings:

**Example `config.json`:**
```json
{
  "host": "0.0.0.0",
  "port": 8080,
  "root_dir": "/path/to/your/files",
  "access_token": "your-secret-token",
  "admin_token": "your-admin-secret-token",
  "enable_ldap": false,
  "ldap_server": null,
  "ldap_base_dn": null,
  "feature_flags": {
    "file_upload": true,
    "file_delete": true,
    "file_rename": true,
    "file_download": true,
    "file_edit": true
  },
  "max_file_size": 10485760,
  "max_readable_file_size": 10485760,
  "chunk_size": 65536
}
```

Run with configuration file:
```bash
aird --config /path/to/config.json
```

### 🔐 LDAP Authentication

For enterprise environments, enable LDAP authentication:

```bash
aird --enable-ldap \
     --ldap-server "ldap://your.ldap.server" \
     --ldap-base-dn "ou=users,dc=example,dc=com" \
     --access-token "fallback-token"
```

Users can authenticate with their LDAP credentials, with token authentication as fallback.

### 🔍 Super Search

The Super Search feature provides powerful, real-time content searching across your entire file system:

1. **Access Super Search:**
   - Click the "🚀 Super Search" button in the main file browser
   - Or navigate directly to `/search` after logging in

2. **Search Interface:**
   - **Search Query:** Enter text, regex patterns, or multiple terms to find
   - **Current Path:** Automatically set based on your current directory (can be modified)
   - **Case Sensitive:** Toggle case-sensitive matching on/off
   - **Max Results:** Limit the number of results to control performance

3. **Real-time Results:**
   - Results appear instantly as you type via WebSocket connection
   - See matching lines with surrounding context for better understanding
   - Click any result to navigate directly to the file and specific line
   - Progress indicators show search status and completion

4. **Advanced Features:**
   - **Regex Support:** Use regular expressions for complex pattern matching
   - **Path Filtering:** Search within specific directories or file types
   - **Context Lines:** See surrounding lines for better match understanding
   - **Performance Optimized:** Fast searching even in large codebases

**Example URLs:**
- Super Search page: `http://localhost:8888/search`
- Search with preset path: `http://localhost:8888/search?path=/specific/folder`

### 🔗 Enhanced File Sharing

The enhanced file sharing feature allows you to create and manage public, temporary links for files and directories:

1. **Access the Share Page:**
   - Navigate to `/share` after logging in
   - Or click the "Share Files" button in the main file browser

2. **Select Files to Share:**
   - Browse directories and select files using checkboxes
   - Navigate between folders to select files from different locations
   - Use "Select All (Current Dir)" to quickly select all visible files

3. **Generate Share Links:**
   - Click "Generate Share Link" after selecting files
   - Copy the generated URL using the "Copy Link" button
   - Share the URL with others for public access (no login required)

4. **Manage Active Shares:**
   - View all active shares in the bottom panel
   - Copy existing share links or open them in a new tab
   - **NEW:** Click "Manage" to modify existing shares

5. **Enhanced Share Management (NEW!):**
   - **Add Files:** Click "Add Files" to browse and select additional files for existing shares
   - **Remove Files:** Click "Remove" next to any file to remove it from the share
   - **Directory Navigation:** Use the file browser to navigate through all accessible directories
   - **File Selection Preview:** See selected files before adding them to shares
   - **Real-time Updates:** Changes apply instantly without recreating the share

6. **Custom Dialog System (NEW!):**
   - All confirmations and prompts use modern HTML/CSS popups
   - Consistent UI/UX across all share management operations
   - Keyboard support with Enter to confirm and Escape to cancel

**Example URLs:**
- Share page: `http://localhost:8888/share`
- Public shared files: `http://localhost:8888/shared/abc123def456`

## 👑 Admin Panel

The admin panel provides real-time control over server features and capabilities.

### Access the Admin Panel

1. **Start server with admin token:**
   ```bash
   aird --admin-token "your-admin-secret-token"
   ```

2. **Navigate to admin interface:**
   Visit `http://localhost:8888/admin` and authenticate with your admin token

3. **Feature Management:**
   - **File Upload:** Toggle file upload capability
   - **File Delete:** Enable/disable file and directory deletion
   - **File Rename:** Control rename functionality
   - **File Edit:** Toggle in-browser file editing
   - **File Download:** Control file download access
   - **File Share:** Enable/disable file sharing functionality

4. **WebSocket Connection Management (NEW!):**
   - **Feature Flags WebSocket:** Configure max connections (1-1000) and idle timeout (30-7200s)
   - **File Streaming WebSocket:** Optimize settings for high-traffic file operations
   - **Search WebSocket:** Tune search handler performance limits
   - **Real-time Statistics:** View live connection stats at `/admin/websocket-stats`
   - **Dynamic Configuration:** All settings apply instantly without restart

All changes apply immediately to all connected users via WebSocket updates.

## 🎯 Key Features in Detail

### 🔍 Super Search (Latest Feature!)
- **Content-based Search:** Find text within files across your entire directory structure
- **Real-time Results:** Live search with WebSocket updates as you type
- **Regex Support:** Advanced pattern matching with regular expressions
- **Context Display:** See matching lines with surrounding context for better understanding
- **Performance Optimized:** Memory-mapped operations for fast searching in large codebases
- **Interactive Navigation:** Click any result to jump directly to the file and line

### 📝 In-Browser File Editing
- **Real-time editing** with syntax highlighting
- **Line numbers** with toggle capability
- **Auto-save functionality** with keyboard shortcuts
- **Large file support** with efficient loading
- **Responsive design** for mobile editing

### 📊 File Browser Enhancements
- **Resizable columns** for Name, Size, and Modified date
- **Mobile-optimized** responsive layout
- **Drag-and-drop upload** with visual feedback
- **Real-time file streaming** with progress animations
- **Keyboard navigation** support

### 🔗 Enhanced File Sharing System
- **Multi-file selection:** Choose multiple files and directories to share in a single link
- **Dynamic Share Management:** Add and remove files from existing shares without recreating them
- **Interactive File Browser:** Navigate through directories to select additional files for sharing
- **Real-time Share Updates:** Instantly modify share contents with live preview of changes
- **On-the-fly browsing:** Navigate directories dynamically without pre-loading all files
- **Secure URL generation:** Each share gets a unique, hard-to-guess identifier
- **Public access:** Shared files can be viewed without authentication
- **Active share management:** View, copy, and revoke existing shares in real-time
- **One-click copy:** Copy shareable URLs to clipboard with visual feedback
- **Temporary access:** All shares are session-based and can be easily revoked
- **Custom HTML/CSS Popups:** Modern dialog system for all share management operations

### 🚀 Performance Features (New in v0.4.1!)
- **Enhanced Python File Icons:** Smart visual distinction between source (🐍💎) and compiled (🐍⚡) Python files
- **Memory-mapped file operations:** Efficient handling of large files (>1MB) using mmap
- **Enhanced security:** CSRF protection, XSS prevention, improved input validation
- **Direct executable support:** Run with simple `aird` command instead of `python -m aird`
- **Chunked file operations** for large files
- **Async WebSocket streaming** for real-time updates
- **Configurable buffer sizes** for optimal performance
- **Memory-efficient** file handling with constant memory usage

### 🛠️ Technical Improvements (New in v0.4.2!)
- **Database Schema Migration:** Automatic database updates for new share management features
- **API Endpoint Enhancements:** New `/share/update` endpoint for dynamic share modifications
- **Path Validation & Security:** Enhanced path handling and validation for file operations
- **Error Handling Improvements:** Better error messages and status codes throughout the application
- **Frontend Architecture:** Modular JavaScript functions for better maintainability
- **Cross-browser Compatibility:** Improved compatibility across different browsers and devices
- **Accessibility Enhancements:** Better keyboard navigation and screen reader support

### 🐛 Bug Fixes & Improvements (New in v0.4.2!)
- **Fixed Share Management:** Resolved "Failed to load share details" error in share management modal
- **Fixed File Browser Navigation:** Corrected directory navigation issues in the Add Files modal
- **Fixed API Response Handling:** Proper handling of API responses for file listing and share management
- **Fixed Path Construction:** Corrected path building logic for file and directory operations
- **Fixed Console Popup Dependencies:** Replaced all native browser popups with custom HTML/CSS modals
- **Fixed Async Dialog Handling:** Proper async/await handling for all confirmation dialogs
- **Fixed File Selection State:** Corrected file selection state management in share management
- **Fixed Error Display:** Improved error message display and user feedback throughout the application

## 📋 Requirements

### **Core Requirements**
- **Python:** 3.10 or higher
- **Dependencies:** Tornado, ldap3, aiofiles (automatically installed)
- **Storage:** Minimal disk space for the application
- **Network:** HTTP/HTTPS and WebSocket support

### **Development Requirements**
For development and testing, additional dependencies are available in the test extras:
```bash
pip install -e .[test]
```

This includes:
- **Testing frameworks:** pytest, pytest-asyncio, pytest-mock, pytest-cov
- **Development tools:** coverage, mock for comprehensive testing

## 🧪 Testing

The project includes a comprehensive test suite with multiple testing utilities:

### Running Tests
```bash
# Run all tests
python run_tests.py

# Run with coverage
python run_coverage.py

# Run specific test files
pytest tests/test_handlers.py

# Run tests with verbose output
pytest -v
```

### Test Coverage
- **Comprehensive Coverage:** Tests for all major components including handlers, utilities, and database operations
- **WebSocket Testing:** Real-time functionality testing with pytest-tornado
- **File Operations:** Testing file streaming, editing, and sharing features
- **Security Testing:** Path traversal protection and authentication testing
- **Performance Testing:** Large file handling and memory efficiency tests

## 🤝 Contributing

We welcome contributions! Here's how you can help:

1. **Fork the repository**
2. **Create a feature branch:** `git checkout -b feature/amazing-feature`
3. **Make your changes** and test thoroughly
4. **Commit your changes:** `git commit -m 'Add amazing feature'`
5. **Push to the branch:** `git push origin feature/amazing-feature`
6. **Open a Pull Request**

### Development Setup

```bash
git clone https://github.com/blinkerbit/aird.git
cd aird
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -e .  # Install in development mode
```

## 👥 Contributors & Thanks

We extend our heartfelt gratitude to all contributors who have helped make aird better:

### 💡 Community Contributors
A special thanks to everyone who has contributed through:
- **Bug reports and feature requests**
- **Code contributions and pull requests** 
- **Documentation improvements**
- **Testing and feedback**
- **Spreading the word about aird**

### 🔧 Feature Contributors
Thanks to all contributors who helped implement key features:
- **File editing capabilities** with syntax highlighting
- **Mobile-responsive design** and resizable columns
- **Real-time streaming** with WebSocket support
- **Admin panel** with live feature toggling
- **Security enhancements** and path traversal protection

*Want to see your name here? Check out our [Contributing Guidelines](#-contributing) and join our community!*

---

**🎉 Thank you to all our stars, forks, and users who make this project worthwhile!**

If you've benefited from aird, consider:
- ⭐ **Starring the repository**
- 🍴 **Forking and contributing**
- 🐛 **Reporting issues**
- 💝 **Sharing with others**

## 📄 License

This project is licensed under a **Custom License** that prohibits commercial use without explicit written consent from the author. See the `LICENSE` file for complete details.

### Key License Points:
- ✅ **Free for personal and non-commercial use**
- ✅ **Open source for educational purposes**
- ❌ **Commercial use requires written permission** (usually given for free, but requires written consent.) 
- ❌ **No warranty or liability coverage**

## 🔗 Links

- **GitHub Repository:** [https://github.com/blinkerbit/aird](https://github.com/blinkerbit/aird)
- **PyPI Package:** [https://pypi.org/project/aird/](https://pypi.org/project/aird/)
- **Issue Tracker:** [https://github.com/blinkerbit/aird/issues](https://github.com/blinkerbit/aird/issues)

## 🎯 Roadmap & Future Plans

### 🔜 Upcoming Features
- **File Previews:** In-browser previews for images, PDFs, and Markdown
- **Enhanced Search:** Advanced search filters, file type filtering, and search history
- **Multi-File Operations:** Batch actions for multiple files
- **Theme Support:** Dark mode and customizable themes

### 🚀 Advanced Features (Planned)
- **User Management:** Role-based permissions system
- **File History:** Version tracking and backup features
- **API Integration:** RESTful API for external integrations
- **Plugin System:** Extensible architecture for custom features

---

**Made with ❤️ by Viswantha Srinivas P**

*Star ⭐ this repo if you find it useful!*
