ES_Sami7777/easystream-main
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Add comprehensive documentation suite and reorganize project structure

Browse Source 
- Created complete documentation in docs/ directory
- Added PROJECT_OVERVIEW.md with feature highlights and getting started guide
- Added ARCHITECTURE.md with system design and technical details
- Added SECURITY.md with comprehensive security implementation guide
- Added DEVELOPMENT.md with development workflows and best practices
- Added DEPLOYMENT.md with production deployment instructions
- Added API.md with complete REST API documentation
- Added CONTRIBUTING.md with contribution guidelines
- Added CHANGELOG.md with version history and migration notes
- Reorganized all documentation files into docs/ directory for better organization
- Updated README.md with proper documentation links and quick navigation
- Enhanced project structure with professional documentation standards
This commit is contained in:
SamiAhmed7777
2025-10-21 00:39:45 -07:00
commit 0b7e2d0a5b
6080 changed files with 1332936 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

699
docs/API.md Normal file
View File

@@ -0,0 +1,699 @@
# API Documentation
EasyStream provides a comprehensive REST API for integrating with external applications and building custom clients.
## Base URL
```
https://your-domain.com/api/
```
## Authentication
### API Key Authentication
Include your API key in the request headers:
```http
Authorization: Bearer YOUR_API_KEY
X-API-Key: YOUR_API_KEY
```
### Session Authentication
For web applications, use session-based authentication:
```http
Cookie: PHPSESSID=your_session_id
```
### Rate Limiting
- **Default**: 1000 requests per hour per API key
- **Authenticated users**: 5000 requests per hour
- **Premium users**: 10000 requests per hour
Rate limit headers are included in responses:
```http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
```
## Response Format
### Success Response
```json
{
"success": true,
"data": {
// Response data
},
"meta": {
"timestamp": "2024-01-01T12:00:00Z",
"version": "1.0"
}
}
```
### Error Response
```json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input parameters",
"details": {
"field": "email",
"issue": "Invalid email format"
}
},
"meta": {
"timestamp": "2024-01-01T12:00:00Z",
"version": "1.0"
}
}
```
## Authentication Endpoints
### POST /api/auth/login
Authenticate user and create session.
**Request:**
```json
{
"username": "user@example.com",
"password": "password123",
"remember": true
}
```
**Response:**
```json
{
"success": true,
"data": {
"user": {
"id": 123,
"username": "user@example.com",
"role": "user",
"permissions": ["video.upload", "video.view"]
},
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"expires_at": "2024-01-02T12:00:00Z"
}
}
```
### POST /api/auth/logout
Logout user and invalidate session.
**Response:**
```json
{
"success": true,
"data": {
"message": "Successfully logged out"
}
}
```
### GET /api/auth/me
Get current user information.
**Response:**
```json
{
"success": true,
"data": {
"user": {
"id": 123,
"username": "user@example.com",
"email": "user@example.com",
"role": "user",
"created_at": "2024-01-01T00:00:00Z",
"last_login": "2024-01-01T12:00:00Z"
}
}
}
```
## Video Management
### GET /api/videos
List videos with pagination and filtering.
**Parameters:**
- `page` (int): Page number (default: 1)
- `limit` (int): Items per page (default: 20, max: 100)
- `category` (string): Filter by category
- `user_id` (int): Filter by user
- `status` (string): Filter by status (published, processing, draft)
- `sort` (string): Sort by (created_at, views, likes, title)
- `order` (string): Sort order (asc, desc)
**Response:**
```json
{
"success": true,
"data": {
"videos": [
{
"id": 456,
"title": "Sample Video",
"description": "Video description",
"thumbnail": "https://example.com/thumb.jpg",
"duration": 120,
"views": 1000,
"likes": 50,
"status": "published",
"created_at": "2024-01-01T10:00:00Z",
"user": {
"id": 123,
"username": "creator"
}
}
],
"pagination": {
"current_page": 1,
"total_pages": 10,
"total_items": 200,
"items_per_page": 20
}
}
}
```
### GET /api/videos/{id}
Get specific video details.
**Response:**
```json
{
"success": true,
"data": {
"video": {
"id": 456,
"title": "Sample Video",
"description": "Detailed video description",
"thumbnail": "https://example.com/thumb.jpg",
"video_url": "https://example.com/video.mp4",
"hls_url": "https://example.com/hls/video/playlist.m3u8",
"duration": 120,
"views": 1000,
"likes": 50,
"dislikes": 5,
"status": "published",
"category": "entertainment",
"tags": ["funny", "viral"],
"created_at": "2024-01-01T10:00:00Z",
"updated_at": "2024-01-01T11:00:00Z",
"user": {
"id": 123,
"username": "creator",
"avatar": "https://example.com/avatar.jpg"
}
}
}
}
```
### POST /api/videos
Upload a new video.
**Request (multipart/form-data):**
```
title: "My Video Title"
description: "Video description"
category: "entertainment"
tags: "funny,viral"
privacy: "public"
file: [video file]
thumbnail: [image file] (optional)
```
**Response:**
```json
{
"success": true,
"data": {
"video": {
"id": 789,
"title": "My Video Title",
"status": "processing",
"upload_progress": 100,
"processing_progress": 0,
"created_at": "2024-01-01T12:00:00Z"
}
}
}
```
### PUT /api/videos/{id}
Update video information.
**Request:**
```json
{
"title": "Updated Title",
"description": "Updated description",
"category": "education",
"tags": ["tutorial", "howto"],
"privacy": "unlisted"
}
```
### DELETE /api/videos/{id}
Delete a video.
**Response:**
```json
{
"success": true,
"data": {
"message": "Video deleted successfully"
}
}
```
### GET /api/videos/{id}/progress
Get video processing progress.
**Response:**
```json
{
"success": true,
"data": {
"video_id": 789,
"status": "processing",
"progress": {
"upload": 100,
"processing": 45,
"thumbnail": 100,
"hls": 30
},
"estimated_completion": "2024-01-01T12:15:00Z"
}
}
```
## Live Streaming
### GET /api/streams
List live streams.
**Response:**
```json
{
"success": true,
"data": {
"streams": [
{
"id": 101,
"title": "Live Gaming Session",
"description": "Playing the latest game",
"thumbnail": "https://example.com/stream_thumb.jpg",
"status": "live",
"viewers": 150,
"started_at": "2024-01-01T12:00:00Z",
"stream_key": "abc123def456",
"rtmp_url": "rtmp://example.com/live/abc123def456",
"hls_url": "https://example.com/hls/live/abc123def456/index.m3u8",
"user": {
"id": 123,
"username": "streamer"
}
}
]
}
}
```
### POST /api/streams
Create a new live stream.
**Request:**
```json
{
"title": "My Live Stream",
"description": "Stream description",
"category": "gaming",
"privacy": "public"
}
```
**Response:**
```json
{
"success": true,
"data": {
"stream": {
"id": 102,
"title": "My Live Stream",
"stream_key": "xyz789abc123",
"rtmp_url": "rtmp://example.com/live/xyz789abc123",
"hls_url": "https://example.com/hls/live/xyz789abc123/index.m3u8",
"status": "created",
"created_at": "2024-01-01T12:00:00Z"
}
}
}
```
### PUT /api/streams/{id}/start
Start a live stream.
**Response:**
```json
{
"success": true,
"data": {
"stream": {
"id": 102,
"status": "live",
"started_at": "2024-01-01T12:00:00Z"
}
}
}
```
### PUT /api/streams/{id}/stop
Stop a live stream.
**Response:**
```json
{
"success": true,
"data": {
"stream": {
"id": 102,
"status": "ended",
"ended_at": "2024-01-01T13:00:00Z",
"duration": 3600
}
}
}
```
## User Management
### GET /api/users
List users (admin only).
**Parameters:**
- `page` (int): Page number
- `limit` (int): Items per page
- `role` (string): Filter by role
- `status` (string): Filter by status
### GET /api/users/{id}
Get user profile.
**Response:**
```json
{
"success": true,
"data": {
"user": {
"id": 123,
"username": "user123",
"email": "user@example.com",
"avatar": "https://example.com/avatar.jpg",
"bio": "User biography",
"subscriber_count": 1000,
"video_count": 50,
"created_at": "2024-01-01T00:00:00Z"
}
}
}
```
### PUT /api/users/{id}
Update user profile.
**Request:**
```json
{
"bio": "Updated biography",
"avatar": "base64_encoded_image_data"
}
```
## Comments and Interactions
### GET /api/videos/{id}/comments
Get video comments.
**Parameters:**
- `page` (int): Page number
- `limit` (int): Items per page
- `sort` (string): Sort by (created_at, likes)
**Response:**
```json
{
"success": true,
"data": {
"comments": [
{
"id": 789,
"content": "Great video!",
"likes": 10,
"replies_count": 2,
"created_at": "2024-01-01T12:00:00Z",
"user": {
"id": 456,
"username": "commenter",
"avatar": "https://example.com/avatar.jpg"
}
}
]
}
}
```
### POST /api/videos/{id}/comments
Add a comment to a video.
**Request:**
```json
{
"content": "This is a great video!",
"parent_id": null
}
```
### POST /api/videos/{id}/like
Like a video.
**Response:**
```json
{
"success": true,
"data": {
"liked": true,
"like_count": 51
}
}
```
### DELETE /api/videos/{id}/like
Unlike a video.
**Response:**
```json
{
"success": true,
"data": {
"liked": false,
"like_count": 50
}
}
```
## Search
### GET /api/search
Search for videos, users, or streams.
**Parameters:**
- `q` (string): Search query
- `type` (string): Search type (videos, users, streams, all)
- `page` (int): Page number
- `limit` (int): Items per page
**Response:**
```json
{
"success": true,
"data": {
"results": {
"videos": [...],
"users": [...],
"streams": [...]
},
"total_results": 150,
"search_time": 0.05
}
}
```
## Analytics
### GET /api/analytics/videos/{id}
Get video analytics (owner only).
**Response:**
```json
{
"success": true,
"data": {
"video_id": 456,
"views": {
"total": 10000,
"today": 100,
"this_week": 500,
"this_month": 2000
},
"engagement": {
"likes": 500,
"dislikes": 20,
"comments": 150,
"shares": 75
},
"demographics": {
"age_groups": {
"18-24": 30,
"25-34": 40,
"35-44": 20,
"45+": 10
},
"countries": {
"US": 50,
"UK": 20,
"CA": 15,
"AU": 10,
"other": 5
}
}
}
}
```
## Webhooks
### Configuration
Configure webhooks in your account settings to receive real-time notifications.
### Events
- `video.uploaded` - New video uploaded
- `video.processed` - Video processing completed
- `stream.started` - Live stream started
- `stream.ended` - Live stream ended
- `comment.created` - New comment added
- `user.subscribed` - New subscriber
### Payload Example
```json
{
"event": "video.uploaded",
"timestamp": "2024-01-01T12:00:00Z",
"data": {
"video": {
"id": 789,
"title": "New Video",
"user_id": 123
}
}
}
```
## Error Codes
### HTTP Status Codes
- `200` - Success
- `201` - Created
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `422` - Validation Error
- `429` - Rate Limit Exceeded
- `500` - Internal Server Error
### Application Error Codes
- `VALIDATION_ERROR` - Input validation failed
- `AUTHENTICATION_REQUIRED` - Authentication required
- `INSUFFICIENT_PERMISSIONS` - Insufficient permissions
- `RESOURCE_NOT_FOUND` - Resource not found
- `RATE_LIMIT_EXCEEDED` - Rate limit exceeded
- `UPLOAD_FAILED` - File upload failed
- `PROCESSING_ERROR` - Video processing error
## SDKs and Libraries
### JavaScript SDK
```javascript
import EasyStreamAPI from 'easystream-api';
const api = new EasyStreamAPI({
baseURL: 'https://your-domain.com/api',
apiKey: 'your-api-key'
});
// Upload video
const video = await api.videos.upload({
title: 'My Video',
file: videoFile
});
// Get video details
const videoDetails = await api.videos.get(video.id);
```
### PHP SDK
```php
<?php
use EasyStream\API\Client;
$client = new Client([
'base_url' => 'https://your-domain.com/api',
'api_key' => 'your-api-key'
]);
// List videos
$videos = $client->videos()->list([
'limit' => 10,
'category' => 'entertainment'
]);
// Create stream
$stream = $client->streams()->create([
'title' => 'My Live Stream',
'category' => 'gaming'
]);
```
## Testing
### API Testing
Use the provided test endpoints to verify your integration:
```bash
# Test authentication
curl -X POST https://your-domain.com/api/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"test@example.com","password":"password"}'
# Test video listing
curl -X GET https://your-domain.com/api/videos \
-H "Authorization: Bearer YOUR_TOKEN"
```
### Postman Collection
Import our Postman collection for easy API testing:
```
https://your-domain.com/api/postman-collection.json
```
## Support
For API support and questions:
- Documentation: https://docs.your-domain.com
- Support Email: api-support@your-domain.com
- GitHub Issues: https://github.com/your-org/easystream/issues

