HTTP Class Technical Documentation (diff)

Difference between revisions for Users / Eo Ny / dev

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