Difference between revisions for Users / Eo Ny / dev




← Previous edit
Revision 3 as of 05/05/2026 19:10 ▼
6 05/05/2026 19:21 EoNy 5 05/05/2026 19:11 EoNy 4 05/05/2026 19:10 EoNy 3 05/05/2026 19:10 EoNy 2 05/05/2026 19:08 EoNy 1 05/05/2026 19:06 EoNy

(17.4 KiB)
EoNy
 Next edit →
Revision 7 as of 05/05/2026 19:23 ▼
18 05/21/2026 16:12 WikiAdmin 17 05/18/2026 15:15 WikiAdmin 16 05/18/2026 05:05 WikiAdmin 15 05/18/2026 05:04 WikiAdmin 14 05/17/2026 21:10 WikiAdmin 13 05/05/2026 19:29 EoNy 12 05/05/2026 19:28 WikiAdmin 11 05/05/2026 19:28 WikiAdmin 10 05/05/2026 19:27 WikiAdmin 9 05/05/2026 19:25 WikiAdmin 8 05/05/2026 19:24 WikiAdmin 7 05/05/2026 19:23 WikiAdmin 6 05/05/2026 19:21 EoNy 5 05/05/2026 19:11 EoNy 4 05/05/2026 19:10 EoNy

(14.8 KiB) -2,646
WikiAdmin