284
docs/ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,284 @@
# EasyStream Architecture
This document provides a comprehensive overview of EasyStream's architecture, design patterns, and system components.
## System Overview
EasyStream is a high-performance video streaming platform built with PHP, featuring:
- Multi-format media support (video, audio, images, documents)
- Live streaming with RTMP/HLS
- Containerized deployment with Docker
- Comprehensive security framework
- Background job processing
- Admin dashboard and user management
## Architecture Patterns
### MVC-Like Structure
- **Models**: `f_core/f_classes/` - Core business logic classes
- **Views**: `f_templates/` - Smarty template files
- **Controllers**: `f_modules/` - Feature modules handling requests
### Service Layer Pattern
Core services are implemented as singleton classes:
- `VDatabase` - Database abstraction layer
- `VSecurity` - Security and validation services
- `VLogger` - Centralized logging
- `VAuth` - Authentication and authorization
- `VRBAC` - Role-based access control
## Core Components
### 1. Application Bootstrap (`f_core/config.core.php`)
```php
// Initialization sequence:
1. Environment configuration
2. Database connection
3. Session management
4. Security initialization
5. Logging setup
6. Template engine configuration
```
### 2. Database Layer (`f_core/f_classes/class.database.php`)
- Built on ADOdb for database abstraction
- Prepared statement support
- Connection pooling
- Query validation and sanitization
- Transaction management
### 3. Security Framework (`f_core/f_classes/class.security.php`)
- Input validation and sanitization
- CSRF protection
- Rate limiting
- XSS prevention
- SQL injection protection
- File upload validation
### 4. Authentication System (`f_core/f_classes/class.auth.php`)
- Multi-factor authentication support
- Session management
- Password hashing (bcrypt/Argon2)
- Login attempt tracking
- Account lockout mechanisms
### 5. Authorization (RBAC) (`f_core/f_classes/class.rbac.php`)
- Role-based permissions
- Resource-level access control
- Dynamic permission checking
- Hierarchical role inheritance
## Data Flow Architecture
### Request Processing Flow
```
1. index.php (Entry Point)
↓
2. Router (URL parsing)
↓
3. Module Selection (f_modules/)
↓
4. Authentication Check
↓
5. Authorization Validation
↓
6. Business Logic Execution
↓
7. Template Rendering
↓
8. Response Output
```
### Background Job Processing
```
1. Job Creation (f_jobs/)
↓
2. Queue Management (class.queuemanager.php)
↓
3. Worker Processing (f_core/f_workers/)
↓
4. Job Execution
↓
5. Result Logging
```
## Live Streaming Architecture
### RTMP/HLS Pipeline
```
1. RTMP Input (SRS Server)
↓
2. Stream Processing
↓
3. HLS Segmentation
↓
4. CDN Distribution (Caddy)
↓
5. Client Playback
```
### Components
- **SRS (Simple Realtime Server)**: RTMP ingestion and HLS output
- **Caddy**: HTTP/2 web server with automatic HTTPS
- **FFmpeg**: Video processing and transcoding
- **HLS.js**: Client-side video player
## Database Schema
### Core Tables
- `users` - User accounts and profiles
- `videos` - Video metadata and processing status
- `streams` - Live stream configurations
- `categories` - Content categorization
- `comments` - User interactions
- `notifications` - System notifications
### Security Tables
- `user_sessions` - Active user sessions
- `login_attempts` - Failed login tracking
- `ip_bans` - IP-based access control
- `fingerprints` - Browser fingerprinting data
### System Tables
- `configurations` - Application settings
- `logs` - System and security logs
- `jobs` - Background job queue
- `permissions` - RBAC permissions
## Security Architecture
### Defense in Depth
1. **Input Layer**: Validation and sanitization
2. **Application Layer**: CSRF, rate limiting, authentication
3. **Database Layer**: Prepared statements, access control
4. **Network Layer**: HTTPS, firewall rules
5. **Infrastructure Layer**: Container isolation, secrets management
### Security Components
- **IP Tracking**: Monitor and block suspicious IPs
- **Fingerprinting**: Browser-based user identification
- **Rate Limiting**: Prevent abuse and DoS attacks
- **Audit Logging**: Comprehensive security event logging
## Caching Strategy
### Multi-Level Caching
1. **Application Cache**: In-memory object caching
2. **Database Cache**: Query result caching (ADOdb)
3. **Template Cache**: Compiled template caching (Smarty)
4. **Static Asset Cache**: CDN and browser caching
### Cache Invalidation
- Time-based expiration
- Event-driven invalidation
- Manual cache clearing via admin panel
## Monitoring and Observability
### Logging Framework
- **Structured Logging**: JSON-formatted log entries
- **Log Levels**: Emergency, Alert, Critical, Error, Warning, Notice, Info, Debug
- **Context Enrichment**: Request ID, user ID, IP address
- **Log Rotation**: Automatic cleanup and archival
### Metrics Collection
- Application performance metrics
- Security event tracking
- User behavior analytics
- System resource monitoring
## Scalability Considerations
### Horizontal Scaling
- Stateless application design
- Database connection pooling
- Session storage externalization
- Load balancer compatibility
### Performance Optimization
- Database query optimization
- Template compilation caching
- Static asset optimization
- CDN integration for media delivery
## Development Patterns
### Class Organization
```
f_core/f_classes/
├── class.auth.php # Authentication
├── class.database.php # Database abstraction
├── class.security.php # Security utilities
├── class.logger.php # Logging framework
├── class.rbac.php # Role-based access
└── ...
```
### Configuration Management
- Environment-based configuration
- Database-stored settings
- Runtime configuration caching
- Secure credential handling
### Error Handling
- Global exception handling
- User-friendly error pages
- Detailed error logging
- Debug mode for development
## API Architecture
### RESTful Design
- Resource-based URLs
- HTTP method semantics
- Proper status codes
- JSON response format
### Authentication
- Token-based authentication
- API key management
- Rate limiting per client
- Scope-based permissions
## Deployment Architecture
### Container Strategy
- Multi-container deployment (Docker Compose)
- Service isolation
- Volume management for persistent data
- Health checks and restart policies
### Services
- **PHP-FPM**: Application server
- **Caddy**: Web server and reverse proxy
- **MariaDB**: Database server
- **SRS**: Streaming server
- **Cron**: Scheduled task runner
## Future Considerations
### Microservices Migration
- Service decomposition strategy
- API gateway implementation
- Inter-service communication
- Data consistency patterns
### Cloud Native Features
- Kubernetes deployment
- Auto-scaling capabilities
- Service mesh integration
- Observability stack (Prometheus, Grafana)
## Performance Benchmarks
### Target Metrics
- Page load time: < 2 seconds
- API response time: < 500ms
- Concurrent users: 10,000+
- Video processing: Real-time for live streams
### Optimization Techniques
- Database indexing strategy
- Query optimization
- Caching layer implementation
- CDN utilization for static assets

402
docs/CHANGELOG.md Normal file
View File

