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

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