HTTP Class Technical Documentation (diff)

Difference between revisions for Users / Eo Ny / 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 ====

Private 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 ( 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:

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

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

(hl php)<!~~markup:2:end~~> $http->session(); // 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:**

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

---- ===== ##store_cache(): void## ===== =====##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**

PHP

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

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

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

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

php<!~~markup:1:end~~>**

PHP

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

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

(hl 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 ##'...'## 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~~>**

PHP

<!--markup:2:end-->
$client_ip = $http->ip;  // e.g., "23..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 =====~~
<!~~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:

- 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 31 (permanent) vs 32 (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);  // 31
$http->redirect('/wiki/HomePage');                       // 32

`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

2 => 'OK'
26 => 'Partial Content'
31 => 'Moved Permanently'
32 => 'Moved Temporarily'
34 => 'Not Modified'
4 => 'Bad Request'
41 => 'Unauthorized'
43 => 'Forbidden'
44 => 'Not Found'
45 => 'Method Not Allowed'
49 => 'Conflict'
41 => 'Gone'
416 => 'Requested Range Not Satisfiable'
5 => 'Internal Server Error'
51 => 'Not Implemented'
53 => 'Service Unavailable'

Example:

PHP

$http->status(44);  // Send 44 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** 

(hl php)<!~~markup:2:end~~> $http->cache_promisc();

---- ==== Language Negotiation ==== ===== ##user_agent_language(): string## ===== Determines best language based on browser preferences. **Features:** - Follows RFC 911 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=.9,de;q=.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:**

(hl 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**

PHP

<!--markup:2:end-->
$http->sendfile(44);  // Serves file defined by HTTP_44 constant
$http->sendfile(43);  // Serves file defined by HTTP_43 constant

Example:
<!~~markup:1:begin~~>

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

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

----

===== ##mime_type($path): string## =====
Returns MIME type for a file.

**Returns:**
  - MIME type string (e.g., 'application/pdf')
  - Default: ##'application/octet-stream'##

**Example:**

(hl 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:
  - 86 bytes < content < 1 MB
  - Client accepts compression
  - Headers not already sent

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

php<!~~markup:1:end~~>**

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)
$data = $http->parse_str('name=John&age=3');

----

===== ##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, =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 (/1/2) ||
|| ##permissions_policy## | int | Permissions-Policy setting (/1/2) ||
|| ##referrer_policy## | int | Referrer-Policy setting (-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 directory ||
|| ##LANG_DIR## | string | Language files directory ||
|| ##DAYSECS## | int | Seconds in a day (864) ||
|| ##HTTP_44## | string | Path to 44 error page ||
|| ##HTTP_43## | string | Path to 43 error page ||
|#

----

=== Workflow Examples ===

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

php<!~~markup:1:end~~> Request====

PHP

<!--markup:2:end-->
// In main wiki entry point
$http = new Http($db);
$http->session();  // 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

<!~~markup:1:begin~~>

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

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

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

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

----

=== 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 (34 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:1:end~~>

<!~~markup:2: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 224-1-15 12:3:45 GMT -->

Version History

Supports PHP 8.+ (uses match expressions, union types)
Follows RFC 911 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

SQLite Testing

Difference between revisions for Users / Eo Ny / dev

Overview

Class Properties

Private Properties

Private Properties

Constructor

Core Methods

Session Management

`session($route): void`

`invalidate_page($page): int`

`ensure_tls($url): void`

HTTPS Detection

`tls_session(): bool` (Private)

Security Headers

HTTP Methods

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

`terminate(): void`

`status($code): void`

Caching Control

`no_cache($client_only = true): void`

`cache_promisc(): void`

Utility Methods

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

Example 2: Handling TLS/HTTPS Upgrade

Example 3: Invalidating Cache After Page Edit

Example 4: Serving a File

Related Classes

Version History

Conclusion

Difference between revisions for Users / Eo Ny / dev

Overview

Class Properties

Private Properties

Private Properties

Constructor

Core Methods

Session Management

session($route): void

invalidate_page($page): int

ensure_tls($url): void

HTTPS Detection

tls_session(): bool (Private)

Security Headers

HTTP Methods

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

terminate(): void

status($code): void

Caching Control

no_cache($client_only = true): void

cache_promisc(): void

Utility Methods

parse_str($str): array (Private)

Example 2: Handling TLS/HTTPS Upgrade

Example 3: Invalidating Cache After Page Edit

Example 4: Serving a File

Related Classes

Version History

Conclusion

`session($route): void`

`invalidate_page($page): int`

`ensure_tls($url): void`

`tls_session(): bool` (Private)

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

`terminate(): void`

`status($code): void`

`no_cache($client_only = true): void`

`cache_promisc(): void`

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