SQLite Testing: dev

https://wackowiki.org/test     Version: 1 (05/05/2026 19:06)
This is an old revision of Users/EoNy/dev from 05/05/2026 19:06 edited by EoNy.

dev

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


Property Type Description
$tls_session bool Indicates if the current session uses HTTPS/TLS encryption
$request_uri string Normalized REQUEST_URI (e.g., 'PageOfNoReturn/show?a=1')
$ip string Client's real IP address (accounts for proxies)
$sess Session Reference to the Session object
$method string Current HTTP method/request type

Private Properties

Property Type Description
$db object Database connection reference
$tls_mark string Cookie name for TLS session marking
$page string Current page name being processed
$hash string SHA1 hash of the page name
$query string Encoded query string
$lang string Current language code
$file string Cache file path
$caching int Flag indicating if page should be cached (0 or 1)

Constructor 

php
public function __construct(&$db)
Purpose: Initializes the Http object and sets up HTTP session handling.
Parameters:
- $db - Database object reference
Initialization Steps:
1. Stores database reference
2. Extracts and normalizes REQUEST_URI
3. Detects TLS/HTTPS session status
4. Determines client's real IP address
5. Sets up TLS mark cookie name
6. Enforces TLS session upgrade if needed
Example: 
php
$http = new Http($db);

Core Methods

Session Management

session($route): void

Initializes the session handler (file-based or database-based).
Parameters:
- $route (int) - Routing flag:
- Bit 2 ($route & 2): Enable static mode for files/freecap (disables replay prevention and ID regeneration)
Features:
- Selects storage backend (file or database)
- Configures cookie settings (security, path, httponly)
- Binds IP and TLS validation
- Recovers diagnostic logs from previous session
Example: 
php
$http->session(0);  // Normal session
$http->session(2);  // Static file serving mode

Caching System

check_cache($page, $method): void

Determines if a page can be cached and prepares the cache check.
Parameters:
- $page (string) - Page name to cache
- $method (string) - Request method/action (e.g., 'show', 'edit')
Caching Rules:
- ✅ Enabled for GET requests only
- ✅ Disabled for POST requests
- ❌ Never cached for 'edit' or 'watch' methods
- ✅ Only cached for anonymous users (no logged-in users)
Example: 
php
$http->check_cache('HomePage', 'show');

store_cache(): void

Saves the generated page content to cache file.
Features:
- Retrieves output buffer content
- Saves to cache file with proper permissions
- Records cache metadata in database
- Only executes if caching flag is set and user is anonymous
Example: 
php
// Called at end of page rendering
$http->store_cache();

invalidate_page($page): int

Invalidates all cached versions of a page.
Parameters:
- $page (string) - Page name to invalidate
Returns:
- Number of cache entries invalidated
Process:
1. Finds all cached versions (different methods/languages)
2. Touches files to past timestamp (faster than deletion)
3. Removes entries from cache metadata table
4. Returns count of invalidated caches
Example: 
php
$count = $http->invalidate_page('HomePage');
echo "Invalidated $count cache entries";

TLS/HTTPS Security

secure_base_url(): void

Switches base URL from HTTP to HTTPS.
Purpose:
- Ensures all subsequent URLs use HTTPS
- Stores original HTTP URL for fallback
- Called when TLS session is detected
Example: 
php
$http->secure_base_url();
// $db->base_url now uses https://

ensure_tls($url): void

Enforces HTTPS for a specific URL and redirects if necessary.
Parameters:
- $url (string) - URL to secure
Behavior:
- If not already HTTPS and TLS is enabled, forces HTTPS redirect
- Handles both relative and absolute URLs
- Converts relative URLs using current server name
Example: 
php
$http->ensure_tls('/secure/payment');

IP Address Detection

real_ip(): string (Private)

