Detailed Description

Thin kcgi integration helpers used by VM opcodes under src/vm/kcgi/.

This module centralizes compact helpers around the kcgi API so the VM opcode snippets included by vm.c can remain minimal and focus on stack marshalling. The helpers here do not depend on VM internals beyond the Value conversion utilities used to represent HTTP requests as Fun values. Keeping the external-API specifics in src/extensions/ mirrors other integrations (OpenSSL, PCRE2, SQLite, XML2, JSON, INI) and improves maintainability.

Build-time feature flag:

All code in this file is compiled only when FUN_WITH_KCGI is enabled. When disabled, the file provides no symbols and VM opcodes compiled from src/vm/kcgi/*.c will fall back to no-op/falsey behaviors as documented in those opcode snippets.

Ownership and memory model:

kcgi_parse_request() allocates a struct kreq via khttp_parse() and, on success, returns it through the out-parameter; the caller takes ownership and must later release it with kcgi_free_request().
kcgi_free_request() calls khttp_free() and then frees the allocation wrapper used by this module.
kcgi_write_str() does not take ownership of the input string; it may be NULL, which is treated as an empty string.
kreq_to_fun() and kcgi_fields_to_map() create Fun Values following the VM's normal ownership semantics (returned by value to the caller).

Global state and lifetime:

A thread-local pointer g_kcgi_req holds the current request for the active CGI handling context. VM opcodes are responsible for setting and clearing this pointer by calling the helpers exposed here.

Error handling:

Functions return 0/NULL on failure and non-zero/valid objects on success. Callers should check return values before use. No errno is set.

Thread-safety:

The request handle is stored in a thread-local variable to isolate state between concurrent executions. Helpers otherwise maintain no global mutable state.

Definition in file kcgi.c.