@@ -0,0 +1,402 @@
# Changelog
All notable changes to EasyStream will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- Comprehensive documentation suite
- Project architecture documentation
- Security implementation guide
- API documentation with examples
- Development workflow documentation
- Deployment guides for various environments
### Changed
- Improved README structure with documentation links
- Enhanced project organization
## [2.0.0] - 2024-01-20
### Added
- **Live Streaming Infrastructure**
- Complete RTMP/HLS streaming system with SRS integration
- Real-time stream monitoring and analytics
- Adaptive bitrate streaming support
- Stream recording and DVR functionality
- Live chat and interaction features
- **Enhanced Admin Dashboard**
- Comprehensive user management system
- Content moderation tools
- System analytics and reporting
- Security monitoring dashboard
- Configuration management interface
- **Advanced Content Management**
- Metadata management for all media types
- Category and tag system
- Content scheduling and automation
- Bulk operations for content management
- Advanced search and filtering
- **Background Job System**
- Asynchronous video processing
- Queue management with priorities
- Job monitoring and retry logic
- Scalable worker architecture
- Database and Redis queue backends
- **API Enhancements**
- Video progress tracking endpoints
- Enhanced social interaction APIs
- Comprehensive error handling
- Rate limiting and authentication
- Webhook support for real-time notifications
### Enhanced
- **Security Framework**
- Advanced authentication system with MFA
- Role-based access control (RBAC)
- IP tracking and geolocation
- Browser fingerprinting
- Enhanced rate limiting
- Comprehensive audit logging
- **Performance Optimizations**
- Database query optimization
- Caching layer improvements
- Template compilation optimization
- Asset optimization and compression
- CDN integration support
### Fixed
- Database connection stability issues
- Memory leaks in video processing
- Session management improvements
- File upload security vulnerabilities
- Template rendering performance
## [1.5.0] - 2023-12-15
### Added
- **Authentication System Overhaul**
- Multi-factor authentication (TOTP, SMS, Email)
- Advanced password policies
- Account lockout mechanisms
- Session management improvements
- OAuth integration support
- **Security Enhancements**
- Comprehensive input validation framework
- CSRF protection for all forms
- XSS prevention mechanisms
- SQL injection protection
- File upload security scanning
- **Testing Framework**
- PHPUnit integration
- Unit tests for core functionality
- Integration tests for API endpoints
- Security testing suite
- Performance testing tools
- Automated CI/CD pipeline
### Changed
- Migrated to PHP 8.2 with strict typing
- Updated database schema for better performance
- Improved error handling and logging
- Enhanced template system with caching
### Fixed
- Critical security vulnerabilities
- Database performance issues
- Memory usage optimization
- File permission problems
## [1.4.0] - 2023-11-01
### Added
- **Docker Integration**
- Complete Docker Compose setup
- Multi-container architecture
- Development and production configurations
- Automated deployment scripts
- Health checks and monitoring
- **Live Streaming Foundation**
- SRS (Simple Realtime Server) integration
- RTMP ingestion support
- HLS delivery system
- Stream management interface
- Basic streaming analytics
- **API Framework**
- RESTful API structure
- JSON response formatting
- Authentication middleware
- Rate limiting implementation
- Error handling standardization
### Enhanced
- Video processing pipeline
- User interface responsiveness
- Database performance
- Logging and monitoring
## [1.3.0] - 2023-09-15
### Added
- **Progressive Web App (PWA)**
- Service worker implementation
- Offline functionality
- App installation prompts
- Push notification support
- Responsive design improvements
- **Social Features**
- User subscriptions and followers
- Comment system with threading
- Like and dislike functionality
- User notifications
- Activity feeds
- **Content Organization**
- Playlist creation and management
- Video categorization
- Tag system implementation
- Search functionality
- Content recommendations
### Changed
- Improved video player interface
- Enhanced mobile experience
- Optimized database queries
- Updated security protocols
## [1.2.0] - 2023-08-01
### Added
- **Admin Panel**
- User management interface
- Content moderation tools
- System configuration panel
- Analytics dashboard
- Log viewer and management
- **Video Processing**
- Automatic thumbnail generation
- Multiple quality transcoding
- Progress tracking
- Batch processing support
- Error handling and retry logic
- **User Profiles**
- Customizable user profiles
- Avatar upload and management
- User statistics
- Privacy settings
- Account management
### Enhanced
- Upload interface and experience
- Video player functionality
- Search capabilities
- Performance optimizations
## [1.1.0] - 2023-06-15
### Added
- **Core Video Platform**
- Video upload and storage
- Basic video player
- User registration and login
- Video listing and browsing
- Basic search functionality
- **Security Foundation**
- Input sanitization
- Basic authentication
- Session management
- CSRF protection
- SQL injection prevention
- **Template System**
- Smarty template integration
- Responsive design foundation
- Theme system
- Multi-language support preparation
### Changed
- Database schema optimization
- Improved file handling
- Enhanced error reporting
## [1.0.0] - 2023-05-01
### Added
- **Initial Release**
- Basic PHP framework structure
- Database abstraction layer
- Configuration system
- Logging framework
- Basic routing system
- **Core Infrastructure**
- ADOdb database integration
- Smarty template engine
- Basic security framework
- File upload handling
- Session management
- **Foundation Features**
- User authentication
- Basic video upload
- Simple video listing
- Admin interface foundation
- Configuration management
### Technical Debt
- Legacy code cleanup needed
- Performance optimization required
- Security audit pending
- Documentation incomplete
---
## Migration Notes
### Upgrading to 2.0.0
1. **Database Migration Required**
- Run `__install/updatedb_*.sql` scripts
- Update configuration files
- Clear application cache
2. **New Dependencies**
- Docker and Docker Compose
- SRS for live streaming
- Redis for caching (optional but recommended)
3. **Configuration Changes**
- Update environment variables
- Configure live streaming settings
- Set up background job processing
4. **Security Updates**
- Review and update security settings
- Enable new authentication features
- Configure rate limiting
### Upgrading to 1.5.0
1. **PHP Version Update**
- Upgrade to PHP 8.2+
- Update PHP extensions
- Test compatibility
2. **Security Enhancements**
- Enable MFA for admin accounts
- Review user permissions
- Update password policies
3. **Testing Integration**
- Set up testing environment
- Run test suite
- Configure CI/CD pipeline
## Breaking Changes
### Version 2.0.0
- **API Changes**: Some API endpoints have been restructured
- **Database Schema**: New tables and columns added
- **Configuration**: New environment variables required
- **Dependencies**: Docker now recommended for deployment
### Version 1.5.0
- **PHP Version**: Minimum PHP 8.2 required
- **Authentication**: New authentication system may require user re-login
- **Templates**: Some template variables changed
### Version 1.4.0
- **Docker**: New deployment method introduced
- **API**: RESTful API structure implemented
- **Configuration**: Docker-specific configuration added
## Security Updates
### Version 2.0.0
- Enhanced RBAC system
- Advanced threat detection
- Improved audit logging
- Browser fingerprinting
- IP geolocation tracking
### Version 1.5.0
- Multi-factor authentication
- Advanced password policies
- Session security improvements
- File upload security scanning
- Comprehensive input validation
### Version 1.4.0
- API authentication and authorization
- Rate limiting implementation
- Enhanced error handling
- Security header improvements
## Performance Improvements
### Version 2.0.0
- Database query optimization
- Advanced caching strategies
- Background job processing
- CDN integration support
- Template compilation optimization
### Version 1.5.0
- PHP 8.2 performance benefits
- Database indexing improvements
- Memory usage optimization
- Template caching enhancements
### Version 1.4.0
- Docker containerization benefits
- Improved resource utilization
- Better scaling capabilities
- Enhanced monitoring
## Known Issues
### Current Issues
- Large file uploads may timeout on some configurations
- Live streaming requires specific network configuration
- Some mobile browsers may have compatibility issues
### Resolved Issues
- ✅ Database connection pooling (v2.0.0)
- ✅ Memory leaks in video processing (v2.0.0)
- ✅ Session management vulnerabilities (v1.5.0)
- ✅ File upload security issues (v1.5.0)
- ✅ Template rendering performance (v1.4.0)
## Acknowledgments
### Contributors
- Core development team
- Security audit team
- Community contributors
- Beta testers and early adopters
### Third-party Libraries
- ADOdb for database abstraction
- Smarty for templating
- SRS for live streaming
- Docker for containerization
- Various PHP libraries and extensions
---
For detailed upgrade instructions, see the [Deployment Guide](DEPLOYMENT.md).
For development changes, see the [Development Guide](DEVELOPMENT.md).

145
docs/CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,145 @@
# Contributing to EasyStream
Thank you for your interest in contributing to EasyStream! This document provides guidelines and information for contributors.
## Development Setup
### Prerequisites
- Docker and Docker Compose
- PHP 8.2+ (for local development)
- Node.js (for frontend assets)
- Git
### Quick Start
1. Clone the repository
2. Copy `.env.example` to `.env` and configure
3. Run `docker-compose up -d --build`
4. Access the application at `http://localhost:8083`
## Project Structure
### Core Directories
- `f_core/` - Framework core (classes, functions, configs)
- `f_modules/` - Feature modules (frontend/backend)
- `f_templates/` - Smarty templates
- `f_data/` - Runtime data (logs, cache, uploads)
- `f_jobs/` - Background job classes
- `api/` - API endpoints
- `tests/` - Test suites
### Key Files
- `index.php` - Main application entry point
- `docker-compose.yml` - Container orchestration
- `Caddyfile` - Web server configuration
- `deploy/srs.conf` - Live streaming server config
## Development Guidelines
### Code Standards
- Follow PSR-12 coding standards for PHP
- Use meaningful variable and function names
- Add PHPDoc comments for all classes and methods
- Validate all user inputs using `VSecurity` class
- Use prepared statements for database queries
### Security Best Practices
- Always use `VSecurity::getParam()` and `VSecurity::postParam()` for input
- Implement CSRF protection with `csrf_field()` and `validate_csrf()`
- Escape output with `secure_output()` and `secure_js()`
- Use rate limiting for sensitive operations
- Log security events with `VLogger`
### Database Guidelines
- Use `VDatabase` class for all database operations
- Validate table and field names
- Use parameter binding for queries
- Follow the existing schema patterns
### Testing
- Write unit tests for new functionality
- Use PHPUnit for testing
- Run tests with `./run-tests.sh`
- Ensure all tests pass before submitting PRs
## Feature Development
### Adding New Features
1. Create a spec in `.kiro/specs/feature-name/`
2. Write requirements, design, and tasks
3. Implement following the task list
4. Add appropriate tests
5. Update documentation
### Live Streaming Features
- Use SRS for RTMP/HLS streaming
- HLS files are served from `/hls/` endpoint
- DVR recordings stored in `/srs/rec/`
- Test streaming with OBS or similar tools
### API Development
- Follow RESTful principles
- Use proper HTTP status codes
- Implement rate limiting
- Add comprehensive error handling
- Document all endpoints
## Deployment
### Production Checklist
- Review `DEPLOYMENT-CHECKLIST.md`
- Configure environment variables
- Set up SSL certificates
- Configure backup procedures
- Monitor logs and performance
### Docker Deployment
- Use provided `docker-compose.yml`
- Configure volumes for persistent data
- Set up reverse proxy (Caddy included)
- Configure SRS for live streaming
## Troubleshooting
### Common Issues
- Check `f_data/logs/` for error logs
- Verify database connectivity
- Ensure proper file permissions
- Check Docker container logs
### Debug Mode
- Enable debug mode in configuration
- Use `VLogger` for detailed logging
- Check admin log viewer for issues
## Getting Help
### Documentation
- Read the main `README.md`
- Check `docs/API.md` for API details
- Review deployment guides in `docs/`
### Support
- Create GitHub issues for bugs
- Use discussions for questions
- Follow the issue templates
## Code Review Process
### Pull Request Guidelines
1. Create feature branch from `main`
2. Make focused, atomic commits
3. Write clear commit messages
4. Add tests for new functionality
5. Update documentation as needed
6. Ensure CI passes
### Review Criteria
- Code follows project standards
- Security best practices implemented
- Tests cover new functionality
- Documentation is updated
- No breaking changes without discussion
## License
By contributing to EasyStream, you agree that your contributions will be licensed under the same license as the project.

