0
# Web Interface
1

2
Web-based user interface providing interactive monitoring and management capabilities with authentication support and comprehensive dashboard views.
3

4
## Capabilities
5

6
### Base Handler
7

8
Foundation class for all web interface handlers with authentication and template rendering.
9

10
```python { .api }
11
class BaseHandler(tornado.web.RequestHandler):
12
    """
13
    Base class for all web view handlers.
14
    
15
    Provides authentication, template rendering, and common functionality
16
    for web interface pages.
17
    """
18
    
19
    def render(self, *args, **kwargs):
20
        """
21
        Render template with Flower-specific context.
22
        
23
        Args:
24
            *args: Template name and context arguments
25
            **kwargs: Template context variables
26
            
27
        Adds common context variables like current user, application state,
28
        and configuration options to all rendered templates.
29
        """
30
    
31
    def get_current_user(self):
32
        """
33
        Get current authenticated user.
34
        
35
        Returns:
36
            str or None: User identifier if authenticated, None otherwise
37
            
38
        Handles both Basic Auth and OAuth2 authentication methods.
39
        """
40
    
41
    def get_argument(self, name, default=None, strip=True, type=str):
42
        """
43
        Enhanced argument parsing with type conversion.
44
        
45
        Args:
46
            name (str): Argument name
47
            default: Default value if not present
48
            strip (bool): Strip whitespace from string values
49
            type: Type to convert to (str, int, float, bool)
50
            
51
        Returns:
52
            Parsed and converted argument value
53
        """
54
    
55
    def format_task(self, task):
56
        """
57
        Apply custom task formatting for display.
58
        
59
        Args:
60
            task (dict): Task object to format
61
            
62
        Returns:
63
            dict: Formatted task with display-friendly values
64
        """
65
    
66
    def get_active_queue_names(self):
67
        """
68
        Get list of active queue names across all workers.
69
        
70
        Returns:
71
            list: Queue names currently being consumed
72
        """
73
    
74
    @property
75
    def capp(self):
76
        """Access to Celery application instance."""
77
```
78

79
### Dashboard Views
80

81
#### Workers Dashboard
82

83
```python { .api }
84
# GET / and GET /workers
85
class WorkersView(BaseHandler):
86
    """
87
    Main workers dashboard showing cluster overview.
88
    
89
    Query Parameters:
90
        refresh (bool): Force worker information refresh
91
        json (bool): Return JSON response instead of HTML
92
        
93
    Displays worker status, active tasks, load information,
94
    and provides controls for worker management.
95
    """
96

97
# GET /worker/{name}
98
class WorkerView(BaseHandler):
99
    """
100
    Individual worker details page.
101
    
102
    Shows detailed information for a specific worker including:
103
    - Active and processed task counts
104
    - System load and resource usage
105
    - Registered tasks and active queues
106
    - Process pool information
107
    """
108
```
109

110
#### Tasks Dashboard
111

112
```python { .api }
113
# GET /tasks
114
class TasksView(BaseHandler):
115
    """
116
    Tasks dashboard with filtering and search capabilities.
117
    
118
    Provides interactive task management with:
119
    - Real-time task status updates
120
    - Advanced filtering by state, worker, time range
121
    - Search functionality across task content
122
    - Pagination for large task sets
123
    """
124

125
# GET /task/{task_id}
126
class TaskView(BaseHandler):
127
    """
128
    Individual task details page.
129
    
130
    Shows complete task information including:
131
    - Execution timeline and status
132
    - Arguments and result data
133
    - Error traceback if failed
134
    - Worker and routing information
135
    """
136

137
# GET /tasks/datatable
138
class TasksDataTable(BaseHandler):
139
    """
140
    DataTable-compatible task data endpoint.
141
    
142
    Query Parameters:
143
        draw (int): DataTable draw counter
144
        start (int): Starting record number
145
        length (int): Number of records to return
146
        search[value] (str): Search term
147
        order[0][column] (int): Sort column index
148
        order[0][dir] (str): Sort direction ('asc' or 'desc')
149
        
150
    Returns JSON data formatted for DataTables JavaScript library.
151
    """
152
```
153

154
#### Broker Dashboard
155

156
```python { .api }
157
# GET /broker
158
class BrokerView(BaseHandler):
159
    """
160
    Broker information and queue status page.
161
    
162
    Displays:
163
    - Queue lengths and message counts
164
    - Exchange information
165
    - Broker connection status
166
    - Queue consumer details
167
    """
168
```
169

170
### Authentication Views
171

172
```python { .api }
173
# GET /login
174
class LoginHandler:
175
    """
176
    Dynamic login handler factory.
177
    
178
    Creates appropriate login handler based on configured
179
    authentication provider (Google, GitHub, GitLab, Okta).
180
    """
181

182
class GoogleAuth2LoginHandler(BaseHandler):
183
    """Google OAuth2 authentication handler."""
184
    
185
    def get(self):
186
        """Handle OAuth2 authentication flow."""
187
    
188
    def _on_auth(self, user):
189
        """Process authentication result."""
190

191
class GithubLoginHandler(BaseHandler):
192
    """GitHub OAuth2 authentication handler."""
193

194
class GitLabLoginHandler(BaseHandler):
195
    """GitLab OAuth2 authentication handler."""
196

197
class OktaLoginHandler(BaseHandler):
198
    """Okta OAuth2 authentication handler."""
199
```
200