Detects client's real IP address accounting for proxies.
Proxy Headers Checked (in order):
1. HTTP_X_CLUSTER_CLIENT_IP
2. HTTP_X_FORWARDED_FOR (or custom header)
3. HTTP_CLIENT_IP
4. HTTP_X_REMOTE_ADDR
5. REMOTE_ADDR (fallback)
Features:
- Filters out private/reserved IP ranges
- Respects configured reverse proxy addresses
- Returns '0.0.0.0' as fallback
Configuration in Database:
- reverse_proxy_addresses - Comma/space-separated proxy IPs
- reverse_proxy_header - Custom header name (default: X-Forwarded-For)
Example: 
php
$client_ip = $http->ip;  // e.g., "203.0.113.42"

HTTPS Detection

tls_session(): bool (Private)

Detects if current connection uses HTTPS/TLS.
Checks (any being true = HTTPS):
- $_SERVER['HTTPS'] is 'on'
- $_SERVER['SERVER_PORT'] is 443
- $_SERVER['HTTP_X_FORWARDED_PROTO'] is 'https'
- $_SERVER['HTTP_X_FORWARDED_SSL'] is 'on'
- $_SERVER['HTTP_X_FORWARDED_PORT'] is 443

Security Headers

http_security_headers(): void

Sets security-related HTTP headers.
Headers Set:
Header Purpose Config Key
Content-Security-Policy XSS/injection protection csp
Permissions-Policy Control browser features permissions_policy
Referrer-Policy Control referrer information referrer_policy
Strict-Transport-Security Force HTTPS Auto (TLS only)
X-Frame-Options Clickjacking protection Hardcoded: SAMEORIGIN
X-Content-Type-Options MIME sniffing prevention Hardcoded: nosniff
CSP Configuration Options:
- 0 - Disabled
- 1 - Default policy (from csp.conf)
- 2 - Custom policy (from csp_custom.conf)
Example: 
php
$http->http_security_headers();

HTTP Methods

redirect($url, $permanent = false): void

Performs an HTTP redirect.
Parameters:
- $url (string) - Target URL
- $permanent (bool) - Use 301 (permanent) vs 302 (temporary)
Features:
- Decodes & entities to prevent broken redirects
- Only works if headers not yet sent
- Uses output buffering to work anywhere in page processing
Example: 
php
$http->redirect('http://example.com/new-page', true);  // 301
$http->redirect('/wiki/HomePage');                       // 302

terminate(): void

Safe exit/die with cleanup.
Cleanup Operations:
- Saves diagnostic logs to session flash data
- Ends script execution
Example: 
php
$http->terminate();

status($code): void

Sets HTTP response status code.
Supported Status Codes: 
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'
Example: 
php
$http->status(404);  // Send 404 Not Found

Caching Control

no_cache($client_only = true): void

Disables caching of the current page.
Parameters:
- $client_only (bool, default: TRUE)
- TRUE: Disable browser cache only
- FALSE: Disable both browser and server cache
Headers Set:
- Last-Modified: <current-time> (always fresh)
- Cache-Control: no-store
Example: 
php
$http->no_cache();        // Client-side only
$http->no_cache(false);   // Both client & server

cache_promisc(): void

Marks page as publicly cacheable.
Headers Set:
- Cache-Control: public
Example: 
php
$http->cache_promisc();

Language Negotiation

user_agent_language(): string

Determines best language based on browser preferences.
Features:
- Follows RFC 9110 section 12.5.4 (HTTP Accept-Language)
- Parses Accept-Language header with quality factors
- Attempts exact match first, then language fallback
- Falls back to default system language
Example Header: 
Accept-Language: en-US,en;q=0.9,de;q=0.8
Returns:
- Language code (e.g., 'en', 'en-US', 'de')

available_languages($subset = true): array

Returns list of available language translations.
Parameters:
- $subset (bool, default: TRUE)
- TRUE: Only allowed languages
- FALSE: All available languages
Features:
- Scans LANG_DIR for language files
- Filters by allowed_languages config if set
- Caches result in session
- System language always included
Returns:
- Associative array: ['en' => 'en', 'de' => 'de', ...]
Example: 
php
$all_langs = $http->available_languages(false);
$allowed = $http->available_languages(true);