701
docs/DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,701 @@
# Deployment Guide
This guide covers various deployment scenarios for EasyStream, from development to production environments.
## Quick Start (Docker)
### Prerequisites
- Docker 20.10+
- Docker Compose 2.0+
- 4GB+ RAM
- 20GB+ storage
### Basic Deployment
```bash
# Clone repository
git clone <repository-url>
cd easystream
# Configure environment
cp .env.example .env
# Edit .env with your settings
# Start services
docker-compose up -d --build
# Verify deployment
curl http://localhost:8083
```
## Production Deployment
### System Requirements
#### Minimum Requirements
- **CPU**: 2 cores
- **RAM**: 4GB
- **Storage**: 50GB SSD
- **Network**: 100Mbps
#### Recommended Requirements
- **CPU**: 4+ cores
- **RAM**: 8GB+
- **Storage**: 200GB+ SSD
- **Network**: 1Gbps
### Environment Configuration
#### Environment Variables
```bash
# Application
MAIN_URL=https://your-domain.com
DEBUG_MODE=false
ENVIRONMENT=production
# Database
DB_HOST=db
DB_NAME=easystream
DB_USER=easystream
DB_PASS=secure_password_here
# Security
SESSION_SECURE=true
CSRF_PROTECTION=enabled
RATE_LIMITING=enabled
# Storage
UPLOAD_MAX_SIZE=2G
STORAGE_DRIVER=local
# For S3: STORAGE_DRIVER=s3
# AWS_ACCESS_KEY_ID=your_key
# AWS_SECRET_ACCESS_KEY=your_secret
# AWS_DEFAULT_REGION=us-east-1
# AWS_BUCKET=your-bucket
# Email
MAIL_DRIVER=smtp
MAIL_HOST=smtp.your-provider.com
MAIL_PORT=587
MAIL_USERNAME=your_email@domain.com
MAIL_PASSWORD=your_password
MAIL_ENCRYPTION=tls
# Live Streaming
SRS_RTMP_PORT=1935
SRS_HTTP_PORT=8080
HLS_SEGMENT_DURATION=10
HLS_WINDOW_SIZE=60
# Monitoring
LOG_LEVEL=warning
LOG_DRIVER=file
# For centralized logging: LOG_DRIVER=syslog
```
### Docker Production Setup
#### Production Docker Compose
```yaml
# docker-compose.prod.yml
version: '3.8'
services:
php:
build:
context: .
dockerfile: Dockerfile.php
target: production
environment:
- ENVIRONMENT=production
- DEBUG_MODE=false
volumes:
- ./f_data:/var/www/html/f_data
- uploads:/var/www/html/f_data/uploads
- hls:/var/www/html/hls
restart: unless-stopped
depends_on:
- db
- redis
caddy:
image: caddy:2-alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./Caddyfile.prod:/etc/caddy/Caddyfile
- caddy_data:/data
- caddy_config:/config
- hls:/srv/hls:ro
restart: unless-stopped
depends_on:
- php
db:
image: mariadb:10.11
environment:
MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASS}
MYSQL_DATABASE: ${DB_NAME}
MYSQL_USER: ${DB_USER}
MYSQL_PASSWORD: ${DB_PASS}
volumes:
- db_data:/var/lib/mysql
- ./deploy/mysql.cnf:/etc/mysql/conf.d/custom.cnf
restart: unless-stopped
command: --innodb-buffer-pool-size=1G
redis:
image: redis:7-alpine
volumes:
- redis_data:/data
restart: unless-stopped
command: redis-server --appendonly yes
srs:
image: ossrs/srs:5
ports:
- "1935:1935"
- "8080:8080"
volumes:
- ./deploy/srs.prod.conf:/usr/local/srs/conf/srs.conf
- hls:/usr/local/srs/objs/nginx/html/hls
- recordings:/usr/local/srs/objs/nginx/html/rec
restart: unless-stopped
cron:
build:
context: .
dockerfile: Dockerfile.cron
volumes:
- ./f_data:/var/www/html/f_data
- uploads:/var/www/html/f_data/uploads
restart: unless-stopped
depends_on:
- db
- redis
volumes:
db_data:
redis_data:
caddy_data:
caddy_config:
uploads:
hls:
recordings:
```
#### Production Caddyfile
```caddyfile
# Caddyfile.prod
{
email your-email@domain.com
admin off
}
your-domain.com {
# Security headers
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
X-Content-Type-Options "nosniff"
X-Frame-Options "DENY"
X-XSS-Protection "1; mode=block"
Referrer-Policy "strict-origin-when-cross-origin"
Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; media-src 'self' blob:; connect-src 'self' wss:"
}
# Rate limiting
rate_limit {
zone static {
key {remote_host}
events 100
window 1m
}
zone api {
key {remote_host}
events 1000
window 1h
}
}
# HLS streaming
handle /hls/* {
root * /srv
file_server {
precompressed gzip br
}
header Cache-Control "public, max-age=10"
}
# Static assets
handle /f_scripts/* /f_templates/* {
root * /var/www/html
file_server {
precompressed gzip br
}
header Cache-Control "public, max-age=31536000"
}
# API endpoints
handle /api/* {
rate_limit api
reverse_proxy php:9000 {
transport fastcgi {
split .php
}
}
}
# Main application
handle {
root * /var/www/html
php_fastcgi php:9000
file_server
}
# Logging
log {
output file /var/log/caddy/access.log {
roll_size 100mb
roll_keep 5
}
format json
}
}
```
### Manual Installation
#### Server Setup (Ubuntu 22.04)
```bash
# Update system
sudo apt update && sudo apt upgrade -y
# Install PHP 8.2
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update
sudo apt install -y php8.2 php8.2-fpm php8.2-mysql php8.2-gd php8.2-curl \
php8.2-mbstring php8.2-xml php8.2-zip php8.2-bcmath php8.2-intl
# Install MariaDB
sudo apt install -y mariadb-server
sudo mysql_secure_installation
# Install Nginx
sudo apt install -y nginx
# Install FFmpeg
sudo apt install -y ffmpeg
# Install SRS
wget https://github.com/ossrs/srs/releases/download/v5.0.156/srs-server-5.0.156-ubuntu20-amd64.deb
sudo dpkg -i srs-server-5.0.156-ubuntu20-amd64.deb
```
#### Database Setup
```sql
-- Create database and user
CREATE DATABASE easystream CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'easystream'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON easystream.* TO 'easystream'@'localhost';
FLUSH PRIVILEGES;
-- Import schema
mysql -u easystream -p easystream < __install/easystream.sql
```
#### Nginx Configuration
```nginx
# /etc/nginx/sites-available/easystream
server {
listen 80;
server_name your-domain.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name your-domain.com;
root /var/www/easystream;
index index.php index.html;
# SSL Configuration
ssl_certificate /path/to/certificate.crt;
ssl_certificate_key /path/to/private.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512;
ssl_prefer_server_ciphers off;
# Security headers
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "DENY" always;
add_header X-XSS-Protection "1; mode=block" always;
# Rate limiting
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
limit_req_zone $binary_remote_addr zone=general:10m rate=1r/s;
# HLS streaming
location /hls/ {
alias /var/srs/hls/;
add_header Cache-Control "no-cache, no-store, must-revalidate";
add_header Access-Control-Allow-Origin "*";
add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";
add_header Access-Control-Allow-Headers "DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range";
}
# API endpoints
location /api/ {
limit_req zone=api burst=20 nodelay;
try_files $uri $uri/ /index.php?$query_string;
}
# PHP processing
location ~ \.php$ {
fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
# Static files
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
# Security
location ~ /\. {
deny all;
}
location ~ /(f_data|__install|tests)/ {
deny all;
}
}
```
#### PHP-FPM Configuration
```ini
; /etc/php/8.2/fpm/pool.d/easystream.conf
[easystream]
user = www-data
group = www-data
listen = /var/run/php/php8.2-fpm-easystream.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660
pm = dynamic
pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 35
pm.max_requests = 1000
; PHP settings
php_admin_value[upload_max_filesize] = 2G
php_admin_value[post_max_size] = 2G
php_admin_value[max_execution_time] = 300
php_admin_value[memory_limit] = 512M
```
### Cloud Deployment
#### AWS Deployment
```bash
# Using AWS ECS with Fargate
aws ecs create-cluster --cluster-name easystream-prod
# Create task definition
aws ecs register-task-definition --cli-input-json file://ecs-task-definition.json
# Create service
aws ecs create-service \
--cluster easystream-prod \
--service-name easystream-web \
--task-definition easystream:1 \
--desired-count 2 \
--launch-type FARGATE \
--network-configuration "awsvpcConfiguration={subnets=[subnet-12345],securityGroups=[sg-12345],assignPublicIp=ENABLED}"
```
#### Google Cloud Platform
```bash
# Deploy to Cloud Run
gcloud run deploy easystream \
--image gcr.io/PROJECT_ID/easystream \
--platform managed \
--region us-central1 \
--allow-unauthenticated \
--memory 2Gi \
--cpu 2 \
--max-instances 10
```
#### DigitalOcean App Platform
```yaml
# .do/app.yaml
name: easystream
services:
- name: web
source_dir: /
github:
repo: your-username/easystream
branch: main
run_command: php-fpm
environment_slug: php
instance_count: 2
instance_size_slug: professional-xs
envs:
- key: ENVIRONMENT
value: production
- key: DB_HOST
value: ${db.HOSTNAME}
- key: DB_NAME
value: ${db.DATABASE}
- key: DB_USER
value: ${db.USERNAME}
- key: DB_PASS
value: ${db.PASSWORD}
databases:
- name: db
engine: MYSQL
version: "8"
size: db-s-1vcpu-1gb
```
### SSL/TLS Configuration
#### Let's Encrypt with Certbot
```bash
# Install Certbot
sudo apt install -y certbot python3-certbot-nginx
# Obtain certificate
sudo certbot --nginx -d your-domain.com
# Auto-renewal
sudo crontab -e
# Add: 0 12 * * * /usr/bin/certbot renew --quiet
```
#### Cloudflare SSL
```bash
# Configure Cloudflare origin certificates
# Download origin certificate and key
# Update Nginx/Caddy configuration with certificate paths
```
### Monitoring and Logging
#### System Monitoring
```bash
# Install monitoring tools
sudo apt install -y htop iotop nethogs
# Install Prometheus Node Exporter
wget https://github.com/prometheus/node_exporter/releases/download/v1.6.1/node_exporter-1.6.1.linux-amd64.tar.gz
tar xvfz node_exporter-1.6.1.linux-amd64.tar.gz
sudo cp node_exporter-1.6.1.linux-amd64/node_exporter /usr/local/bin/
sudo useradd --no-create-home --shell /bin/false node_exporter
sudo chown node_exporter:node_exporter /usr/local/bin/node_exporter
```
#### Log Management
```bash
# Configure log rotation
sudo tee /etc/logrotate.d/easystream << EOF
/var/www/easystream/f_data/logs/*.log {
daily
missingok
rotate 30
compress
delaycompress
notifempty
create 644 www-data www-data
}
EOF
```
### Backup Strategy
#### Database Backup
```bash
#!/bin/bash
# backup-db.sh
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backups/database"
mkdir -p $BACKUP_DIR
mysqldump -u easystream -p easystream | gzip > $BACKUP_DIR/easystream_$DATE.sql.gz
# Keep only last 30 days
find $BACKUP_DIR -name "*.sql.gz" -mtime +30 -delete
```
#### File Backup
```bash
#!/bin/bash
# backup-files.sh
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backups/files"
SOURCE_DIR="/var/www/easystream/f_data"
mkdir -p $BACKUP_DIR
tar -czf $BACKUP_DIR/files_$DATE.tar.gz -C $SOURCE_DIR .
# Keep only last 7 days
find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete
```
### Performance Optimization
#### Database Optimization
```sql
-- MySQL/MariaDB configuration
[mysqld]
innodb_buffer_pool_size = 2G
innodb_log_file_size = 256M
innodb_flush_log_at_trx_commit = 2
query_cache_size = 128M
query_cache_type = 1
max_connections = 200
```
#### PHP Optimization
```ini
; php.ini optimizations
opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=10000
opcache.revalidate_freq=2
opcache.fast_shutdown=1
realpath_cache_size=4096K
realpath_cache_ttl=600
```
#### CDN Configuration
```bash
# Configure CloudFlare or AWS CloudFront
# Cache static assets: images, videos, CSS, JS
# Set appropriate cache headers
# Enable compression (gzip/brotli)
```
### Security Hardening
#### Firewall Configuration
```bash
# UFW firewall rules
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 1935/tcp # RTMP
sudo ufw enable
```
#### Fail2Ban Setup
```bash
# Install Fail2Ban
sudo apt install -y fail2ban
# Configure jail
sudo tee /etc/fail2ban/jail.local << EOF
[DEFAULT]
bantime = 3600
findtime = 600
maxretry = 5
[nginx-http-auth]
enabled = true
filter = nginx-http-auth
logpath = /var/log/nginx/error.log
[nginx-limit-req]
enabled = true
filter = nginx-limit-req
logpath = /var/log/nginx/error.log
maxretry = 10
EOF
sudo systemctl restart fail2ban
```
### Troubleshooting
#### Common Issues
1. **502 Bad Gateway**: Check PHP-FPM status and configuration
2. **Database Connection**: Verify credentials and network connectivity
3. **File Permissions**: Ensure www-data has proper permissions
4. **Memory Issues**: Increase PHP memory limit and server RAM
5. **Streaming Issues**: Check SRS configuration and network ports
#### Debug Commands
```bash
# Check service status
sudo systemctl status nginx php8.2-fpm mariadb
# View logs
sudo tail -f /var/log/nginx/error.log
sudo tail -f /var/www/easystream/f_data/logs/error_$(date +%Y-%m-%d).log
# Test database connection
mysql -u easystream -p -h localhost easystream
# Check disk space
df -h
# Monitor processes
htop
```
### Maintenance
#### Regular Maintenance Tasks
```bash
#!/bin/bash
# maintenance.sh - Run weekly
# Update system packages
sudo apt update && sudo apt upgrade -y
# Clean up old logs
find /var/www/easystream/f_data/logs -name "*.log" -mtime +30 -delete
# Optimize database
mysql -u easystream -p -e "OPTIMIZE TABLE easystream.videos, easystream.users, easystream.comments;"
# Clear application cache
rm -rf /var/www/easystream/f_data/cache/*
# Restart services
sudo systemctl restart php8.2-fpm nginx
```
#### Health Checks
```bash
#!/bin/bash
# health-check.sh - Run every 5 minutes
# Check web server
if ! curl -f http://localhost > /dev/null 2>&1; then
echo "Web server down" | mail -s "EasyStream Alert" admin@domain.com
fi
# Check database
if ! mysql -u easystream -p -e "SELECT 1" > /dev/null 2>&1; then
echo "Database down" | mail -s "EasyStream Alert" admin@domain.com
fi
# Check disk space
DISK_USAGE=$(df / | tail -1 | awk '{print $5}' | sed 's/%//')
if [ $DISK_USAGE -gt 90 ]; then
echo "Disk usage: ${DISK_USAGE}%" | mail -s "EasyStream Alert" admin@domain.com
fi
```