201
### Monitoring Views
202

203
```python { .api }
204
# GET /metrics
205
class Metrics(BaseHandler):
206
    """
207
    Prometheus metrics endpoint.
208
    
209
    Returns:
210
        text/plain: Prometheus metrics in text format
211
        
212
    Provides comprehensive metrics for:
213
    - Task execution statistics
214
    - Worker status and performance
215
    - Queue lengths and throughput
216
    - System resource usage
217
    """
218

219
# GET /healthcheck
220
class Healthcheck(BaseHandler):
221
    """
222
    Health check endpoint.
223
    
224
    Returns:
225
        text/plain: "OK" if service is healthy
226
        
227
    Used for load balancer health checks and monitoring.
228
    """
229
```
230

231
## Template Context
232

233
All web interface templates receive common context variables:
234

235
```python { .api }
236
template_context = {
237
    'current_user': str,          # Authenticated user identifier
238
    'capp': celery.Celery,        # Celery application instance
239
    'events': Events,             # Events monitoring instance
240
    'broker_url': str,            # Broker connection URL
241
    'flower_version': str,        # Flower version string
242
    'celery_version': str,        # Celery version string
243
    'options': OptionsNamespace,  # Configuration options
244
    'url_prefix': str,            # URL prefix for reverse proxy
245
    'static_url': callable,       # Static file URL generator
246
    'reverse_url': callable,      # URL reverse lookup
247
}
248
```
249

250
## Usage Examples
251

252
### Custom Template Context
253

254
```python
255
from flower.views import BaseHandler
256

257
class CustomView(BaseHandler):
258
    def get(self):
259
        # Add custom context
260
        context = {
261
            'custom_data': self.get_custom_data(),
262
            'page_title': 'Custom Dashboard'
263
        }
264
        self.render('custom_template.html', **context)
265
    
266
    def get_custom_data(self):
267
        # Custom data processing
268
        return {'key': 'value'}
269
```
270

271
### Authentication Integration
272

273
```python
274
class ProtectedView(BaseHandler):
275
    @tornado.web.authenticated
276
    def get(self):
277
        user = self.get_current_user()
278
        if not self.is_authorized(user):
279
            raise tornado.web.HTTPError(403)
280
        
281
        self.render('protected.html', user=user)
282
    
283
    def is_authorized(self, user):
284
        # Custom authorization logic
285
        return user.endswith('@company.com')
286
```
287

288
### Real-time Updates
289

290
The web interface supports real-time updates through:
291

292
- **Periodic Refresh**: Automatic page refresh at configurable intervals
293
- **AJAX Updates**: Background data updates without page reload
294
- **WebSocket Support**: Real-time task and worker status updates
295

296
## Static Assets
297

298
Flower includes comprehensive static assets for the web interface:
299

300
- **CSS**: Bootstrap-based responsive styling
301
- **JavaScript**: jQuery, DataTables, real-time updates
302
- **Images**: Icons and visual elements
303
- **Fonts**: Web fonts for consistent display
304

305
## Error Handling
306

307
```python { .api }
308
# Default 404 handler
309
class NotFoundErrorHandler(BaseHandler):
310
    """Handle 404 errors with custom error page."""
311
    
312
    def get(self):
313
        """Raise 404 error with custom template."""
314
    
315
    def post(self):
316
        """Handle POST requests to invalid URLs."""
317
```
318

319
## Responsive Design
320

321
The web interface is fully responsive and mobile-friendly:
322

323
- **Bootstrap Framework**: Responsive grid system
324
- **Mobile Navigation**: Collapsible navigation menu
325
- **Touch-Friendly**: Appropriate touch targets for mobile devices
326
- **Adaptive Tables**: Responsive table layouts for different screen sizes
327

328
## Customization
329

330
### Custom Templates
331

332
```python
333
# Override default templates
334
TEMPLATE_PATH = '/path/to/custom/templates'
335
flower_app = Flower(template_path=TEMPLATE_PATH)
336

337
# Custom template structure
338
templates/
339
├── base.html          # Base template
340
├── workers.html       # Workers dashboard
341
├── tasks.html         # Tasks dashboard
342
├── task.html          # Task details
343
├── broker.html        # Broker information
344
└── login.html         # Login page
345
```
346

347
### Custom Styling
348

349
```python
350
# Custom static files
351
STATIC_PATH = '/path/to/custom/static'
352
flower_app = Flower(static_path=STATIC_PATH)
353

354
# Custom CSS
355
static/
356
├── css/
357
│   └── custom.css     # Additional styles
358
├── js/
359
│   └── custom.js      # Additional JavaScript
360
└── images/
361
    └── logo.png       # Custom logo
362
```