HTTP Class Technical Documentation (diff)

Difference between revisions for Users / Eo Ny / dev

Version1		Version2
1	== HTTP Class Technical Documentation ==	1	== HTTP Class Technical Documentation ==
2		2
		3	{{toc numerate=1}}
3	=== Overview ===	4	=== Overview ===
4		5
5	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.	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.
…	…	…	…
10		11
11	----	12	----
12		13
13		14	=== Class Properties ===
14		15
15		16	====Public Properties====
16		17
17		18	#\|
		19	\| Property \| Type \| Description \|
		20	\|\| ##$tls_session## \| bool \| Indicates if the current session uses HTTPS/TLS encryption \|\|
		21	\|\| ##$request_uri## \| string \| Normalized REQUEST_URI (e.g., 'PageOfNoReturn/show?a=1') \|\|
		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 \|\|
		34	\|\| ##$hash## \| string \| SHA1 hash of the page name \|\|
		35	\|\| ##$query## \| string \| Encoded query string \|\|
		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	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl php)
		293	$http->terminate();
		294	%%
		295
		296	----
		297
		298	===== ##status($code): void## =====
		299	Sets HTTP response status code.
		300
		301	Supported Status Codes:
		302	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl 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	%%(hl 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	----
18		628
19	=== Security Considerations ===	629	=== Security Considerations ===
20		630
…	…	…	…
81		691
82	The class integrates with WackoWiki's diagnostic system:	692	The class integrates with WackoWiki's diagnostic system:
83		693
84	%%~~php~~	694	%%(hl php)
85	// Diagnostic messages are preserved across redirects	695	// Diagnostic messages are preserved across redirects
86	// via session flash data	696	// via session flash data
87		697