HTTP Class Technical Documentation (diff)

Difference between revisions for Users / Eo Ny / dev

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