Difference between revisions for Users / Eo Ny / dev




← Previous edit
Revision 3 as of 05/05/2026 19:10 ▼
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 9 as of 05/05/2026 19:25 ▼
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

(15.7 KiB) -1,730
WikiAdmin

Merge of Version1 & Version2
1 # HTTP Class Technical Documentation== HTTP Class Technical Documentation ==
2
3 ## Overview=== Overview ===
4
5 The `Http` class (`src/class/http.php`##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.
6
7 **File Location:** `src/class/http.php`##src/class/http.php##
8 **Language:** PHP
9 **Dependencies:** Database class, Session classes, Utility classes (##Ut##), Diagnostics class (##Diag##)
10
11 ----
12
13 === Class Properties ===
14
15 ====Public Properties====
16
17 #|
18 *| Property | Type | Description |*
19 || ##$tls_session## | bool | Indicates if the current session uses HTTPS/TLS encryption ||
20 || ##$request_uri## | string | Normalized REQUEST_URI (e.g., 'PageOfNoReturn/show?a=1') ||
21 || ##$ip## | string | Client's real IP address (accounts for proxies) ||
22 || ##$sess## | Session | Reference to the Session object ||
23 || ##$method## | string | Current HTTP method/request type ||
24 |#
25
26 ====Private Properties====
27
28 #|
29 *| Property | Type | Description |*
30 || ##$db## | object | Database connection reference ||
31 || ##$tls_mark## | string | Cookie name for TLS session marking ||
32 || ##$page## | string | Current page name being processed ||
33 || ##$hash## | string | SHA1 hash of the page name ||
34 || ##$query## | string | Encoded query string ||
35 || ##$lang## | string | Current language code ||
36 || ##$file## | string | Cache file path ||
37 || ##$caching## | int | Flag indicating if page should be cached (0 or 1) ||
38 |#
39
40 ----
41 === Constructor ===
42
43 %%php
44 public function __construct(&$db)
45 ```%%
46
47 **Purpose:** Initializes the Http object and sets up HTTP session handling.
48
49 **Parameters:**
50 - `$db`  - ##$db## - Database object reference
51
52 **Initialization Steps:**
53   1. Stores database reference
54   2. Extracts and normalizes REQUEST_URI
55   3. Detects TLS/HTTPS session status
56   4. Determines client's real IP address
57   5. Sets up TLS mark cookie name
58   6. Enforces TLS session upgrade if needed
59
60 **Example:**
61 ```%%php
62 $http = new Http($db);
63 ```%%
64
65 ----
66
67 ## Core Methods=== Core Methods ===
68
69 ### Session Management==== Session Management ====
70
71 #### `session($route): void`===== ##session($route): void## =====
72 Initializes the session handler (file-based or database-based).
73
74 **Parameters:**
75 - `$route`  - ##$route## (int) - Routing flag:
76   - Bit 2 (`$route & 2`##$route & 2##): Enable static mode for files/freecap (disables replay prevention and ID regeneration)
77
78 **Features:**
79   - Selects storage backend (file or database)
80   - Configures cookie settings (security, path, httponly)
81   - Binds IP and TLS validation
82   - Recovers diagnostic logs from previous session
83
84 **Example:**
85 ```%%php
86 $http->session(0); // Normal session
87 $http->session(2); // Static file serving mode
88 ```%%
89
90 ----
91
92 ### Caching System==== Caching System ====
93
94 #### `check_cache($page, $method): void`===== ##check_cache($page, $method): void## =====
95 Determines if a page can be cached and prepares the cache check.
96
97 **Parameters:**
98 - `$page`  - ##$page## (string) - Page name to cache
99 - `$method`  - ##$method## (string) - Request method/action (e.g., 'show', 'edit')
100
101 **Caching Rules:**
102   - ✅ Enabled for GET requests only
103   - ✅ Disabled for POST requests
104   - ❌ Never cached for 'edit' or 'watch' methods
105   - ✅ Only cached for anonymous users (no logged-in users)
106
107 **Example:**
108 ```%%php
109 $http->check_cache('HomePage', 'show');
110 ```%%
111
112 ----
113
114 #### `store_cache(): void`===== ##store_cache(): void## =====
115 Saves the generated page content to cache file.
116
117 **Features:**
118   - Retrieves output buffer content
119   - Saves to cache file with proper permissions
120   - Records cache metadata in database
121   - Only executes if caching flag is set and user is anonymous
122
123 **Example:**
124 ```%%php
125 // Called at end of page rendering
126 $http->store_cache();
127 ```%%
128
129 ----
130
131 #### `invalidate_page($page): int`===== ##invalidate_page($page): int## =====
132 Invalidates all cached versions of a page.
133
134 **Parameters:**
135 - `$page`  - ##$page## (string) - Page name to invalidate
136
137 **Returns:**
138   - Number of cache entries invalidated
139
140 **Process:**
141   1. Finds all cached versions (different methods/languages)
142   2. Touches files to past timestamp (faster than deletion)
143   3. Removes entries from cache metadata table
144   4. Returns count of invalidated caches
145
146 **Example:**
147 ```%%php
148 $count = $http->invalidate_page('HomePage');
149 echo "Invalidated $count cache entries";
150 ```%%
151
152 ----
153
154 ### TLS/HTTPS Security==== TLS/HTTPS Security ====
155
156 #### `secure_base_url(): void`===== ##secure_base_url(): void## =====
157 Switches base URL from HTTP to HTTPS.
158
159 **Purpose:**
160   - Ensures all subsequent URLs use HTTPS
161   - Stores original HTTP URL for fallback
162   - Called when TLS session is detected
163
164 **Example:**
165 ```%%php
166 $http->secure_base_url();
167 // $db->base_url now uses https://
168 ```%%
169
170 ----
171
172 #### `ensure_tls($url): void`===== ##ensure_tls($url): void## =====
173 Enforces HTTPS for a specific URL and redirects if necessary.
174
175 **Parameters:**
176 - `$url`  - ##$url## (string) - URL to secure
177
178 **Behavior:**
179   - If not already HTTPS and TLS is enabled, forces HTTPS redirect
180   - Handles both relative and absolute URLs
181   - Converts relative URLs using current server name
182
183 **Example:**
184 ```%%php
185 $http->ensure_tls('/secure/payment');
186 ```%%
187
188 ----
189
190 ### IP Address Detection==== IP Address Detection ====
191
192 #### `real_ip(): string` (Private)===== ##real_ip(): string## (Private) =====
193 Detects client's real IP address accounting for proxies.
194
195 **Proxy Headers Checked (in order):**
196 1. `HTTP_X_CLUSTER_CLIENT_IP`  1. ##HTTP_X_CLUSTER_CLIENT_IP##
197 2. `HTTP_X_FORWARDED_FOR`  2. ##HTTP_X_FORWARDED_FOR## (or custom header)
198 3. `HTTP_CLIENT_IP`  3. ##HTTP_CLIENT_IP##
199 4. `HTTP_X_REMOTE_ADDR`  4. ##HTTP_X_REMOTE_ADDR##
200 5. `REMOTE_ADDR`  5. ##REMOTE_ADDR## (fallback)
201
202 **Features:**
203   - Filters out private/reserved IP ranges
204   - Respects configured reverse proxy addresses
205 - Returns `'0.0.0.0'`  - Returns ##'0.0.0.0'## as fallback
206
207 **Configuration in Database:**
208 - `reverse_proxy_addresses`  - ##reverse_proxy_addresses## - Comma/space-separated proxy IPs
209 - `reverse_proxy_header` - Custom header name (default: `X-Forwarded-For`  - ##reverse_proxy_header## - Custom header name (default: ##X-Forwarded-For##)
210
211 **Example:**
212 ```%%php
213 $client_ip = $http->ip; // e.g., "203.0.113.42"
214 ```%%
215
216 ----
217
218 ### HTTPS Detection==== HTTPS Detection ====
219
220 #### `tls_session(): bool` (Private)===== ##tls_session(): bool## (Private) =====
221 Detects if current connection uses HTTPS/TLS.
222
223 **Checks (any being true = HTTPS):**
224   - ##$_SERVER['HTTPS']## is 'on'
225   - ##$_SERVER['SERVER_PORT']## is 443
226   - ##$_SERVER['HTTP_X_FORWARDED_PROTO']## is 'https'
227   - ##$_SERVER['HTTP_X_FORWARDED_SSL']## is 'on'
228   - ##$_SERVER['HTTP_X_FORWARDED_PORT']## is 443
229
230 ----
231
232 ==== Security Headers ====
233
234 ===== ##http_security_headers(): void## =====
235
236
237 ==== HTTP Methods ====
238
239 ===== ##redirect($url, $permanent = false): void## =====
240 Performs an HTTP redirect.
241
242 **Parameters:**
243 - `$url`  - ##$url## (string) - Target URL
244 - `$permanent`  - ##$permanent## (bool) - Use 301 (permanent) vs 302 (temporary)
245
246 **Features:**
247 - Decodes `&`  - Decodes ##&## entities to prevent broken redirects
248   - Only works if headers not yet sent
249   - Uses output buffering to work anywhere in page processing
250
251 **Example:**
252 ```%%php
253 $http->redirect('http://example.com/new-page', true); // 301
254 $http->redirect('/wiki/HomePage'); // 302
255 ```%%
256
257 ----
258
259 #### `terminate(): void`===== ##terminate(): void## =====
260 Safe exit/die with cleanup.
261
262 **Cleanup Operations:**
263   - Saves diagnostic logs to session flash data
264   - Ends script execution
265
266 **Example:**
267 ```%%php
268 $http->terminate();
269 ```%%
270
271 ----
272
273 #### `status($code): void`===== ##status($code): void## =====
274 Sets HTTP response status code.
275
276 **Supported Status Codes:**
277 ```%%php
278 200 => 'OK'
279 206 => 'Partial Content'
280 301 => 'Moved Permanently'
… …
291 500 => 'Internal Server Error'
292 501 => 'Not Implemented'
293 503 => 'Service Unavailable'
294 ```%%
295
296 **Example:**
297 ```%%php
298 $http->status(404); // Send 404 Not Found
299 ```%%
300
301 ----
302
303 ### Caching Control==== Caching Control ====
304
305 #### `no_cache($client_only = true): void`===== ##no_cache($client_only = true): void## =====
306 Disables caching of the current page.
307
308 **Parameters:**
309 - `$client_only`  - ##$client_only## (bool, default: TRUE)
310   - `TRUE`##TRUE##: Disable browser cache only
311   - `FALSE`##FALSE##: Disable both browser and server cache
312
313 **Headers Set:**
314 - `Last-Modified: <current-time>`  - ##Last-Modified: <current-time>## (always fresh)
315 - `Cache-Control: no-store`  - ##Cache-Control: no-store##
316
317 **Example:**
318 ```%%php
319 $http->no_cache(); // Client-side only
320 $http->no_cache(false); // Both client & server
321 ```%%
322
323 ----
324
325 #### `cache_promisc(): void`===== ##cache_promisc(): void## =====
326 Marks page as publicly cacheable.
327
328 **Headers Set:**
329 - `Cache-Control: public`  - ##Cache-Control: public##
330
331 **Example:**
332 ```%%php
333 $http->cache_promisc();
334 ```%%
335
336 ----
337
338 ### Language Negotiation==== Language Negotiation ====
339
340 #### `user_agent_language(): string`===== ##user_agent_language(): string## =====
341 Determines best language based on browser preferences.
342
343 **Features:**
344   - Follows RFC 9110 section 12.5.4 (HTTP Accept-Language)
345 - Parses `Accept-Language`  - Parses ##Accept-Language## header with quality factors
346   - Attempts exact match first, then language fallback
347   - Falls back to default system language
348
349 **Example Header:**
350 ```%%
351 Accept-Language: en-US,en;q=0.9,de;q=0.8
352 ```%%
353
354 **Returns:**
355   - Language code (e.g., 'en', 'en-US', 'de')
356
357 ----
358
359 #### `available_languages($subset = true): array`===== ##available_languages($subset = true): array## =====
360 Returns list of available language translations.
361
362 **Parameters:**
363 - `$subset`  - ##$subset## (bool, default: TRUE)
364   - `TRUE`##TRUE##: Only allowed languages
365   - `FALSE`##FALSE##: All available languages
366
367 **Features:**
368 - Scans `LANG_DIR`  - Scans ##LANG_DIR## for language files
369 - Filters by `allowed_languages`  - Filters by ##allowed_languages## config if set
370   - Caches result in session
371   - System language always included
372
373 **Returns:**
374 - Associative array: `['en' => 'en', 'de' => 'de', ...]`  - Associative array: ##['en' => 'en', 'de' => 'de', ...]##
375
376 **Example:**
377 ```%%php
378 $all_langs = $http->available_languages(false);
379 $allowed = $http->available_languages(true);
380 ```%%
381
382 ----
383
384 ### File Serving==== File Serving ====
385
386 #### `sendfile($path, $filename = null, $age = null): void`===== ##sendfile($path, $filename = null, $age = null): void## =====
387 Serves files with proper HTTP headers and caching.
388
389 **Parameters:**
390 - `$path`  - ##$path## (string) - File path (or HTTP_XXX constant for error pages)
391 - `$filename`  - ##$filename## (string, optional) - Custom download filename
392 - `$age`  - ##$age## (int, optional) - Cache age in days
393
394 **Features:**
395   - HTTP range request support (partial file downloads)
396   - ETag and Last-Modified conditional requests
397   - Proper MIME type detection
398   - Content-Security-Policy for special file types
399   - Streaming for large files
400   - GZip compression for text files
401
402 **Special Paths:**
403 ```%%php
404 $http->sendfile(404); // Serves file defined by HTTP_404 constant
405 $http->sendfile(403); // Serves file defined by HTTP_403 constant
406 ```%%
407
408 **Example:**
409 ```%%php
410 $http->sendfile('uploads/document.pdf', 'my-document.pdf', 30);
411 ```%%
412
413 ----
414
415 #### `mime_type($path): string`===== ##mime_type($path): string## =====
416 Returns MIME type for a file.
417
418 **Returns:**
419   - MIME type string (e.g., 'application/pdf')
420 - Default: `'application/octet-stream'`  - Default: ##'application/octet-stream'##
421
422 **Example:**
423 ```%%php
424 $mime = $http->mime_type('file.pdf'); // 'application/pdf'
425 ```%%
426
427 ----
428
429 #### `mime_types(): array` (Private)===== ##mime_types(): array## (Private) =====
430 Loads and caches MIME types from configuration.
431
432 **Features:**
433 - Reads from `config/mime.types`  - Reads from ##config/mime.types##
434 - Caches to `cache/config/mime.types`  - Caches to ##cache/config/mime.types##
435   - Reloads if config is updated
436
437 ----
438
439 ### Compression==== Compression ====
440
441 #### `gzip(): void`===== ##gzip(): void## =====
442 Compresses HTTP response with gzip/x-gzip.
443
444 **Features:**
445   - Manually implements gzip (not relying on zlib.output_compression)
446 - Produces correct `Content-Length`  - Produces correct ##Content-Length## header
447   - Only compresses if:
448   - 860 bytes < content < 1 MB
449   - Client accepts compression
450   - Headers not already sent
451
452 **Example:**
453 ```%%php
454 $http->gzip();
455 ```%%
456
457 ----
458
459 ### Utility Methods==== Utility Methods ====
460
461 #### `parse_str($str): array` (Private)===== ##parse_str($str): array## (Private) =====
462 Parses URL-encoded strings with special character handling.
463
464 **Purpose:**
465   - Safely handles special characters in query/form data
466   - Converts encoding properly
467
468 **Example:**
469 ```%%php
470 $data = $http->parse_str('name=John&age=30');
471 ```%%
472
473 ----
474
475 #### `request_uri(): string` (Private)===== ##request_uri(): string## (Private) =====
476 Extracts and normalizes REQUEST_URI from server.
477
478 **Normalization:**
479   - Removes base URL prefix
480   - Removes spaces
481   - Collapses multiple slashes
482 - Removes `..`  - Removes ##..## path traversal attempts
483   - Removes leading/trailing slashes
484
485 ----
486
487 #### `cut_prefix($prefix, $path): string` (Private)===== ##cut_prefix($prefix, $path): string## (Private) =====
488 Removes prefix from path (case-insensitive).
489
490 ----
491
492 #### `get_header_conf($file_name): string` (Private)===== ##get_header_conf($file_name): string## (Private) =====
493 Loads security header configuration from files.
494
495 **Files Supported:**
496   - ##csp.conf## / ##csp_custom.conf##
497   - ##permissions_policy.conf## / ##permissions_policy_custom.conf##
498
499 ----
500
501 === Configuration Dependencies ===
502
503
504
505 === Constants Used ===
506
507
508
509 === Workflow Examples ===
510
511 ==== Example 1: Handling a GET Request ====
512
513 %%php
514 // In main wiki entry point
515 $http = new Http($db);
516 $http->session(0); // Start session
… …
528
529 // Possibly compress output
530 $http->gzip();
531 ```%%
532
533 ### Example 2: Handling TLS/HTTPS Upgrade==== Example 2: Handling TLS/HTTPS Upgrade ====
534
535 ```%%php
536 $http = new Http($db); // Constructor detects TLS requirement
537 // If TLS is enabled and user wasn't in TLS before:
538 // - Sets TLS session flag
539 // - Marks session with TLS cookie
540 // - Redirects to HTTPS version
541 ```%%
542
543 ### Example 3: Invalidating Cache After Page Edit==== Example 3: Invalidating Cache After Page Edit ====
544
545 ```%%php
546 // User edits a page
547 $http = new Http($db);
548 $count = $http->invalidate_page('HomePage');
549 // All cached versions (different languages, methods) are invalidated
550 ```%%
551
552 ### Example 4: Serving a File==== Example 4: Serving a File ====
553
554 ```%%php
555 $http = new Http($db);
556 $http->session(2); // Static file mode - no session replay prevention
557
558 // Serve with 30-day cache
559 $http->sendfile('uploads/manual.pdf', 'user-manual.pdf', 30);
560 ```%%
561
562 ----
563
564 ## Security Considerations=== Security Considerations ===
565
566 ### 1. **IP Address Spoofing**==== 1. **IP Address Spoofing** ====
567   - Validates IPs against private ranges
568   - Filters proxy-provided IPs appropriately
569   - Configurable reverse proxy trust
570
571 ### 2. **Session Security**==== 2. **Session Security** ====
572   - Binds sessions to IP address
573   - Binds sessions to TLS status
574   - Supports both file and database storage
575   - HttpOnly cookies by default
576
577 ### 3. **TLS Enforcement**==== 3. **TLS Enforcement** ====
578   - Automatic HTTPS upgrade when configured
579   - Marks TLS sessions to prevent downgrade attacks
580   - HSTS header support
581
582 ### 4. **Content Security**==== 4. **Content Security** ====
583   - CSP headers to prevent XSS
584   - X-Frame-Options to prevent clickjacking
585   - X-Content-Type-Options to prevent MIME sniffing
586   - Referrer-Policy control
587   - Permissions-Policy for browser features
588
589 ### 5. **File Serving**==== 5. **File Serving** ====
590   - Validates file existence and readability
591 - Prevents directory traversal via `realpath()`  - Prevents directory traversal via ##realpath()##
592   - Rejects symbolic links
593   - Special CSP for SVG and PDF files
594
595 ### 6. **Cache Security**==== 6. **Cache Security** ====
596   - Cached only for anonymous users
597   - Disabled for sensitive operations (edit, watch)
598   - Only GET requests cached
599
600 ----
601
602 ## Performance Optimization=== Performance Optimization ===
603
604 ### 1. **Page Caching**==== 1. **Page Caching** ====
605   - Stores full HTML output
606   - TTL-based expiration
607   - Language and method-aware caching
608   - Conditional request support (304 Not Modified)
609
610 ### 2. **MIME Type Caching**==== 2. **MIME Type Caching** ====
611   - Loads MIME types once and caches
612   - Regenerates only when config changes
613
614 ### 3. **Session Options**==== 3. **Session Options** ====
615   - File-based sessions for simple deployments
616   - Database sessions for distributed systems
617
618 ### 4. **Compression**==== 4. **Compression** ====
619   - Manual gzip implementation
620   - Proper Content-Length generation
621   - Only compresses appropriate sizes
622
623 ----
624
625 ## Debugging=== Debugging ===
626
627 The class integrates with WackoWiki's diagnostic system:
628
629 ```%%php
630 // Diagnostic messages are preserved across redirects
631 // via session flash data
632
633 // Check cached pages (debug comments in output):
634 // <!-- WackoWiki Caching Engine: page cached at 2024-01-15 12:30:45 GMT -->
635 %%
636
637 ----
638
639 === Related Classes ===
640   - **Session Classes** (##SessionFileStore##, ##SessionDbalStore##) - Session management backends
641   - **Database Class** - Configuration and cache metadata storage
642   - **Ut Utility Class** - String/path utilities
643   - **Diag Class** - Diagnostic logging
644
645 ----
646
647 === Version History ===
648   - Supports PHP 8.0+ (uses match expressions, union types)
649   - Follows RFC 9110 for HTTP header handling
650   - Modern cookie security practices
651
652 ----
653
654 === Conclusion ===
655
656 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:
657   - Extending WackoWiki with custom request handlers
658   - Implementing custom session logic
659   - Adding new security policies
660   - Optimizing cache strategies
661   - Debugging HTTP-related issues