This is an old revision of Users/EoNy/dev from 05/18/2026 05:05 edited by WikiAdmin.

dev

1. Overview

2. Class Properties

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)

2.1. Public Properties

2.2. Private 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

3. Constructor

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)

4. Core Methods

PHP

public function __construct(&$db)

Purpose: Initializes the Http object and sets up HTTP session handling.

Parameters:

$db - Database object reference

Initialization Steps:

Stores database reference
Extracts and normalizes REQUEST_URI
Detects TLS/HTTPS session status
Determines client's real IP address
Sets up TLS mark cookie name
Enforces TLS session upgrade if needed

Example:

PHP

$http = new Http($db);

4.1. Session Management

4.1.1. `session($route): void`

4.2. Caching System

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

4.2.1. `check_cache($page, $method): void`

4.2.2. `store_cache(): 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');

4.2.3. `invalidate_page($page): int`

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();

4.3. TLS/HTTPS Security

Invalidates all cached versions of a page.

Parameters:

$page (string) - Page name to invalidate

Returns:

Number of cache entries invalidated

Process:

Finds all cached versions (different methods/languages)
Touches files to past timestamp (faster than deletion)
Removes entries from cache metadata table
Returns count of invalidated caches

Example:

PHP

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

4.3.1. `secure_base_url(): void`

4.3.2. `ensure_tls($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://

4.4. IP Address Detection

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');

4.4.1. `real_ip(): string` (Private)

4.5. HTTPS Detection

Detects client's real IP address accounting for proxies.

Proxy Headers Checked (in order):

HTTP_X_CLUSTER_CLIENT_IP
HTTP_X_FORWARDED_FOR (or custom header)
HTTP_CLIENT_IP
HTTP_X_REMOTE_ADDR
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"

4.5.1. `tls_session(): bool` (Private)

4.6. Security Headers

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

4.6.1. `http_security_headers(): void`

4.7. HTTP Methods

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();

4.7.1. `redirect($url, $permanent = false): void`

4.7.2. `terminate(): 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

4.7.3. `status($code): void`

Safe exit/die with cleanup.

Cleanup Operations:

Saves diagnostic logs to session flash data
Ends script execution

Example:

PHP

$http->terminate();

4.8. Caching Control

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

4.8.1. `no_cache($client_only = true): void`

4.8.2. `cache_promisc(): 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

4.9. Language Negotiation

Marks page as publicly cacheable.

Headers Set:

Cache-Control: public

Example:

PHP

$http->cache_promisc();

4.9.1. `user_agent_language(): string`

4.9.2. `available_languages($subset = true): array`

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')

4.10. File Serving

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);

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

4.10.2. `mime_type($path): string`

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);

4.10.3. `mime_types(): array` (Private)

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'

4.11. Compression

Loads and caches MIME types from configuration.

Features:

Reads from config/mime.types
Caches to cache/config/mime.types
Reloads if config is updated

4.11.1. `gzip(): void`

4.12. Utility Methods

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();

4.12.1. `parse_str($str): array` (Private)

4.12.2. `request_uri(): string` (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');

4.12.3. `cut_prefix($prefix, $path): 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

4.12.4. `get_header_conf($file_name): string` (Private)

Removes prefix from path (case-insensitive).

5. Configuration Dependencies

Loads security header configuration from files.

Files Supported:

csp.conf / csp_custom.conf
permissions_policy.conf / permissions_policy_custom.conf

6. Constants Used

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)

7. Workflow Examples

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

7.1. Example 1: Handling a GET Request

7.2. Example 2: Handling TLS/HTTPS Upgrade

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();

7.3. Example 3: Invalidating Cache After Page Edit

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

7.4. Example 4: Serving a File

PHP

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

8. Security Considerations

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);

8.1. 1. IP Address Spoofing

8.2. 2. Session Security

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

8.3. 3. TLS Enforcement

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

8.4. 4. Content Security

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

8.5. 5. File Serving

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

8.6. 6. Cache Security

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

9. Performance Optimization

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

9.1. 1. Page Caching

9.2. 2. MIME Type Caching

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

9.3. 3. Session Options

Loads MIME types once and caches
Regenerates only when config changes

9.4. 4. Compression

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

10. Debugging

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

11. Related Classes

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 -->

12. Version History

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

13. Conclusion

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

dev

1. Overview

2. Class Properties

2.1. Public Properties

2.2. Private Properties

3. Constructor

4. Core Methods

4.1. Session Management

4.1.1. session($route): void

4.2. Caching System

4.2.1. check_cache($page, $method): void

4.2.2. store_cache(): void

4.2.3. invalidate_page($page): int

4.3. TLS/HTTPS Security

4.3.1. secure_base_url(): void

4.3.2. ensure_tls($url): void

4.4. IP Address Detection

4.4.1. real_ip(): string (Private)

4.5. HTTPS Detection

4.5.1. tls_session(): bool (Private)

4.6. Security Headers

4.6.1. http_security_headers(): void

4.7. HTTP Methods

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

4.7.2. terminate(): void

4.7.3. status($code): void

4.8. Caching Control

4.8.1. no_cache($client_only = true): void

4.8.2. cache_promisc(): void

4.9. Language Negotiation

4.9.1. user_agent_language(): string

4.9.2. available_languages($subset = true): array

4.10. File Serving

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

4.10.2. mime_type($path): string

4.10.3. mime_types(): array (Private)

4.11. Compression

4.11.1. gzip(): void

4.12. Utility Methods

4.12.1. parse_str($str): array (Private)

4.12.2. request_uri(): string (Private)

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

4.12.4. get_header_conf($file_name): string (Private)

5. Configuration Dependencies

6. Constants Used

7. Workflow Examples

7.1. Example 1: Handling a GET Request

7.2. Example 2: Handling TLS/HTTPS Upgrade

7.3. Example 3: Invalidating Cache After Page Edit

7.4. Example 4: Serving a File

8. Security Considerations

8.1. 1. IP Address Spoofing

8.2. 2. Session Security

8.3. 3. TLS Enforcement

8.4. 4. Content Security

8.5. 5. File Serving

8.6. 6. Cache Security

9. Performance Optimization

9.1. 1. Page Caching

9.2. 2. MIME Type Caching

9.3. 3. Session Options

9.4. 4. Compression

10. Debugging

11. Related Classes

12. Version History

13. Conclusion

Conclusion

4.1.1. `session($route): void`

4.2.1. `check_cache($page, $method): void`

4.2.2. `store_cache(): void`

4.2.3. `invalidate_page($page): int`

4.3.1. `secure_base_url(): void`

4.3.2. `ensure_tls($url): void`

4.4.1. `real_ip(): string` (Private)

4.5.1. `tls_session(): bool` (Private)

4.6.1. `http_security_headers(): void`

4.7.1. `redirect($url, $permanent = false): void`

4.7.2. `terminate(): void`

4.7.3. `status($code): void`

4.8.1. `no_cache($client_only = true): void`

4.8.2. `cache_promisc(): void`

4.9.1. `user_agent_language(): string`

4.9.2. `available_languages($subset = true): array`

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

4.10.2. `mime_type($path): string`

4.10.3. `mime_types(): array` (Private)

4.11.1. `gzip(): void`

4.12.1. `parse_str($str): array` (Private)

4.12.2. `request_uri(): string` (Private)

4.12.3. `cut_prefix($prefix, $path): string` (Private)

4.12.4. `get_header_conf($file_name): string` (Private)