#== HTTP Class Technical Documentation
## ==
=== Overview ===
The `Http` Http class (`src/class/http.php`) (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`** src/class/http.php Language: PHP
Dependencies: Database class, Session classes, Utility classes (`Ut`), (Ut), Diagnostics class (`Diag`)

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

%%php<!--markup:2:end-->
public function __construct(&$db)
<!--markup:1:begin-->
` 
<!--markup:2:end-->

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

**Parameters:**
  - <!--markup:1:begin-->`$db`<!--markup:1:end--> <!--markup:2:begin-->##$db##<!--markup:2:end--> - 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:1:end-->**
<!--markup:2:begin-->
php $http = new Http($db);
`

---

##<!--markup:1:end-->
<!--markup:2:begin-->%%

----

===<!--markup:2:end--> Core Methods

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

====<!--markup:2:end--> Session Management

<!--markup:1:begin-->#### `session($route): void`<!--markup:1:end--> <!--markup:2:begin-->====

===== ##session($route): void## =====<!--markup:2:end-->
Initializes the session handler (file-based or database-based).

**Parameters:**
  - <!--markup:1:begin-->`$route`<!--markup:1:end--> <!--markup:2:begin-->##$route##<!--markup:2:end--> (int) - Routing flag:
  - Bit 2 <!--markup:1:begin-->(`$route<!--markup:1:end--> <!--markup:2:begin-->(##$route<!--markup:2:end--> & <!--markup:1:begin-->2`):<!--markup:1:end--> <!--markup:2:begin-->2##):<!--markup:2:end--> 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** 
php<!--markup:2:end-->
$http->session(0);  // Normal session
$http->session(2);  // Static file serving mode
<!--markup:1:begin-->```

---

###<!--markup:1:end-->
<!--markup:2:begin-->

Caching System
`check_cache($page, ====

##check_cache($page, $method): void` void## ===== Determines if a page can be cached and prepares the cache check.

Parameters:
  • `$page` $page (string) - Page name to cache
  • `$method` $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<!--markup:1:end-->**
<!--markup:2:begin-->%%php<!--markup:2:end-->
$http->check_cache('HomePage', 'show');
<!--markup:1:begin-->
`

`store_cache(): void`
----

===== ##store_cache(): void## =====<!--markup:2:end-->
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:**
<!--markup:1:begin-->```php<!--markup:1:end-->**
<!--markup:2:begin-->
php // Called at end of page rendering
$http->store_cache();
`

---

#### `invalidate_page($page): int`<!--markup:1:end-->
<!--markup:2:begin-->%%

----

===== ##invalidate_page($page): int## =====<!--markup:2:end-->
Invalidates all cached versions of a page.

**Parameters:**
  - <!--markup:1:begin-->`$page`<!--markup:1:end--> <!--markup:2:begin-->##$page##<!--markup:2:end--> (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** 
php<!--markup:2:end-->
$count = $http->invalidate_page('HomePage');
echo "Invalidated $count cache entries";
<!--markup:1:begin-->```

---

###<!--markup:1:end-->
<!--markup:2:begin-->

TLS/HTTPS Security
`secure_base_url(): void` ====

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<!--markup:1:end-->**
<!--markup:2:begin-->%%php<!--markup:2:end-->
$http->secure_base_url();
// $db->base_url now uses https://
<!--markup:1:begin-->
`

`ensure_tls($url): void`
----

===== ##ensure_tls($url): void## =====<!--markup:2:end-->
Enforces HTTPS for a specific URL and redirects if necessary.

**Parameters:**
  - <!--markup:1:begin-->`$url`<!--markup:1:end--> <!--markup:2:begin-->##$url##<!--markup:2:end--> (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-->
php $http->ensure_tls('/secure/payment');
`

---

###<!--markup:1:end-->
<!--markup:2:begin-->%%

----

====<!--markup:2:end--> IP Address Detection

<!--markup:1:begin-->#### `real_ip(): string`<!--markup:1:end--> <!--markup:2:begin-->====

===== ##real_ip(): string##<!--markup:2:end--> (Private) <!--markup:2:begin-->=====<!--markup:2:end-->
Detects client's real IP address accounting for proxies.

**Proxy Headers Checked (in order):**
  1. <!--markup:1:begin-->`HTTP_X_CLUSTER_CLIENT_IP`<!--markup:1:end--> <!--markup:2:begin-->##HTTP_X_CLUSTER_CLIENT_IP##<!--markup:2:end-->
  2. <!--markup:1:begin-->`HTTP_X_FORWARDED_FOR`<!--markup:1:end--> <!--markup:2:begin-->##HTTP_X_FORWARDED_FOR##<!--markup:2:end--> (or custom header)
  3. <!--markup:1:begin-->`HTTP_CLIENT_IP`<!--markup:1:end--> <!--markup:2:begin-->##HTTP_CLIENT_IP##<!--markup:2:end-->
  4. <!--markup:1:begin-->`HTTP_X_REMOTE_ADDR`<!--markup:1:end--> <!--markup:2:begin-->##HTTP_X_REMOTE_ADDR##<!--markup:2:end-->
  5. <!--markup:1:begin-->`REMOTE_ADDR`<!--markup:1:end--> <!--markup:2:begin-->##REMOTE_ADDR##<!--markup:2:end--> (fallback)

**Features:**
  - Filters out private/reserved IP ranges
  - Respects configured reverse proxy addresses
  - Returns <!--markup:1:begin-->`'0.0.0.0'`<!--markup:1:end--> <!--markup:2:begin-->##'0.0.0.0'##<!--markup:2:end--> as fallback

**Configuration in Database:**
  - <!--markup:1:begin-->`reverse_proxy_addresses`<!--markup:1:end--> <!--markup:2:begin-->##reverse_proxy_addresses##<!--markup:2:end--> - Comma/space-separated proxy IPs
  - <!--markup:1:begin-->`reverse_proxy_header`<!--markup:1:end--> <!--markup:2:begin-->##reverse_proxy_header##<!--markup:2:end--> - Custom header name (default: <!--markup:1:begin-->`X-Forwarded-For`)<!--markup:1:end--> <!--markup:2:begin-->##X-Forwarded-For##)<!--markup:2:end-->

**Example:**
<!--markup:1:begin-->
`php** 
php<!--markup:2:end-->
$client_ip = $http->ip;  // e.g., "203.0.113.42"
<!--markup:1:begin-->```

---

###<!--markup:1:end-->
<!--markup:2:begin-->

HTTPS Detection
`tls_session(): bool` ====

tls_session(): bool (Private) ===== Detects if current connection uses HTTPS/TLS.

Checks (any being true = HTTPS):
  • `$_SERVER['HTTPS']` $_SERVER['HTTPS'] is 'on'
  • `$_SERVER['SERVER_PORT']` $_SERVER['SERVER_PORT'] is 443
  • `$_SERVER['HTTP_X_FORWARDED_PROTO']` $_SERVER['HTTP_X_FORWARDED_PROTO'] is 'https'
  • `$_SERVER['HTTP_X_FORWARDED_SSL']` $_SERVER['HTTP_X_FORWARDED_SSL'] is 'on'
  • `$_SERVER['HTTP_X_FORWARDED_PORT']` $_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_security_headers(): void


HTTP Methods
`redirect($url, ====

##redirect($url, $permanent = false): void` void## ===== Performs an HTTP redirect.

Parameters:
  • `$url` $url (string) - Target URL
  • `$permanent` $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<!--markup:1:end-->**
<!--markup:2:begin-->%%php<!--markup:2:end-->
$http->redirect('http://example.com/new-page', true);  // 301
$http->redirect('/wiki/HomePage');                       // 302
<!--markup:1:begin-->
`

`terminate(): void`
----

===== ##terminate(): void## =====<!--markup:2:end-->
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-->
php $http->terminate();
`

---

#### `status($code): void`<!--markup:1:end-->
<!--markup:2:begin-->%%

----

===== ##status($code): void## =====<!--markup:2:end-->
Sets HTTP response status code.

**Supported Status Codes:**
<!--markup:1:begin-->
`php** 
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'
<!--markup:1:begin-->```<!--markup:1:end-->
<!--markup:2:begin-->

Example:
`php<!--markup:1:end-->**
<!--markup:2:begin-->%%php<!--markup:2:end-->
$http->status(404);  // Send 404 Not Found
<!--markup:1:begin-->
`

###
----

====<!--markup:2:end--> Caching Control

<!--markup:1:begin-->#### `no_cache($client_only<!--markup:1:end--> <!--markup:2:begin-->====

===== ##no_cache($client_only<!--markup:2:end--> = true): <!--markup:1:begin-->void`<!--markup:1:end--> <!--markup:2:begin-->void## =====<!--markup:2:end-->
Disables caching of the current page.

**Parameters:**
  - <!--markup:1:begin-->`$client_only`<!--markup:1:end--> <!--markup:2:begin-->##$client_only##<!--markup:2:end--> (bool, default: TRUE)
  - <!--markup:1:begin-->`TRUE`:<!--markup:1:end--> <!--markup:2:begin-->##TRUE##:<!--markup:2:end--> Disable browser cache only
  - <!--markup:1:begin-->`FALSE`:<!--markup:1:end--> <!--markup:2:begin-->##FALSE##:<!--markup:2:end--> Disable both browser and server cache

**Headers Set:**
  - <!--markup:1:begin-->`Last-Modified: <current-time>`<!--markup:1:end--> <!--markup:2:begin-->##Last-Modified: <current-time>##<!--markup:2:end--> (always fresh)
  - <!--markup:1:begin-->`Cache-Control: no-store`<!--markup:1:end--> <!--markup:2:begin-->##Cache-Control: no-store##<!--markup:2:end-->

**Example:**
<!--markup:1:begin-->```php<!--markup:1:end-->**
<!--markup:2:begin-->
php $http->no_cache(); // Client-side only
$http->no_cache(false); // Both client & server
`

---

#### `cache_promisc(): void`<!--markup:1:end-->
<!--markup:2:begin-->%%

----

===== ##cache_promisc(): void## =====<!--markup:2:end-->
Marks page as publicly cacheable.

**Headers Set:**
  - <!--markup:1:begin-->`Cache-Control: public`<!--markup:1:end--> <!--markup:2:begin-->##Cache-Control: public##<!--markup:2:end-->

**Example:**
<!--markup:1:begin-->
`php** 
php<!--markup:2:end-->
$http->cache_promisc();
<!--markup:1:begin-->```

---

###<!--markup:1:end-->
<!--markup:2:begin-->

Language Negotiation
`user_agent_language(): string` ====

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` Accept-Language header with quality factors
  • Attempts exact match first, then language fallback
  • Falls back to default system language

Example Header:
`<!--markup:1:end-->**
<!--markup:2:begin-->%%<!--markup:2:end-->
Accept-Language: en-US,en;q=0.9,de;q=0.8
<!--markup:1:begin-->
` 
<!--markup:2:end-->

**Returns:**
  - Language code (e.g., 'en', 'en-US', 'de')

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

#### `available_languages($subset<!--markup:1:end-->

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

===== ##available_languages($subset<!--markup:2:end--> = true): <!--markup:1:begin-->array`<!--markup:1:end--> <!--markup:2:begin-->array## =====<!--markup:2:end-->
Returns list of available language translations.

**Parameters:**
  - <!--markup:1:begin-->`$subset`<!--markup:1:end--> <!--markup:2:begin-->##$subset##<!--markup:2:end--> (bool, default: TRUE)
  - <!--markup:1:begin-->`TRUE`:<!--markup:1:end--> <!--markup:2:begin-->##TRUE##:<!--markup:2:end--> Only allowed languages
  - <!--markup:1:begin-->`FALSE`:<!--markup:1:end--> <!--markup:2:begin-->##FALSE##:<!--markup:2:end--> All available languages

**Features:**
  - Scans <!--markup:1:begin-->`LANG_DIR`<!--markup:1:end--> <!--markup:2:begin-->##LANG_DIR##<!--markup:2:end--> for language files
  - Filters by <!--markup:1:begin-->`allowed_languages`<!--markup:1:end--> <!--markup:2:begin-->##allowed_languages##<!--markup:2:end--> config if set
  - Caches result in session
  - System language always included

**Returns:**
  - Associative array: <!--markup:1:begin-->`['en'<!--markup:1:end--> <!--markup:2:begin-->##['en'<!--markup:2:end--> => 'en', 'de' => 'de', <!--markup:1:begin-->...]`<!--markup:1:end--> <!--markup:2:begin-->...]##<!--markup:2:end-->

**Example:**
<!--markup:1:begin-->```php<!--markup:1:end-->**
<!--markup:2:begin-->
php $all_langs = $http->available_languages(false);
$allowed = $http->available_languages(true);
`

---

###<!--markup:1:end-->
<!--markup:2:begin-->%%

----

====<!--markup:2:end--> File Serving

<!--markup:1:begin-->#### `sendfile($path,<!--markup:1:end--> <!--markup:2:begin-->====

===== ##sendfile($path,<!--markup:2:end--> $filename = null, $age = null): <!--markup:1:begin-->void`<!--markup:1:end--> <!--markup:2:begin-->void## =====<!--markup:2:end-->
Serves files with proper HTTP headers and caching.

**Parameters:**
  - <!--markup:1:begin-->`$path`<!--markup:1:end--> <!--markup:2:begin-->##$path##<!--markup:2:end--> (string) - File path (or HTTP_XXX constant for error pages)
  - <!--markup:1:begin-->`$filename`<!--markup:1:end--> <!--markup:2:begin-->##$filename##<!--markup:2:end--> (string, optional) - Custom download filename
  - <!--markup:1:begin-->`$age`<!--markup:1:end--> <!--markup:2:begin-->##$age##<!--markup:2:end--> (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** 
php<!--markup:2:end-->
$http->sendfile(404);  // Serves file defined by HTTP_404 constant
$http->sendfile(403);  // Serves file defined by HTTP_403 constant
<!--markup:1:begin-->```<!--markup:1:end-->
<!--markup:2:begin-->

Example:
`php<!--markup:1:end-->**
<!--markup:2:begin-->%%php<!--markup:2:end-->
$http->sendfile('uploads/document.pdf', 'my-document.pdf', 30);
<!--markup:1:begin-->
`

`mime_type($path): string`
----

===== ##mime_type($path): string## =====<!--markup:2:end-->
Returns MIME type for a file.

**Returns:**
  - MIME type string (e.g., 'application/pdf')
  - Default: <!--markup:1:begin-->`'application/octet-stream'`<!--markup:1:end--> <!--markup:2:begin-->##'application/octet-stream'##<!--markup:2:end-->

**Example:**
<!--markup:1:begin-->```php<!--markup:1:end-->**
<!--markup:2:begin-->
php $mime = $http->mime_type('file.pdf'); // 'application/pdf'
`

---

#### `mime_types(): array`<!--markup:1:end-->
<!--markup:2:begin-->%%

----

===== ##mime_types(): array##<!--markup:2:end--> (Private) <!--markup:2:begin-->=====<!--markup:2:end-->
Loads and caches MIME types from configuration.

**Features:**
  - Reads from <!--markup:1:begin-->`config/mime.types`<!--markup:1:end--> <!--markup:2:begin-->##config/mime.types##<!--markup:2:end-->
  - Caches to <!--markup:1:begin-->`cache/config/mime.types`<!--markup:1:end--> <!--markup:2:begin-->##cache/config/mime.types##<!--markup:2:end-->
  - Reloads if config is updated

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

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

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

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

<!--markup:1:begin-->#### `gzip(): void`<!--markup:1:end--> <!--markup:2:begin-->====

===== ##gzip(): void## =====<!--markup:2:end-->
Compresses HTTP response with gzip/x-gzip.

**Features:**
  - Manually implements gzip (not relying on zlib.output_compression)
  - Produces correct <!--markup:1:begin-->`Content-Length`<!--markup:1:end--> <!--markup:2:begin-->##Content-Length##<!--markup:2:end--> header
  - Only compresses if:
  - 860 bytes < content < 1 MB
  - Client accepts compression
  - Headers not already sent

**Example:**
<!--markup:1:begin-->
`php** 
php<!--markup:2:end-->
$http->gzip();
<!--markup:1:begin-->```

---

###<!--markup:1:end-->
<!--markup:2:begin-->

Utility Methods
`parse_str($str): array` ====

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<!--markup:1:end-->**
<!--markup:2:begin-->%%php<!--markup:2:end-->
$data = $http->parse_str('name=John&age=30');
<!--markup:1:begin-->
`

`request_uri(): string`
----

===== ##request_uri(): string##<!--markup:2:end--> (Private) <!--markup:2:begin-->=====<!--markup:2:end-->
Extracts and normalizes REQUEST_URI from server.

**Normalization:**
  - Removes base URL prefix
  - Removes spaces
  - Collapses multiple slashes
  - Removes <!--markup:1:begin-->`..`<!--markup:1:end--> <!--markup:2:begin-->##..##<!--markup:2:end--> path traversal attempts
  - Removes leading/trailing slashes

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

#### `cut_prefix($prefix,<!--markup:1:end-->

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

===== ##cut_prefix($prefix,<!--markup:2:end--> $path): <!--markup:1:begin-->string`<!--markup:1:end--> <!--markup:2:begin-->string##<!--markup:2:end--> (Private) <!--markup:2:begin-->=====<!--markup:2:end-->
Removes prefix from path (case-insensitive).

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

#### `get_header_conf($file_name): string`<!--markup:1:end-->

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

===== ##get_header_conf($file_name): string##<!--markup:2:end--> (Private) <!--markup:2:begin-->=====<!--markup:2:end-->
Loads security header configuration from files.

**Files Supported:**
  - <!--markup:1:begin-->`csp.conf`<!--markup:1:end--> <!--markup:2:begin-->##csp.conf##<!--markup:2:end--> / <!--markup:1:begin-->`csp_custom.conf`<!--markup:1:end--> <!--markup:2:begin-->##csp_custom.conf##<!--markup:2:end-->
  - <!--markup:1:begin-->`permissions_policy.conf`<!--markup:1:end--> <!--markup:2:begin-->##permissions_policy.conf##<!--markup:2:end--> / <!--markup:1:begin-->`permissions_policy_custom.conf`

---

##<!--markup:1:end--> <!--markup:2:begin-->##permissions_policy_custom.conf##

----

===<!--markup:2:end--> Configuration Dependencies

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

---

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



===<!--markup:2:end--> Constants Used

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

---

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



===<!--markup:2:end--> Workflow Examples

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

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

<!--markup:1:begin-->```php<!--markup:1:end--> <!--markup:2:begin-->====
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();
`

###<!--markup:1:end-->
<!--markup:2:begin-->%%

====<!--markup:2:end--> Example 2: Handling TLS/HTTPS Upgrade

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

###<!--markup:1:end-->
<!--markup:2:begin-->

Example 3: Invalidating Cache After Page Edit 
`php<!--markup:1:end--> <!--markup:2: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
<!--markup:1:begin-->
`
###
====<!--markup:2:end--> Example 4: Serving a File

<!--markup:1:begin-->```php<!--markup:1:end--> <!--markup:2:begin-->====
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);
`

---

##<!--markup:1:end-->
<!--markup:2:begin-->%%

----

===<!--markup:2:end--> Security Considerations

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

====<!--markup:2:end--> 1. **IP Address Spoofing** <!--markup:2:begin-->====<!--markup:2:end-->
  - Validates IPs against private ranges
  - Filters proxy-provided IPs appropriately
  - Configurable reverse proxy trust

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

<!--markup:2:begin-->====<!--markup:2:end--> 2. **Session Security** <!--markup:2:begin-->====<!--markup:2:end-->
  - Binds sessions to IP address
  - Binds sessions to TLS status
  - Supports both file and database storage
  - HttpOnly cookies by default

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

<!--markup:2:begin-->====<!--markup:2:end--> 3. **TLS Enforcement** <!--markup:2:begin-->====<!--markup:2:end-->
  - Automatic HTTPS upgrade when configured
  - Marks TLS sessions to prevent downgrade attacks
  - HSTS header support

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

<!--markup:2:begin-->====<!--markup:2:end--> 4. **Content Security** <!--markup:2:begin-->====<!--markup:2:end-->
  - 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

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

<!--markup:2:begin-->====<!--markup:2:end--> 5. **File Serving** <!--markup:2:begin-->====<!--markup:2:end-->
  - Validates file existence and readability
  - Prevents directory traversal via <!--markup:1:begin-->`realpath()`<!--markup:1:end--> <!--markup:2:begin-->##realpath()##<!--markup:2:end-->
  - Rejects symbolic links
  - Special CSP for SVG and PDF files

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

<!--markup:2:begin-->====<!--markup:2:end--> 6. **Cache Security** <!--markup:2:begin-->====<!--markup:2:end-->
  - Cached only for anonymous users
  - Disabled for sensitive operations (edit, watch)
  - Only GET requests cached

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

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

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

===<!--markup:2:end--> Performance Optimization

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

====<!--markup:2:end--> 1. **Page Caching** <!--markup:2:begin-->====<!--markup:2:end-->
  - Stores full HTML output
  - TTL-based expiration
  - Language and method-aware caching
  - Conditional request support (304 Not Modified)

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

<!--markup:2:begin-->====<!--markup:2:end--> 2. **MIME Type Caching** <!--markup:2:begin-->====<!--markup:2:end-->
  - Loads MIME types once and caches
  - Regenerates only when config changes

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

<!--markup:2:begin-->====<!--markup:2:end--> 3. **Session Options** <!--markup:2:begin-->====<!--markup:2:end-->
  - File-based sessions for simple deployments
  - Database sessions for distributed systems

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

<!--markup:2:begin-->====<!--markup:2:end--> 4. **Compression** <!--markup:2:begin-->====<!--markup:2:end-->
  - Manual gzip implementation
  - Proper Content-Length generation
  - Only compresses appropriate sizes

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

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

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

===<!--markup:2:end--> Debugging <!--markup:2:begin-->===<!--markup:2:end-->

The class integrates with WackoWiki's diagnostic system:

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

---

##<!--markup:1:end-->
<!--markup:2:begin-->


=== Related Classes ===
  • Session Classes (`SessionFileStore`, `SessionDbalStore`)** (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` 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