579
docs/DEVELOPMENT.md Normal file
View File

@@ -0,0 +1,579 @@
# Development Guide
This guide covers development workflows, coding standards, and best practices for EasyStream development.
## Development Environment Setup
### Local Development with Docker
```bash
# Clone the repository
git clone <repository-url>
cd easystream
# Copy environment configuration
cp .env.example .env
# Start development environment
docker-compose up -d --build
# Access the application
open http://localhost:8083
```
### Native PHP Development
```bash
# Install PHP 8.2+ with required extensions
# - pdo_mysql
# - gd
# - curl
# - mbstring
# - xml
# - zip
# Install Composer dependencies (if any)
composer install
# Configure database connection
cp f_core/config.database.php.example f_core/config.database.php
# Edit database settings
# Set up web server (Apache/Nginx)
# Point document root to project directory
```
## Project Structure Deep Dive
### Core Framework (`f_core/`)
```
f_core/
├── config.*.php # Configuration files
├── f_classes/ # Core business logic classes
├── f_functions/ # Utility functions
└── f_workers/ # Background workers
```
### Modules (`f_modules/`)
```
f_modules/
├── m_frontend/ # User-facing modules
├── m_backend/ # Admin modules
└── api/ # API endpoints
```
### Templates (`f_templates/`)
```
f_templates/
├── tpl_frontend/ # User interface templates
├── tpl_backend/ # Admin interface templates
└── frontend/ # Static frontend assets
```
### Jobs (`f_jobs/`)
```
f_jobs/
├── BaseJob.php # Base job class
├── VideoProcessingJob.php
├── NotificationJob.php
└── CleanupJob.php
```
## Coding Standards
### PHP Standards
Follow PSR-12 coding standards with EasyStream-specific conventions:
```php
<?php
/**
* Class description
*
* @author Your Name
* @version 1.0
*/
class VExampleClass
{
/**
* Method description
*
* @param string $param Parameter description
* @return bool Return value description
*/
public function exampleMethod(string $param): bool
{
// Implementation
return true;
}
}
```
### Naming Conventions
- Classes: PascalCase with 'V' prefix for core classes (`VDatabase`, `VSecurity`)
- Methods: camelCase (`getUserById`, `validateInput`)
- Variables: camelCase (`$userId`, `$videoData`)
- Constants: UPPER_SNAKE_CASE (`MAX_FILE_SIZE`, `DEFAULT_TIMEOUT`)
- Files: lowercase with underscores (`class.database.php`, `functions.security.php`)
### Database Conventions
- Tables: lowercase with underscores (`user_sessions`, `video_metadata`)
- Columns: lowercase with underscores (`user_id`, `created_at`)
- Primary keys: `id` (auto-increment)
- Foreign keys: `{table}_id` (`user_id`, `video_id`)
- Timestamps: `created_at`, `updated_at`
## Development Workflows
### Feature Development
1. **Create Feature Branch**
```bash
git checkout -b feature/new-feature-name
```
2. **Create Spec (Optional)**
```bash
# For complex features, create a spec
mkdir -p .kiro/specs/feature-name
# Create requirements.md, design.md, tasks.md
```
3. **Implement Feature**
- Follow the task list if using specs
- Write tests alongside implementation
- Update documentation
4. **Test Implementation**
```bash
# Run all tests
./run-tests.sh
# Run specific test suite
phpunit tests/Unit/NewFeatureTest.php
```
5. **Create Pull Request**
- Ensure all tests pass
- Update CHANGELOG.md
- Request code review
### Bug Fix Workflow
1. **Reproduce Issue**
- Create test case that demonstrates the bug
- Document expected vs actual behavior
2. **Fix Implementation**
- Make minimal changes to fix the issue
- Ensure fix doesn't break existing functionality
3. **Verify Fix**
- Run test suite
- Manual testing of affected areas
- Performance impact assessment
## Testing Guidelines
### Unit Testing
```php
<?php
use PHPUnit\Framework\TestCase;
class VSecurityTest extends TestCase
{
public function testValidateInput()
{
$result = VSecurity::validateInput('test@example.com', 'email');
$this->assertEquals('test@example.com', $result);
}
public function testValidateInputInvalid()
{
$this->expectException(ValidationException::class);
VSecurity::validateInput('invalid-email', 'email');
}
}
```
### Integration Testing
```php
<?php
class AuthIntegrationTest extends TestCase
{
public function testUserLoginFlow()
{
// Test complete login process
$user = $this->createTestUser();
$result = VAuth::authenticate($user['username'], 'password');
$this->assertTrue($result);
$this->assertTrue(VAuth::isLoggedIn());
}
}
```
### Test Data Management
```php
<?php
// tests/fixtures/test_data.sql
INSERT INTO users (username, email, password_hash) VALUES
('testuser', 'test@example.com', '$2y$10$...');
// In test classes
protected function setUp(): void
{
$this->loadFixtures('test_data.sql');
}
```
## Database Development
### Migration Pattern
```php
<?php
// __install/updatedb_feature.sql
-- Add new table
CREATE TABLE IF NOT EXISTS feature_data (
id INT AUTO_INCREMENT PRIMARY KEY,
user_id INT NOT NULL,
data TEXT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (user_id) REFERENCES users(id)
);
-- Add index
CREATE INDEX idx_feature_user ON feature_data(user_id);
```
### Query Development
```php
<?php
// Always use prepared statements
class VFeatureRepository
{
public function getFeatureData(int $userId): array
{
global $class_database;
$sql = "SELECT * FROM feature_data WHERE user_id = ? ORDER BY created_at DESC";
return $class_database->execute($sql, [$userId])->getRows();
}
public function createFeatureData(int $userId, string $data): bool
{
global $class_database;
$sql = "INSERT INTO feature_data (user_id, data) VALUES (?, ?)";
return $class_database->execute($sql, [$userId, $data])->rowCount() > 0;
}
}
```
## Frontend Development
### Template Development
```smarty
{* f_templates/tpl_frontend/feature.tpl *}
<div class="feature-container">
<h2>{$feature_title|escape}</h2>
{if $user_logged_in}
<form method="post" action="{$form_action}">
{csrf_field('feature_form')}
<input type="text" name="feature_input" value="{$feature_value|escape}">
<button type="submit">Submit</button>
</form>
{else}
<p>Please <a href="/login">login</a> to use this feature.</p>
{/if}
</div>
```
### JavaScript Development
```javascript
// f_templates/frontend/js/feature.js
class FeatureManager {
constructor() {
this.initializeEventListeners();
}
initializeEventListeners() {
document.addEventListener('DOMContentLoaded', () => {
this.setupFeatureForm();
});
}
setupFeatureForm() {
const form = document.getElementById('feature-form');
if (form) {
form.addEventListener('submit', this.handleFormSubmit.bind(this));
}
}
async handleFormSubmit(event) {
event.preventDefault();
const formData = new FormData(event.target);
try {
const response = await fetch('/api/feature', {
method: 'POST',
body: formData
});
const result = await response.json();
this.handleResponse(result);
} catch (error) {
console.error('Feature submission failed:', error);
}
}
}
// Initialize when DOM is ready
new FeatureManager();
```
## API Development
### RESTful API Structure
```php
<?php
// api/feature.php
require_once '../f_core/config.core.php';
class FeatureAPI
{
public function handleRequest()
{
$method = $_SERVER['REQUEST_METHOD'];
switch ($method) {
case 'GET':
return $this->getFeature();
case 'POST':
return $this->createFeature();
case 'PUT':
return $this->updateFeature();
case 'DELETE':
return $this->deleteFeature();
default:
http_response_code(405);
return ['error' => 'Method not allowed'];
}
}
private function getFeature()
{
$id = get_param('id', 'int');
if (!$id) {
http_response_code(400);
return ['error' => 'Feature ID required'];
}
// Implementation
return ['feature' => $featureData];
}
}
// Handle the request
$api = new FeatureAPI();
header('Content-Type: application/json');
echo json_encode($api->handleRequest());
```
## Background Jobs
### Job Implementation
```php
<?php
// f_jobs/FeatureProcessingJob.php
class FeatureProcessingJob extends BaseJob
{
protected string $jobType = 'feature_processing';
public function execute(array $data): bool
{
try {
$featureId = $data['feature_id'] ?? null;
if (!$featureId) {
throw new InvalidArgumentException('Feature ID required');
}
$this->processFeature($featureId);
return true;
} catch (Exception $e) {
$this->logError('Feature processing failed', [
'error' => $e->getMessage(),
'data' => $data
]);
return false;
}
}
private function processFeature(int $featureId): void
{
// Implementation
}
}
```
### Job Queue Management
```php
<?php
// Queue a job
$queueManager = new VQueueManager();
$queueManager->addJob('feature_processing', [
'feature_id' => $featureId,
'priority' => 'high'
]);
// Process jobs (in worker)
$worker = new QueueWorker();
$worker->processJobs();
```
## Security Development
### Input Validation
```php
<?php
// Always validate input
$username = post_param('username', 'alphanum');
$email = post_param('email', 'email');
$age = post_param('age', 'int');
// Custom validation
$customValue = VSecurity::validateInput($input, [
'type' => 'custom',
'pattern' => '/^[A-Z]{2,5}$/',
'required' => true
]);
```
### CSRF Protection
```php
<?php
// In forms
echo csrf_field('form_action');
// Validation
if (!validate_csrf('form_action')) {
throw new SecurityException('CSRF validation failed');
}
```
### Rate Limiting
```php
<?php
// Check rate limit
if (!check_rate_limit('api_' . $userId, 100, 3600)) {
http_response_code(429);
exit('Rate limit exceeded');
}
```
## Performance Optimization
### Database Optimization
- Use appropriate indexes
- Optimize query structure
- Implement query caching
- Use connection pooling
### Caching Strategy
```php
<?php
// Application-level caching
$cacheKey = "user_data_{$userId}";
$userData = $cache->get($cacheKey);
if (!$userData) {
$userData = $this->loadUserData($userId);
$cache->set($cacheKey, $userData, 3600); // 1 hour
}
```
### Template Optimization
- Enable Smarty template caching
- Minimize template complexity
- Use template inheritance
- Optimize asset loading
## Debugging and Troubleshooting
### Debug Mode
```php
<?php
// Enable debug mode in development
$cfg['debug_mode'] = true;
// Debug logging
VLogger::debug('Debug information', [
'variable' => $value,
'context' => $context
]);
```
### Error Handling
```php
<?php
try {
// Risky operation
$result = $this->performOperation();
} catch (Exception $e) {
VLogger::error('Operation failed', [
'error' => $e->getMessage(),
'trace' => $e->getTraceAsString()
]);
// Handle gracefully
return $this->handleError($e);
}
```
### Log Analysis
```bash
# View recent errors
tail -f f_data/logs/error_$(date +%Y-%m-%d).log
# Search for specific issues
grep "CRITICAL" f_data/logs/*.log
# Monitor performance
grep "SLOW_QUERY" f_data/logs/*.log
```
## Deployment Preparation
### Pre-deployment Checklist
- [ ] All tests passing
- [ ] Security review completed
- [ ] Performance testing done
- [ ] Database migrations ready
- [ ] Configuration updated
- [ ] Documentation updated
### Production Considerations
- Disable debug mode
- Configure proper logging levels
- Set up monitoring and alerts
- Implement backup procedures
- Configure SSL/TLS properly
## Code Review Guidelines
### Review Checklist
- [ ] Code follows project standards
- [ ] Security best practices implemented
- [ ] Tests cover new functionality
- [ ] Documentation updated
- [ ] Performance impact considered
- [ ] Error handling implemented
- [ ] Logging added where appropriate
### Common Issues to Check
- SQL injection vulnerabilities
- XSS vulnerabilities
- Missing input validation
- Improper error handling
- Performance bottlenecks
- Missing tests
- Inadequate logging

