Difference between revisions for Users / Eo Ny / dev

• Detailed
• Simple
• Source
• Side by side
• Inline
• Merged

HTTP Class Technical Documentation

Overview

Class Properties

Constructor

php<!--markup:1:end-->

<!--markup:2:begin-->	

**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:**
<!--markup:1:begin-->	

PHP

<!--markup:2:end-->
$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:
<!markup:1:begin>

php<!--markup:1:end-->**
<!--markup:2:begin-->	

(hl php)

----

==== 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:**
<!--markup:1:begin-->	

PHP

<!--markup:2:end-->
$http->check_cache('HomePage', 'show');

---

===== store_cache(): void =====
<!markup:2:begin>=====store_cache(): void=====

• 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

php<!--markup:1:end-->**
<!--markup:2:begin-->	

----

===== ##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:**
<!--markup:1:begin-->	

PHP

<!--markup:2:end-->
$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:
<!markup:1:begin>

php<!--markup:1:end-->**
<!--markup:2:begin-->	

(hl php)

----

===== ##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:**
<!--markup:1:begin-->	

PHP

<!--markup:2:end-->
$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:
<!markup:1:begin>

php<!--markup:1:end-->**
<!--markup:2:begin-->	

(hl php)

----

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

<!--markup:1:begin-->===== ##http_security_headers(): void## =====<!--markup:1:end-->

<!--markup:2:begin-->=====##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:**	

----<!--markup:2:end-->
==== 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 ##&amp;## entities to prevent broken redirects
  - Only works if headers not yet sent
  - Uses output buffering to work anywhere in page processing

**Example:**
<!--markup:1:begin-->	

PHP

<!--markup:2:end-->
$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:
<!markup:1:begin>

php<!--markup:1:end-->**
<!--markup:2:begin-->	

(hl php)

----

===== ##status($code): void## =====
Sets HTTP response status code.

**Supported Status Codes:**
<!--markup:1:begin-->	

PHP

<!--markup:2:end-->
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:
<!markup:1:begin>

php<!--markup:1:end-->**
<!--markup:2:begin-->	

(hl php)

----

==== 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:**
<!--markup:1:begin-->	

PHP

<!--markup:2:end-->
$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:
<!markup:1:begin>

php<!--markup:1:end-->**
<!--markup:2:begin-->	

(hl php)

----

==== 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:**	

**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:**
<!--markup:1:begin-->	

PHP

<!--markup:2:end-->
$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:
<!markup:1:begin>

php<!--markup:1:end-->**
<!--markup:2:begin-->	

(hl php)

**Example:**
<!--markup:1:begin-->	

PHP

<!--markup:2:end-->
$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:
<!markup:1:begin>

php<!--markup:1:end-->**
<!--markup:2:begin-->	

(hl php)

----

===== ##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:**
<!--markup:1:begin-->	

PHP

<!--markup:2:end-->
$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:
<!markup:1:begin>

php<!--markup:1:end-->**
<!--markup:2:begin-->	

(hl php)

----

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

----

<!--markup:1:begin-->===<!--markup:1:end-->

<!--markup:2:begin-->===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 |<!--markup:2:end--> Configuration <!--markup:1:begin-->Dependencies ===



=== Constants Used ===<!--markup:1:end--> <!--markup:2:begin-->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 ||
|#

----<!--markup:2:end-->

=== Workflow Examples ===

<!--markup:1:begin-->==== Example<!--markup:1:end-->

<!--markup:2:begin-->====Example<!--markup:2:end--> 1: Handling a GET <!--markup:1:begin-->Request ====	

Request====

PHP

<!--markup:2:end-->
// 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

<!markup:1:begin>

php<!--markup:1:end-->

<!--markup:2:begin-->	

(hl php)

==== Example 3: Invalidating Cache After Page Edit ====

<!--markup:1:begin-->	

PHP

<!--markup:2:end-->
// 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

<!markup:1:begin>

php<!--markup:1:end-->

<!--markup:2:begin-->	

(hl php)

----

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

<!--markup:1:begin-->	

PHP

<!--markup:2:end-->
// 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

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