Capy-Bearer Documentation

fastcgi_request

lib call

Capy

function fastcgi_request(opt : any) any

Description

fastcgi_request sends one FastCGI responder request. Use a Unix socket path in socket, or a numeric IPv4 or IPv6 address in host with port. DNS names are not supported.

Unknown option fields are ignored.

env is one map of caller-supplied CGI variables. Each value must be a byte string. The call does not copy the outer request environment or add CGI defaults. body is a byte string sent through FastCGI STDIN.

stdout contains the raw FastCGI STDOUT stream, including CGI headers. Repeated headers remain intact. stderr contains the responder's diagnostics. Both streams can contain arbitrary bytes.

ok means the transport received a complete FastCGI response. Check value.app_status and value.protocol_status separately. A successful transport does not prove that application work succeeded.

The total connection, write, and read deadline defaults to 30000 milliseconds. timeout_ms accepts 1 through 86400000 milliseconds. The caller's remaining runtime deadline can shorten it. The combined stdout and stderr limit defaults to 8 MiB. max_response_bytes accepts 1 through 64 MiB. The body limit is 8 MiB. Environment names and values total at most 1 MiB across at most 16384 entries.

Each call opens one connection. The client does not multiplex, pool connections, or retry a request. A timeout does not prove that the responder canceled execution. Do not retry side-effecting work without an application-level duplicate check.

PHP-specific bootstrap code, return-value capture, and session framing belong in ordinary libraries. This call does not interpret PHP output or change Capy sessions.

Parameters

opt : options with either socket or host and port, optional env, body, timeout_ms, and max_response_bytes

Return Values

{ok: true, value: {stdout, stderr, app_status, protocol_status}} for a complete response. Failures contain ok: false, error, and error_code.

Errors

Invalid options, connection failures, timeouts, malformed or truncated responses, and output limits return ok: false with error_code and error. Failure does not throw, trap, or stop the request.

Example

Capy

try response := fastcgi_request(socket: "/run/php/php-fpm.sock", env: {
	SCRIPT_FILENAME: "/srv/app/adapter.php",
	REQUEST_METHOD: "POST",
	CONTENT_TYPE: "application/octet-stream",
	CONTENT_LENGTH: "5"
}, body: "hello", timeout_ms: 2000)
{
	print(response.stdout)
}
else
{
	print(response.error_code, ": ", response.error, "\n")
}