HTTP Class Technical Documentation (diff)

Difference between revisions for Users / Eo Ny / dev

Version1	Version2	Differences
1	1	== HTTP Class Technical Documentation ==
2	2
	3	{{toc numerate=1}}
3	4	=== Overview ===
4	5
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.
…	…	…
12	13
13	14	=== Class Properties ===
14	15
15		==== ~~Public Properties~~ ====
	16	====Public Properties====
16	17
17	18	#\|
18	19	\| Property \| Type \| Description \|
…	…	…
21	22	\|\| ##$ip## \| string \| Client's real IP address (accounts for proxies) \|\|
22	23	\|\| ##$sess## \| Session \| Reference to the Session object \|\|
23	24	\|\| ##$method## \| string \| Current HTTP method/request type \|\|
24		\|\| ==== Private Properties ==== \|\|
25		\|\| Property \| Type \| Description \|\|
26		\|\| ---------- \| ------ \| ------------- \|\|
	25	\|#
	26
	27	====Private Properties====
	28
	29	#\|
	30	\| Property \| Type \| Description \|
27	31	\|\| ##$db## \| object \| Database connection reference \|\|
28	32	\|\| ##$tls_mark## \| string \| Cookie name for TLS session marking \|\|
29	33	\|\| ##$page## \| string \| Current page name being processed \|\|
…	…	…
32	36	\|\| ##$lang## \| string \| Current language code \|\|
33	37	\|\| ##$file## \| string \| Cache file path \|\|
34	38	\|\| ##$caching## \| int \| Flag indicating if page should be cached (0 or 1) \|\|
35		\|
	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
36	629	=== Security Considerations ===
37	630
38	631	==== 1. IP Address Spoofing ====