File Serving

sendfile($path, $filename = null, $age = null): void

Serves files with proper HTTP headers and caching.
Parameters:
- $path (string) - File path (or HTTP_XXX constant for error pages)
- $filename (string, optional) - Custom download filename
- $age (int, optional) - Cache age in days
Features:
- HTTP range request support (partial file downloads)
- ETag and Last-Modified conditional requests
- Proper MIME type detection
- Content-Security-Policy for special file types
- Streaming for large files
- GZip compression for text files
Special Paths: 
php
$http->sendfile(404);  // Serves file defined by HTTP_404 constant
$http->sendfile(403);  // Serves file defined by HTTP_403 constant
Example: 
php
$http->sendfile('uploads/document.pdf', 'my-document.pdf', 30);

mime_type($path): string

Returns MIME type for a file.
Returns:
- MIME type string (e.g., 'application/pdf')
- Default: 'application/octet-stream'
Example: 
php
$mime = $http->mime_type('file.pdf');  // 'application/pdf'

mime_types(): array (Private)

Loads and caches MIME types from configuration.
Features:
- Reads from config/mime.types
- Caches to cache/config/mime.types
- Reloads if config is updated

Compression

gzip(): void

Compresses HTTP response with gzip/x-gzip.
Features:
- Manually implements gzip (not relying on zlib.output_compression)
- Produces correct Content-Length header
- Only compresses if:
- 860 bytes < content < 1 MB
- Client accepts compression
- Headers not already sent
Example: 
php
$http->gzip();

Utility Methods

parse_str($str): array (Private)

Parses URL-encoded strings with special character handling.
Purpose:
- Safely handles special characters in query/form data
- Converts encoding properly
Example: 
php
$data = $http->parse_str('name=John&age=30');

request_uri(): string (Private)

Extracts and normalizes REQUEST_URI from server.
Normalization:
- Removes base URL prefix
- Removes spaces
- Collapses multiple slashes
- Removes .. path traversal attempts
- Removes leading/trailing slashes

cut_prefix($prefix, $path): string (Private)

Removes prefix from path (case-insensitive).

get_header_conf($file_name): string (Private)

Loads security header configuration from files.
Files Supported:
- csp.conf / csp_custom.conf
- permissions_policy.conf / permissions_policy_custom.conf

Configuration Dependencies

The class relies on these database configuration settings:
Setting Type Purpose
base_url string Wiki's base URL
tls bool Enable HTTPS enforcement
cache bool Enable page caching
cache_ttl int Cache lifetime in seconds
session_store int 1=File, 0=Database
system_seed_hash string Session encryption seed
cookie_prefix string Session cookie prefix
cookie_path string Cookie path
allow_persistent_cookie bool Allow persistent login
session_length int Session lifetime in seconds
reverse_proxy_addresses string Comma/space-separated proxy IPs
reverse_proxy_header string Custom X-Forwarded header
language string Default language code
multilanguage bool Enable language negotiation
allowed_languages string Comma/space-separated allowed langs
enable_security_headers bool Send security headers
csp int CSP setting (0/1/2)
permissions_policy int Permissions-Policy setting (0/1/2)
referrer_policy int Referrer-Policy setting (0-8)

Constants Used

Constant Type Purpose
IN_WACKO bool Security check (exit if not defined)
CHMOD_SAFE int File permissions for cache files
CHMOD_FILE int File permissions for config cache
CACHE_PAGE_DIR string Page cache directory
CACHE_SESSION_DIR string Session cache directory
CACHE_CONFIG_DIR string Config cache directory
CONFIG_DIR string Configuration directory
LANG_DIR string Language files directory
DAYSECS int Seconds in a day (86400)
HTTP_404 string Path to 404 error page
HTTP_403 string Path to 403 error page

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

2. Session Security

3. TLS Enforcement

4. Content Security

5. File Serving

6. Cache Security


Performance Optimization

1. Page Caching

2. MIME Type Caching

3. Session Options

4. Compression


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


Version History


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: