Difference between revisions for Users / Eo Ny / dev




← Previous edit
Revision 3 as of 05/05/2026 19:10 ▼
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 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 18 as of 05/21/2026 16:12 ▼
19 07/07/2026 11:27 WikiAdmin 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

(18.4 KiB) +1,019
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 ===

Public Properties


*| Property | Type | Description | |
|
|
| | `$tls_session`* || $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` $sess | Session | Reference to the Session object | | `$method` $method | string | Current HTTP method/request type | ### Private Properties||

Private Properties


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

=== Constructor <!--markup:1:begin--> 
`php<!--markup:1:end--> <!--markup:2:begin-->===

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

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

###
----

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

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

===== ##check_cache($page,<!--markup:2:end--> $method): <!--markup:1:begin-->void`<!--markup:1:end--> <!--markup:2:begin-->void## =====<!--markup:2:end-->
Determines if a page can be cached and prepares the cache check.

**Parameters:**
  - ##$page## (string) - Page name to cache
  - <!--markup:1:begin-->`$method`<!--markup:1:end--> <!--markup:2:begin-->##$method##<!--markup:2:end--> (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:1:end-->**
<!--markup:2:begin-->
(hl 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:**
(hl 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

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-->%%(hl 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:**
  - ##$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:**
(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. <!--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-->`'...'`<!--markup:1:end--> <!--markup:2:begin-->##'...'##<!--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<!--markup:1:end-->**
<!--markup:2:begin-->
(hl php)
$client_ip = $http->ip; // e.g., "23..113.42"
`

---

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

----

====<!--markup:2:end--> HTTPS Detection

<!--markup:1:begin-->#### `tls_session(): bool`<!--markup:1:end--> <!--markup:2:begin-->====

===== ##tls_session(): bool##<!--markup:2:end--> (Private) <!--markup:2:begin-->=====<!--markup:2:end-->
Detects if current connection uses HTTPS/TLS.

**Checks (any being true = HTTPS):**
  - ##$_SERVER['HTTPS']## is 'on'
  - ##$_SERVER['SERVER_PORT']## is 443
  - <!--markup:1:begin-->`$_SERVER['HTTP_X_FORWARDED_PROTO']`<!--markup:1:end--> <!--markup:2:begin-->##$_SERVER['HTTP_X_FORWARDED_PROTO']##<!--markup:2:end--> is 'https'
  - <!--markup:1:begin-->`$_SERVER['HTTP_X_FORWARDED_SSL']`<!--markup:1:end--> <!--markup:2:begin-->##$_SERVER['HTTP_X_FORWARDED_SSL']##<!--markup:2:end--> is 'on'
  - ##$_SERVER['HTTP_X_FORWARDED_PORT']## is 443

----

==== Security Headers ====

=====##http_security_headers(): void##=====

Sets security-related HTTP headers.

**Headers Set:**

<!--markup:2:begin-->#|<!--markup:2:end-->
*| Header | Purpose | Config Key |
<!--markup:1:begin-->|--------|---------|------------|
|<!--markup:1:end-->*
<!--markup:2:begin-->||<!--markup:2:end--> Content-Security-Policy | XSS/injection protection | <!--markup:1:begin-->`csp` |
|<!--markup:1:end--> <!--markup:2:begin-->##csp## ||
||<!--markup:2:end--> 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 <!--markup:1:begin-->`csp.conf`)<!--markup:1:end--> <!--markup:2:begin-->##csp.conf##)<!--markup:2:end-->
  - <!--markup:1:begin-->`2`<!--markup:1:end--> <!--markup:2:begin-->##2##<!--markup:2:end--> - Custom policy (from ##csp_custom.conf##)

**Example:**
%%(hl php)
$http->http_security_headers();
%%

----
==== HTTP Methods ====

===== ##redirect($url, $permanent = false): <!--markup:1:begin-->void`<!--markup:1:end--> <!--markup:2:begin-->void## =====<!--markup:2:end-->
Performs an HTTP redirect.

**Parameters:**
  - <!--markup:1:begin-->`$url`<!--markup:1:end--> <!--markup:2:begin-->##$url##<!--markup:2:end--> (string) - Target URL
  - <!--markup:1:begin-->`$permanent`<!--markup:1:end--> <!--markup:2:begin-->##$permanent##<!--markup:2:end--> (bool) - Use 31 (permanent) vs 32 (temporary)

**Features:**
  - Decodes <!--markup:1:begin-->`&amp;`<!--markup:1:end--> <!--markup:2:begin-->##&amp;##<!--markup:2:end--> entities to prevent broken redirects
  - Only works if headers not yet sent
  - Uses output buffering to work anywhere in page processing

**Example:**
%%(hl 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:**
%%(hl php)
$http->terminate();
%%

----

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

**Supported Status Codes:**
%%(hl 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:**
%%(hl 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
  - <!--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**
PHP 
<!--markup:2:end-->
$http->no_cache();        // Client-side only
$http->no_cache(false);   // Both client & server
<!--markup:1:begin-->```

---

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

cache_promisc(): void

Marks page as publicly cacheable.

Headers Set:
  • Cache-Control: public

Example:
`php<!--markup:1:end-->**
<!--markup:2:begin-->%%(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 <!--markup:1:begin-->`Accept-Language`<!--markup:1:end--> <!--markup:2:begin-->##Accept-Language##<!--markup:2:end--> 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
<!--markup:1:begin-->
` 
<!--markup:2:end-->

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

----

===== ##available_languages($subset = 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 ##LANG_DIR## 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-->
(hl 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): void## =====
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(44);  // Serves file defined by HTTP_44 constant
$http->sendfile(43);  // Serves file defined by HTTP_43 constant
<!--markup:1:begin-->```<!--markup:1:end-->
<!--markup:2:begin-->

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

`mime_types(): array`
----

===== ##mime_types(): array##<!--markup:2:end--> (Private) <!--markup:2:begin-->=====<!--markup:2:end-->
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

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

**Example:**
(hl php) $http->gzip();
----

==== Utility Methods

<!--markup:1:begin-->#### `parse_str($str): array`<!--markup:1:end--> <!--markup:2:begin-->====

===== ##parse_str($str): array##<!--markup:2:end--> (Private) =====
Parses URL-encoded strings with special character handling.

**Purpose:**
  - Safely handles special characters in query/form data
  - Converts encoding properly

**Example:**
(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 <!--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).

----

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

<!--markup:2:begin-->#|<!--markup:2:end-->
*| Setting | Type | Purpose |*
|| ##base_url## | string | Wiki's base URL <!--markup:1:begin-->|
| `tls`<!--markup:1:end--> <!--markup:2:begin-->||
|| ##tls##<!--markup:2:end--> | bool | Enable HTTPS enforcement ||
|| ##cache## | bool | Enable page caching <!--markup:1:begin-->|
| `cache_ttl`<!--markup:1:end--> <!--markup:2:begin-->||
|| ##cache_ttl##<!--markup:2:end--> | int | Cache lifetime in seconds <!--markup:1:begin-->|
| `session_store`<!--markup:1:end--> <!--markup:2:begin-->||
|| ##session_store##<!--markup:2:end--> | int | 1=File, =Database ||
|| ##system_seed_hash## | string | Session encryption seed <!--markup:1:begin-->|
| `cookie_prefix`<!--markup:1:end--> <!--markup:2:begin-->||
|| ##cookie_prefix##<!--markup:2:end--> | 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 <!--markup:1:begin-->|
| `reverse_proxy_header`<!--markup:1:end--> <!--markup:2:begin-->||
|| ##reverse_proxy_header##<!--markup:2:end--> | string | Custom X-Forwarded header ||
|| ##language## | string | Default language code ||
|| ##multilanguage## | bool | Enable language negotiation <!--markup:1:begin-->|
| `allowed_languages`<!--markup:1:end--> <!--markup:2:begin-->||
|| ##allowed_languages##<!--markup:2:end--> | string | Comma/space-separated allowed langs ||
|| ##enable_security_headers## | bool | Send security headers <!--markup:1:begin-->|
| `csp`<!--markup:1:end--> <!--markup:2:begin-->||
|| ##csp##<!--markup:2:end--> | int | CSP setting (/1/2) ||
|| ##permissions_policy## | int | Permissions-Policy setting (/1/2) <!--markup:1:begin-->|
| `referrer_policy`<!--markup:1:end--> <!--markup:2:begin-->||
|| ##referrer_policy##<!--markup:2:end--> | 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 <!--markup:1:begin-->|
| `CHMOD_FILE`<!--markup:1:end--> <!--markup:2:begin-->||
|| ##CHMOD_FILE##<!--markup:2:end--> | int | File permissions for config cache ||
|| ##CACHE_PAGE_DIR## | string | Page cache directory <!--markup:1:begin-->|
| `CACHE_SESSION_DIR`<!--markup:1:end--> <!--markup:2:begin-->||
|| ##CACHE_SESSION_DIR##<!--markup:2:end--> | string | Session cache directory ||
|| ##CACHE_CONFIG_DIR## | string | Config cache directory <!--markup:1:begin-->|
| `CONFIG_DIR`<!--markup:1:end--> <!--markup:2:begin-->||
|| ##CONFIG_DIR##<!--markup:2:end--> | string | Configuration directory <!--markup:1:begin-->|
| `LANG_DIR`<!--markup:1:end--> <!--markup:2:begin-->||
|| ##LANG_DIR##<!--markup:2:end--> | string | Language files directory <!--markup:1:begin-->|
| `DAYSECS`<!--markup:1:end--> <!--markup:2:begin-->||
|| ##DAYSECS##<!--markup:2:end--> | int | Seconds in a day (864) ||
|| ##HTTP_44## | string | Path to 44 error page ||
|| ##HTTP_43## | string | Path to 43 error page <!--markup:1:begin-->|

---

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

----

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

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

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

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

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

==== 5. **File Serving** ====
  - 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** ====
  - Cached only for anonymous users
  - Disabled for sensitive operations (edit, watch)
  - Only GET requests cached

----

=== 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 (34 Not Modified)

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

----

=== Debugging ===

The class integrates with WackoWiki's diagnostic system:

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

<!--markup:2:begin-->
(hl 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 >
%%


=== Related Classes <!markup:2:begin-->===<!markup:2:end>
  • 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 <!markup:2:begin>

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