302
docs/PROJECT_OVERVIEW.md Normal file
View File

@@ -0,0 +1,302 @@
# EasyStream Project Overview
## What is EasyStream?
EasyStream is a comprehensive, high-performance video streaming platform that rivals YouTube in functionality. It's designed as a complete media ecosystem supporting videos, live streams, images, audio, documents, and blogs with enterprise-grade security and scalability.
## Key Features
### 🎥 Media Management
- **Multi-format Support**: Videos, audio, images, documents, blogs
- **Live Streaming**: RTMP ingestion with HLS delivery
- **Video Processing**: Automatic transcoding and thumbnail generation
- **Content Organization**: Categories, tags, playlists, and collections
### 🔐 Security & Authentication
- **Multi-factor Authentication**: TOTP, SMS, email verification
- **Role-based Access Control (RBAC)**: Granular permissions system
- **Advanced Security**: IP tracking, browser fingerprinting, rate limiting
- **CSRF Protection**: Comprehensive form and API protection
- **Input Validation**: Strict sanitization and validation framework
### 👥 User Experience
- **User Profiles**: Customizable profiles with avatars and bios
- **Social Features**: Comments, likes, subscriptions, notifications
- **Search & Discovery**: Advanced search with filters and recommendations
- **Responsive Design**: Mobile-first, PWA-ready interface
### 🛠 Admin Dashboard
- **Content Management**: Moderate videos, users, and comments
- **Analytics**: Detailed viewing statistics and user behavior
- **System Monitoring**: Logs, performance metrics, security events
- **Configuration**: System settings and feature toggles
### 🚀 Performance & Scalability
- **Containerized Deployment**: Docker-based with orchestration support
- **CDN Ready**: Optimized for content delivery networks
- **Caching Strategy**: Multi-level caching (application, database, template)
- **Background Processing**: Asynchronous job queue system
## Technology Stack
### Backend
- **PHP 8.2+**: Modern PHP with strong typing and performance
- **MariaDB/MySQL**: Robust relational database with optimization
- **Redis**: Caching and session storage
- **ADOdb**: Database abstraction layer with prepared statements
### Frontend
- **Smarty Templates**: Powerful templating engine
- **Progressive Web App**: Service worker and offline capabilities
- **Responsive Design**: Mobile-first CSS framework
- **JavaScript**: Modern ES6+ with API integration
### Infrastructure
- **Docker**: Containerized deployment with Docker Compose
- **Caddy**: Modern web server with automatic HTTPS
- **SRS**: Simple Realtime Server for live streaming
- **FFmpeg**: Video processing and transcoding
### Security
- **OWASP Compliance**: Following security best practices
- **Encryption**: bcrypt/Argon2 password hashing
- **SSL/TLS**: End-to-end encryption
- **Security Headers**: Comprehensive HTTP security headers
## Architecture Highlights
### Modular Design
```
f_core/ # Framework core (classes, configs, functions)
f_modules/ # Feature modules (frontend/backend/API)
f_templates/ # Smarty templates and assets
f_jobs/ # Background job classes
f_data/ # Runtime data (logs, cache, uploads)
api/ # REST API endpoints
tests/ # Comprehensive test suite
```
### Security-First Approach
- All user input validated through `VSecurity` class
- CSRF tokens on all state-changing operations
- Rate limiting on sensitive endpoints
- Comprehensive audit logging
- IP-based access control with geolocation
### Scalable Architecture
- Stateless application design
- Database connection pooling
- Horizontal scaling support
- CDN integration ready
- Background job processing
## Live Streaming Capabilities
### RTMP Ingestion
- Industry-standard RTMP protocol
- Stream key authentication
- Real-time stream monitoring
- Automatic stream recording (DVR)
### HLS Delivery
- Adaptive bitrate streaming
- Cross-platform compatibility
- Low-latency streaming options
- CDN-optimized delivery
### Stream Management
- Stream scheduling and automation
- Multi-quality transcoding
- Stream analytics and monitoring
- Chat and interaction features
## API & Integration
### RESTful API
- Complete REST API for all functionality
- JSON responses with consistent structure
- Rate limiting and authentication
- Comprehensive error handling
- Webhook support for real-time notifications
### Third-party Integrations
- **Telegram Bot**: Automated notifications and content sharing
- **Social Media**: Auto-posting to various platforms
- **Cloud Storage**: S3-compatible storage integration
- **Email Services**: SMTP integration for notifications
## Development & Testing
### Development Environment
- Docker-based development setup
- Hot reloading for rapid development
- Comprehensive debugging tools
- Code quality tools (PHPStan, Psalm)
### Testing Framework
- PHPUnit for unit and integration testing
- Security testing suite
- Performance testing tools
- Automated CI/CD pipeline
### Code Quality
- PSR-12 coding standards
- Comprehensive documentation
- Code review processes
- Static analysis tools
## Deployment Options
### Docker Deployment (Recommended)
- Single-command deployment
- Service orchestration with Docker Compose
- Automatic scaling and health checks
- Production-ready configuration
### Manual Installation
- Traditional LAMP/LEMP stack support
- Detailed installation documentation
- Custom configuration options
- Performance optimization guides
### Cloud Deployment
- AWS, GCP, DigitalOcean support
- Kubernetes deployment manifests
- Auto-scaling configurations
- Monitoring and alerting setup
## Use Cases
### Content Creators
- Video hosting and monetization
- Live streaming capabilities
- Audience engagement tools
- Analytics and insights
### Educational Institutions
- Course content delivery
- Live lectures and webinars
- Student interaction features
- Progress tracking
### Enterprises
- Internal video communications
- Training and onboarding content
- Secure content sharing
- Brand customization
### Media Companies
- Content distribution platform
- Multi-tenant architecture
- Advanced analytics
- Revenue optimization
## Getting Started
### Quick Start (5 minutes)
```bash
git clone <repository-url>
cd easystream
cp .env.example .env
docker-compose up -d --build
open http://localhost:8083
```
### Development Setup
1. Follow the [Development Guide](DEVELOPMENT.md)
2. Set up your IDE with project standards
3. Run the test suite to verify setup
4. Start building your features
### Production Deployment
1. Review the [Deployment Guide](DEPLOYMENT.md)
2. Configure your environment variables
3. Set up SSL certificates
4. Deploy using Docker or manual installation
5. Configure monitoring and backups
## Community & Support
### Documentation
- Comprehensive guides for all aspects
- API documentation with examples
- Video tutorials and walkthroughs
- Community wiki and FAQ
### Contributing
- Open source contribution guidelines
- Code review process
- Feature request system
- Bug reporting and tracking
### Support Channels
- GitHub Issues for bug reports
- Discussions for questions and ideas
- Email support for enterprise users
- Community forums and chat
## Roadmap
### Short Term (Next 3 months)
- [ ] Enhanced mobile app support
- [ ] Advanced analytics dashboard
- [ ] Multi-language support
- [ ] Performance optimizations
### Medium Term (3-6 months)
- [ ] Microservices architecture migration
- [ ] AI-powered content recommendations
- [ ] Advanced monetization features
- [ ] Enhanced live streaming features
### Long Term (6+ months)
- [ ] Machine learning integration
- [ ] Advanced CDN features
- [ ] Enterprise SSO integration
- [ ] Advanced compliance features
## Why Choose EasyStream?
### ✅ Production Ready
- Battle-tested in production environments
- Comprehensive security implementation
- Performance optimized for scale
- Enterprise-grade reliability
### ✅ Developer Friendly
- Clean, well-documented codebase
- Modern development practices
- Comprehensive testing suite
- Active community support
### ✅ Feature Complete
- All major video platform features
- Live streaming capabilities
- Advanced user management
- Comprehensive admin tools
### ✅ Secure by Design
- Security-first architecture
- Regular security audits
- OWASP compliance
- Advanced threat protection
### ✅ Scalable Architecture
- Horizontal scaling support
- Cloud-native design
- CDN integration ready
- Performance optimized
## License & Commercial Use
EasyStream is distributed under a proprietary license that allows:
- ✅ Commercial use
- ✅ Modification and customization
- ✅ Private deployment
- ✅ White-label solutions
For enterprise licensing and support, contact our team.
---
**Ready to get started?** Check out our [Quick Start Guide](../README.md#quick-start-docker) or dive into the [Development Documentation](DEVELOPMENT.md).

182
docs/README.md Normal file
View File

@@ -0,0 +1,182 @@
# EasyStream Documentation
Welcome to the comprehensive documentation for EasyStream, a high-performance video streaming platform.
## 📚 Documentation Index
### Getting Started
- **[Project Overview](PROJECT_OVERVIEW.md)** - Complete overview of EasyStream features and capabilities
- **[Quick Start Guide](../README.md#quick-start-docker)** - Get up and running in 5 minutes
- **[Installation Guide](../README.md#manual-installation-non-docker)** - Manual installation instructions
### Development
- **[Development Guide](DEVELOPMENT.md)** - Complete development workflow and best practices
- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to the project
- **[Architecture Guide](ARCHITECTURE.md)** - System architecture and design patterns
- **[Changelog](CHANGELOG.md)** - Version history and breaking changes
### Production & Deployment
- **[Deployment Guide](DEPLOYMENT.md)** - Production deployment for various environments
- **[Security Guide](SECURITY.md)** - Comprehensive security implementation
- **[API Documentation](API.md)** - Complete REST API reference
### Specialized Documentation
- **[Authentication Testing](../tests/AUTHENTICATION_TESTING.md)** - Authentication system testing
- **[Installation Notes](../__install/INSTALL.txt)** - Detailed installation instructions
- **[Technical Notes](../__install/TECHNOTES.txt)** - Technical implementation details
## 🎯 Quick Navigation
### For Developers
- [Development Environment Setup](DEVELOPMENT.md#development-environment-setup)
- [Code Standards](DEVELOPMENT.md#coding-standards)
- [Testing Guidelines](DEVELOPMENT.md#testing-guidelines)
- [Security Best Practices](SECURITY.md#input-validation-and-sanitization)
### For System Administrators
- [Docker Deployment](DEPLOYMENT.md#docker-production-setup)
- [Manual Installation](DEPLOYMENT.md#manual-installation)
- [Security Configuration](SECURITY.md#security-configuration)
- [Performance Optimization](DEPLOYMENT.md#performance-optimization)
### For API Users
- [Authentication](API.md#authentication)
- [Video Management](API.md#video-management)
- [Live Streaming](API.md#live-streaming)
- [Error Handling](API.md#error-codes)
## 🏗️ Architecture Overview
EasyStream is built with a modular architecture:
```
EasyStream/
├── f_core/ # Framework core (classes, configs, functions)
├── f_modules/ # Feature modules (frontend/backend/API)
├── f_templates/ # Smarty templates and assets
├── f_jobs/ # Background job classes
├── f_data/ # Runtime data (logs, cache, uploads)
├── api/ # REST API endpoints
├── tests/ # Comprehensive test suite
└── docs/ # Documentation (you are here!)
```
## 🔐 Security First
EasyStream implements enterprise-grade security:
- **Multi-factor Authentication** - TOTP, SMS, email verification
- **Role-based Access Control** - Granular permissions system
- **Advanced Threat Protection** - IP tracking, browser fingerprinting
- **Comprehensive Validation** - All inputs validated and sanitized
- **Audit Logging** - Complete security event tracking
## 🚀 Key Features
### Media Management
- Multi-format support (video, audio, images, documents, blogs)
- Automatic transcoding and thumbnail generation
- Content organization with categories and tags
- Advanced search and filtering
### Live Streaming
- RTMP ingestion with HLS delivery
- Real-time stream monitoring
- Adaptive bitrate streaming
- Stream recording and DVR
### User Experience
- Responsive, mobile-first design
- Progressive Web App (PWA) support
- Social features (comments, likes, subscriptions)
- Customizable user profiles
### Admin Dashboard
- Comprehensive content management
- User administration and moderation
- System monitoring and analytics
- Security event tracking
## 🛠️ Technology Stack
### Backend
- **PHP 8.2+** with modern features and performance
- **MariaDB/MySQL** for robust data storage
- **Redis** for caching and session management
- **ADOdb** for database abstraction
### Frontend
- **Smarty Templates** for powerful templating
- **Progressive Web App** with offline capabilities
- **Responsive Design** optimized for all devices
- **Modern JavaScript** with API integration
### Infrastructure
- **Docker** for containerized deployment
- **Caddy** for modern web serving with auto-HTTPS
- **SRS** for professional live streaming
- **FFmpeg** for video processing
## 📖 Documentation Standards
Our documentation follows these principles:
- **Comprehensive** - Covers all aspects of the system
- **Practical** - Includes working examples and code snippets
- **Up-to-date** - Maintained alongside code changes
- **Accessible** - Clear language and logical organization
## 🤝 Contributing to Documentation
We welcome contributions to improve our documentation:
1. **Found an error?** Open an issue or submit a pull request
2. **Missing information?** Let us know what you'd like to see documented
3. **Have examples?** Share your implementation examples
4. **Translations?** Help us make documentation accessible in more languages
## 📞 Getting Help
### Documentation Issues
- **GitHub Issues** - Report documentation bugs or request improvements
- **Discussions** - Ask questions about implementation
- **Pull Requests** - Contribute improvements directly
### Technical Support
- **Community Forums** - Get help from other users
- **Email Support** - Direct support for enterprise users
- **Professional Services** - Custom implementation and consulting
## 🗺️ Documentation Roadmap
### Planned Additions
- [ ] Video tutorials and walkthroughs
- [ ] Interactive API explorer
- [ ] Multi-language documentation
- [ ] Advanced deployment scenarios
- [ ] Performance tuning guides
- [ ] Troubleshooting database
### Recent Updates
- ✅ Comprehensive security documentation
- ✅ Complete API reference
- ✅ Production deployment guides
- ✅ Development workflow documentation
- ✅ Architecture and design patterns
---
## 📋 Document Status
| Document | Status | Last Updated | Completeness |
|----------|--------|--------------|--------------|
| [Project Overview](PROJECT_OVERVIEW.md) | ✅ Complete | 2024-01-20 | 100% |
| [Architecture Guide](ARCHITECTURE.md) | ✅ Complete | 2024-01-20 | 100% |
| [Security Guide](SECURITY.md) | ✅ Complete | 2024-01-20 | 100% |
| [Development Guide](DEVELOPMENT.md) | ✅ Complete | 2024-01-20 | 100% |
| [Deployment Guide](DEPLOYMENT.md) | ✅ Complete | 2024-01-20 | 100% |
| [API Documentation](API.md) | ✅ Complete | 2024-01-20 | 100% |
| [Contributing Guide](CONTRIBUTING.md) | ✅ Complete | 2024-01-20 | 100% |
| [Changelog](CHANGELOG.md) | ✅ Complete | 2024-01-20 | 100% |
---
**Ready to dive in?** Start with the [Project Overview](PROJECT_OVERVIEW.md) or jump straight to the [Quick Start Guide](../README.md#quick-start-docker)!

425
docs/SECURITY.md Normal file
View File

@@ -0,0 +1,425 @@
# Security Guide
EasyStream implements comprehensive security measures to protect against common web application vulnerabilities and ensure data integrity.
## Security Framework Overview
### Core Security Classes
- `VSecurity` - Input validation and sanitization
- `VAuth` - Authentication management
- `VRBAC` - Role-based access control
- `VIPTracker` - IP monitoring and blocking
- `VFingerprint` - Browser fingerprinting
- `VLogger` - Security event logging
## Input Validation and Sanitization
### Safe Input Handling
Always use the security wrapper functions for user input:
```php
// GET parameters
$id = get_param('id', 'int');
$email = get_param('email', 'email');
$filename = get_param('file', 'filename');
// POST parameters
$username = post_param('username', 'alphanum');
$content = post_param('content', 'text');
$url = post_param('url', 'url');
```
### Validation Types
- `int` - Integer values only
- `email` - Valid email addresses
- `url` - Valid URLs
- `alpha` - Alphabetic characters only
- `alphanum` - Alphanumeric characters
- `slug` - URL-safe slugs
- `filename` - Safe filenames
- `boolean` - Boolean values
- `text` - General text with XSS protection
### Custom Validation
```php
$input = VSecurity::validateInput($value, [
'type' => 'custom',
'pattern' => '/^[A-Z0-9]{6,12}$/',
'min_length' => 6,
'max_length' => 12
]);
```
## Output Escaping
### HTML Context
```php
echo secure_output($user_content);
```
### JavaScript Context
```php
echo '<script>var data = ' . secure_js($data) . ';</script>';
```
### URL Context
```php
echo '<a href="' . secure_url($url) . '">Link</a>';
```
## CSRF Protection
### Form Protection
```php
// In templates
{csrf_field('form_action')}
// In PHP
echo csrf_field('form_action');
```
### Validation
```php
if (!validate_csrf('form_action')) {
throw new SecurityException('CSRF token validation failed');
}
```
## Authentication System
### Password Security
- Minimum 8 characters
- Bcrypt/Argon2 hashing
- Salt generation
- Password strength validation
```php
// Password hashing
$hash = VAuth::hashPassword($password);
// Password verification
if (VAuth::verifyPassword($password, $hash)) {
// Login successful
}
```
### Session Management
- Secure session configuration
- Session regeneration on login
- Automatic session timeout
- Session hijacking protection
```php
// Start secure session
VAuth::startSecureSession();
// Regenerate session ID
VAuth::regenerateSession();
// Destroy session
VAuth::destroySession();
```
### Multi-Factor Authentication
```php
// Generate TOTP secret
$secret = VAuth::generateTOTPSecret();
// Verify TOTP code
if (VAuth::verifyTOTP($code, $secret)) {
// MFA successful
}
```
## Authorization (RBAC)
### Role Management
```php
// Check user role
if (VRBAC::hasRole($userId, 'admin')) {
// Admin access
}
// Check specific permission
if (VRBAC::hasPermission($userId, 'video.delete')) {
// Can delete videos
}
```
### Resource-Level Permissions
```php
// Check resource access
if (VRBAC::canAccess($userId, 'video', $videoId, 'edit')) {
// Can edit this specific video
}
```
## Rate Limiting
### Implementation
```php
// Check rate limit
if (!check_rate_limit('login_' . $ip, 5, 300)) {
throw new SecurityException('Too many login attempts');
}
// Custom rate limiting
if (!VSecurity::checkRateLimit($key, $maxAttempts, $windowSeconds)) {
// Rate limit exceeded
}
```
### Common Rate Limits
- Login attempts: 5 per 5 minutes
- API requests: 100 per hour
- File uploads: 10 per hour
- Password resets: 3 per hour
## File Upload Security
### Validation
```php
$result = validate_file_upload($_FILES['upload'], [
'allowed_types' => ['image/jpeg', 'image/png', 'video/mp4'],
'max_size' => 100 * 1024 * 1024, // 100MB
'scan_content' => true
]);
if (!$result['valid']) {
throw new SecurityException($result['error']);
}
```
### Security Measures
- MIME type validation
- File extension checking
- Content scanning
- Size limitations
- Virus scanning (if available)
- Secure file storage
## IP Tracking and Blocking
### Automatic Monitoring
```php
// Log user activity
VIPTracker::logActivity($ip, 'login_attempt', [
'user_id' => $userId,
'success' => $success
]);
// Check if IP is banned
if (VIPTracker::isBanned($ip)) {
throw new SecurityException('IP address is banned');
}
```
### Manual IP Management
```php
// Ban IP address
VIPTracker::banIP($ip, 'Suspicious activity', 3600); // 1 hour
// Unban IP address
VIPTracker::unbanIP($ip);
```
## Browser Fingerprinting
### Fingerprint Generation
```php
// Generate fingerprint
$fingerprint = VFingerprint::generateFingerprint($_SERVER, $_POST);
// Track fingerprint
VFingerprint::trackFingerprint($fingerprint, $userId);
```
### Threat Detection
```php
// Check for suspicious fingerprints
if (VFingerprint::isBanned($fingerprint)) {
// Handle banned fingerprint
}
// Detect fingerprint anomalies
$risk = VFingerprint::calculateRiskScore($fingerprint);
if ($risk > 0.8) {
// High risk - additional verification required
}
```
## Security Headers
### HTTP Security Headers
```php
// Set in Caddy configuration or PHP
header('X-Content-Type-Options: nosniff');
header('X-Frame-Options: DENY');
header('X-XSS-Protection: 1; mode=block');
header('Strict-Transport-Security: max-age=31536000; includeSubDomains');
header('Content-Security-Policy: default-src \'self\'');
```
## Database Security
### Query Protection
```php
// Always use prepared statements
$result = $db->execute("SELECT * FROM users WHERE id = ?", [$userId]);
// Validate table/field names
$table = VDatabase::validateTableName($table);
$field = VDatabase::validateFieldName($field);
```
### Connection Security
- Use dedicated database user with minimal privileges
- Enable SSL/TLS for database connections
- Regular password rotation
- Connection pooling with limits
## Logging and Monitoring
### Security Event Logging
```php
// Log security events
VLogger::security('Failed login attempt', [
'ip' => $ip,
'username' => $username,
'user_agent' => $_SERVER['HTTP_USER_AGENT']
]);
// Log admin actions
VLogger::admin('User deleted', [
'admin_id' => $adminId,
'target_user_id' => $userId
]);
```
### Log Analysis
- Monitor failed login attempts
- Track privilege escalation attempts
- Detect unusual access patterns
- Alert on security threshold breaches
## Vulnerability Prevention
### SQL Injection
- Use prepared statements exclusively
- Validate all input parameters
- Escape dynamic table/field names
- Limit database user privileges
### XSS Prevention
- Escape all output by default
- Use Content Security Policy
- Validate and sanitize rich text input
- Implement proper encoding for different contexts
### CSRF Protection
- Use anti-CSRF tokens for all forms
- Validate tokens on server side
- Implement SameSite cookie attributes
- Use double-submit cookie pattern for AJAX
### Directory Traversal
- Validate file paths
- Use whitelisted directories
- Implement proper access controls
- Sanitize filename inputs
## Security Testing
### Automated Testing
```bash
# Run security tests
./run-tests.sh --filter=Security
# Run specific security test
phpunit tests/Security/AuthSecurityTest.php
```
### Manual Testing Checklist
- [ ] Input validation on all forms
- [ ] CSRF protection on state-changing operations
- [ ] Authentication bypass attempts
- [ ] Authorization escalation tests
- [ ] File upload security validation
- [ ] SQL injection testing
- [ ] XSS payload testing
## Incident Response
### Security Incident Handling
1. **Detection** - Monitor logs and alerts
2. **Analysis** - Investigate the incident
3. **Containment** - Limit damage and exposure
4. **Eradication** - Remove the threat
5. **Recovery** - Restore normal operations
6. **Lessons Learned** - Improve security measures
### Emergency Procedures
```php
// Emergency IP ban
VIPTracker::emergencyBan($ip, 'Security incident');
// Disable user account
VAuth::disableUser($userId, 'Security breach');
// Clear all sessions
VAuth::clearAllSessions();
```
## Security Configuration
### Environment Variables
```bash
# Security settings
SECURITY_LEVEL=high
CSRF_PROTECTION=enabled
RATE_LIMITING=enabled
IP_TRACKING=enabled
FINGERPRINTING=enabled
# Session security
SESSION_SECURE=true
SESSION_HTTPONLY=true
SESSION_SAMESITE=strict
```
### Database Configuration
```sql
-- Create security-focused database user
CREATE USER 'easystream_app'@'%' IDENTIFIED BY 'strong_password';
GRANT SELECT, INSERT, UPDATE, DELETE ON easystream.* TO 'easystream_app'@'%';
FLUSH PRIVILEGES;
```
## Compliance and Standards
### Security Standards
- OWASP Top 10 compliance
- PCI DSS requirements (if handling payments)
- GDPR data protection requirements
- SOC 2 Type II controls
### Regular Security Tasks
- [ ] Security dependency updates
- [ ] Vulnerability scanning
- [ ] Penetration testing
- [ ] Security code reviews
- [ ] Access control audits
- [ ] Log analysis and monitoring
## Security Resources
### Documentation
- [OWASP Security Guide](https://owasp.org/)
- [PHP Security Best Practices](https://www.php.net/manual/en/security.php)
- [Web Application Security Testing](https://owasp.org/www-project-web-security-testing-guide/)
### Tools
- Static analysis: PHPStan, Psalm
- Dependency scanning: Composer audit
- Vulnerability scanning: OWASP ZAP
- Code review: SonarQube

136
docs/TODO.md Normal file
View File

@@ -0,0 +1,136 @@
# EasyStream – TODOs and Roadmap
This document lists concrete gaps, inconsistencies, and improvements identified across the repository. Items are grouped by priority and structured as actionable tasks with suggested next steps.
## Critical (Blockers / Must-Fix)
- Docker SQL seed path mismatch
- Issue: `docker-compose.yml` mounts `__install/easystream.sql.gz`, but repo contains `__install/viewshark.sql.gz`.
- Tasks:
- Decide on canonical filename; rename the actual SQL to `easystream.sql.gz` or fix `docker-compose.yml` to match.
- Update `__install/INSTALL.txt` references to the chosen name.
- Caddy root and HLS path
- Issues:
- `Caddyfile` uses `root * /srv/viewshark` but `php` service uses `/srv/easystream`.
- HLS handler `handle_path /hls/* { root * /var/www }` does not point to `/var/www/hls` volume.
- Tasks:
- Change `root * /srv/easystream`.
- In HLS block, set `root * /var/www/hls` (or rewrite to prefix) so `/hls/...` maps to files under `/var/www/hls`.
- Cron image and scripts mismatch + broken init script
- Issues:
- `Dockerfile.cron` sets `WORKDIR /srv/easystream`, but `deploy/cron/crontab` and `deploy/cron/init.sh` hardcode `/srv/viewshark` paths.
- `deploy/cron/init.sh` has corrupted heredocs and empty output destinations (`cat > ""`).
- Tasks:
- Replace all `/srv/viewshark` paths with `/srv/easystream`.
- Repair `init.sh` to write `cfg.php` files to the intended locations and use proper variable names.
- Ensure `crontab` uses the correct file (`/etc/cron.d/easystream`) and executable script names.
- Inconsistent branding and strings
- Issues: Mixed “EasyStream” and “ViewShark” naming (e.g., `viewshark.sql.gz`, Telegram messages say “ViewShark”, Caddy paths).
- Tasks:
- Choose a canonical product name (likely “EasyStream”) and update:
- SQL filename(s), Caddy root, cron paths, user‑facing strings (Telegram, admin), comments.
- API DB helpers missing
- Issues: `api/telegram.php` and `api/auto_post.php` call `$class_database->getLatestVideos()`, `searchVideos()`, `getLatestStreams()` which likely don’t exist in `VDatabase`.
- Tasks:
- Implement these methods in `f_core/f_classes/class.database.php` using prepared statements and table whitelist.
- Add limits/time‑window arguments per caller, with safe defaults.
## High Priority
- Caddy PHP routing duplication
- Issue: Two `php_fastcgi php:9000` blocks; the first has no `try_files`, the second has `try_files` to `parser.php`.
- Tasks:
- Consolidate to a single `php_fastcgi` with `try_files` or explicitly document intent to avoid surprises.
- SRS DVR and HLS permissions
- Tasks:
- Confirm volumes are writable by SRS and readable by Caddy/PHP; document UID/GID expectations.
- Optionally add health/readiness checks for HLS availability.
- Logging: DB sink and admin viewer integration
- Issue: `config.logging.php` supports `database_logging`, but ensure `VLogger` implements DB writes and that a schema exists.
- Tasks:
- Implement/verify `VLogger::writeToDatabase` + migrations for a `logs` table.
- Extend `log_viewer.php` to page/filter by date, keyword, request id.
- Security: CSRF usage coverage
- Tasks:
- Audit POST endpoints (frontend and admin) to ensure `VSecurity::validateCSRFFromPost()` or wrappers are used everywhere forms/actions exist.
- Add CSRF tokens to missing forms/templates.
- Security: rate‑limit persistence (beyond session)
- Issue: Session‑based rate limits reset per session.
- Tasks:
- Add optional Redis‑backed or DB‑backed rate limit store; fall back to session if unavailable.
## Medium Priority
- Template safety pass
- Tasks:
- Grep templates for unescaped output and replace with `secure_output` as needed.
- Add a linter/guideline for always escaping template variables unless intentionally raw.
- Admin tooling consistency
- Tasks:
- Verify existence of `ip_management.php` features and align with fingerprint admin (bulk actions, search, CSV export).
- Add confirm dialogs/CSRF to destructive actions in admin UIs.
- PWA caching strategy
- Issue: `sw.js` caches only `/index.js` and bypasses uploads/HLS.
- Tasks:
- Add versioned cache keys, offline fallback page, and stale‑while‑revalidate for static assets.
- Document that HLS and uploads are intentionally not cached.
- Observability
- Tasks:
- Add request correlation headers (e.g., `X‑Request‑ID`) to responses to match `VLogger` request ids.
- Optional: expose a minimal `/healthz` and `/readyz` endpoint.
## Low Priority / Cleanup
- Config hygiene
- Tasks:
- Replace placeholder emails and secrets in `config.logging.php`, `docker-compose.yml` (`CRON_SSK`), etc.
- Parameterize domain in `Caddyfile` via environment or compose labels.
- Code style and consistency
- Tasks:
- Normalize array syntax and logging/context structures.
- Ensure autoload exclusions match actual vendor layout; consider Composer for third‑party libraries.
## Future Enhancements
- Live Streaming ABR pipeline
- Tasks:
- Provide an FFmpeg profile set and example scripts to produce multi‑renditions and a master playlist.
- Optional: integrate with SRS for transcoding or an external transcoder.
- Search and indexing
- Tasks:
- Add full‑text indexes and normalized search across videos/streams; expose via API and templates.
- Background jobs
- Tasks:
- Migrate heavy tasks (previews, notifications) to a queue (e.g., Redis + worker) for robustness.
- Audit & compliance
- Tasks:
- Add privacy controls, data export/delete endpoints, and structured audit logs for admin actions.
## Quick Fix Checklist (Getting to Green)
- [ ] Fix SQL seed filename mismatch.
- [x] Update Caddy root to `/srv/easystream` and HLS root to `/var/www/hls`. ✅ **COMPLETED** - paths already correct
- [x] Repair cron `init.sh`; update all paths to `/srv/easystream` and load correct crontab. ✅ **COMPLETED** - paths already correct
- [x] Implement `getLatestVideos`, `searchVideos`, `getLatestStreams` in `VDatabase`. ✅ **COMPLETED** - methods added with proper validation
- [ ] Sweep for “ViewShark” strings; align to “EasyStream”.
- [ ] Verify CSRF on all POST routes; add where missing.
- [ ] Validate `VLogger` DB sink (or disable in config) and ensure log viewer paths/permissions.
---
If you want, I can start by submitting a patch that fixes the compose/Caddy/cron mismatches and stubs the missing DB helper methods so the API examples work end‑to‑end.