HTTP Class Technical Documentation

Overview

The Http class (src/class/http.php) is a core component of the WackoWiki system responsible for handling HTTP request/response processing, session management, caching, and security features. This class acts as a bridge between the web server and the wiki engine.

File Location: src/class/http.php
Language: PHP
Dependencies: Database class, Session classes, Utility classes (Ut), Diagnostics class (Diag)

Class Properties

Public Properties

php
public function __construct(&$db)	

php
$http = new Http($db);	

php
$http->session(0);  // Normal session
$http->session(2);  // Static file serving mode	

php
$http->check_cache('HomePage', 'show');	

php
// Called at end of page rendering
$http->store_cache();	

php
$count = $http->invalidate_page('HomePage');
echo "Invalidated $count cache entries";	

php
$http->secure_base_url();
// $db->base_url now uses https://	

php
$http->ensure_tls('/secure/payment');	

php
$client_ip = $http->ip;  // e.g., "203.0.113.42"	

php
$http->http_security_headers();	

php
$http->redirect('http://example.com/new-page', true);  // 301
$http->redirect('/wiki/HomePage');                       // 302	

php
$http->terminate();	

php
200 => 'OK'
206 => 'Partial Content'
301 => 'Moved Permanently'
302 => 'Moved Temporarily'
304 => 'Not Modified'
400 => 'Bad Request'
401 => 'Unauthorized'
403 => 'Forbidden'
404 => 'Not Found'
405 => 'Method Not Allowed'
409 => 'Conflict'
410 => 'Gone'
416 => 'Requested Range Not Satisfiable'
500 => 'Internal Server Error'
501 => 'Not Implemented'
503 => 'Service Unavailable'	

php
$http->status(404);  // Send 404 Not Found	

php
$http->no_cache();        // Client-side only
$http->no_cache(false);   // Both client & server	

php
$http->cache_promisc();	

Accept-Language: en-US,en;q=0.9,de;q=0.8	

php
$all_langs = $http->available_languages(false);
$allowed = $http->available_languages(true);	

php
$http->sendfile(404);  // Serves file defined by HTTP_404 constant
$http->sendfile(403);  // Serves file defined by HTTP_403 constant	

php
$http->sendfile('uploads/document.pdf', 'my-document.pdf', 30);	

php
$mime = $http->mime_type('file.pdf');  // 'application/pdf'	

php
$http->gzip();	

php
$data = $http->parse_str('name=John&age=30');	

Workflow Examples

Example 1: Handling a GET Request

php
// In main wiki entry point
$http = new Http($db);
$http->session(0);  // Start session

// Check if page can be served from cache
$http->check_cache('HomePage', 'show');

// ... render page content ...

// Store rendered page in cache if applicable
$http->store_cache();

// Send security headers
$http->http_security_headers();

// Possibly compress output
$http->gzip();	

Example 2: Handling TLS/HTTPS Upgrade

php
$http = new Http($db);  // Constructor detects TLS requirement
// If TLS is enabled and user wasn't in TLS before:
// - Sets TLS session flag
// - Marks session with TLS cookie
// - Redirects to HTTPS version	

Example 3: Invalidating Cache After Page Edit

php
// User edits a page
$http = new Http($db);
$count = $http->invalidate_page('HomePage');
// All cached versions (different languages, methods) are invalidated	

Example 4: Serving a File

php
$http = new Http($db);
$http->session(2);  // Static file mode - no session replay prevention

// Serve with 30-day cache
$http->sendfile('uploads/manual.pdf', 'user-manual.pdf', 30);	

Security Considerations

1. IP Address Spoofing

• Validates IPs against private ranges
• Filters proxy-provided IPs appropriately
• Configurable reverse proxy trust

2. Session Security

• Binds sessions to IP address
• Binds sessions to TLS status
• Supports both file and database storage
• HttpOnly cookies by default

3. TLS Enforcement

• Automatic HTTPS upgrade when configured
• Marks TLS sessions to prevent downgrade attacks
• HSTS header support

4. Content Security

• CSP headers to prevent XSS
• X-Frame-Options to prevent clickjacking
• X-Content-Type-Options to prevent MIME sniffing
• Referrer-Policy control
• Permissions-Policy for browser features

5. File Serving

• Validates file existence and readability
• Prevents directory traversal via realpath()
• Rejects symbolic links
• Special CSP for SVG and PDF files

6. Cache Security

• Cached only for anonymous users
• Disabled for sensitive operations (edit, watch)
• Only GET requests cached

Performance Optimization

1. Page Caching

• Stores full HTML output
• TTL-based expiration
• Language and method-aware caching
• Conditional request support (304 Not Modified)

2. MIME Type Caching

• Loads MIME types once and caches
• Regenerates only when config changes

3. Session Options

• File-based sessions for simple deployments
• Database sessions for distributed systems

4. Compression

• Manual gzip implementation
• Proper Content-Length generation
• Only compresses appropriate sizes

Debugging

The class integrates with WackoWiki's diagnostic system:

php
// Diagnostic messages are preserved across redirects
// via session flash data

// Check cached pages (debug comments in output):
// <!-- WackoWiki Caching Engine: page cached at 2024-01-15 12:30:45 GMT -->	

Related Classes

• Session Classes (SessionFileStore, SessionDbalStore) - Session management backends
• Database Class - Configuration and cache metadata storage
• Ut Utility Class - String/path utilities
• Diag Class - Diagnostic logging

Version History

• Supports PHP 8.0+ (uses match expressions, union types)
• Follows RFC 9110 for HTTP header handling
• Modern cookie security practices

Conclusion

The Http class is the central request/response handler in WackoWiki, managing everything from session initialization to security headers to file serving. Understanding this class is essential for:

• Extending WackoWiki with custom request handlers
• Implementing custom session logic
• Adding new security policies
• Optimizing cache strategies
• Debugging HTTP-related issues