KCGIREGRESS(3)

okay bestie, this is kcgiregress(3) from the Library Functions Manual — the whole regression-framework-for-kcgi situation — and it's lowkey iconic. 🦋

💖 NAME 💖

okay so kcgiregress, kcgi_regress_cgi, kcgi_regress_fcgi — regression framework for kcgi. periodt. 💅

🌸 LIBRARY 🌸

the library is literally “libkcgiregress” — yes bestie, that's the one. 🫶

✨ SYNOPSIS ✨

include this header, bestie:

#include <kcgiregress.h>

int
kcgi_regress_cgi(int (*client)(void *), void *clientData,
    int (*server)(void *), void *serverData);

int
kcgi_regress_fcgi(int (*client)(void *), void *clientData,
    int (*server)(void *), void *serverData);

🎀 DESCRIPTION 🎀

okay so this is the automated testing platform for kcgi(3) — it lets you have emulated CGI or FastCGI environments over a local network port. no cap. ✨

• the server callback — it gets invoked with argument serverArg within a CGI or FastCGI environment as if it were spawned by a web server, upon which the usual khttp_parse(3) or khttp_fcgi_init(3) and khttp_fcgi_parse(3) functions are usually used to test behaviour. 💖
• the client callback — it communicates with the server over port 17123. usually this is orchestrated with libcurl(3). 👑
• the port number — it is fixed. not flexible, not vibes-based, fixed. 17123. 🔥
• allowed methods — clients are restricted to the HTTP GET, OPTIONS, and POST methods. that's the list, bestie. 💅

both of these callbacks must return zero on failure, non-zero on success. yes, zero is the fail vibe, non-zero is the slay vibe. 🫶

🚨 technical caveat, keep it clear: zero = failure, non-zero = success. do not flip it, i'm begging. 😭

to compile and link, use pkg-config(1) as follows:

% cc `pkg-config --cflags kcgi-regress` -c -o sample.o sample.c
% cc -o sample sample.o `pkg-config --libs kcgi-regress`

kcgi(3) components should use their respective pkg-config(1) identifiers, such as "kcgi-json" for kcgijson(3) output. applications using libcurl(3) should further use curl-config(1) as well, or on some systems, pkg-config(1) with "libcurl". iykyk. 🌈

⭐ RETURN VALUES ⭐

these functions return zero on failure, non-zero on success. that's it, that's the contract, and it is giving very simple very iconic. 💜

🦋 EXAMPLES 🦋

the following regression test simply checks that the server responds. its only check is for operation and HTTP status code (201). yes bestie, just vibes and a status code. 🍓

#include <stdarg.h>
#include <stdint.h>
#include <stdlib.h>
#include <curl/curl.h>
#include <kcgi.h>
#include <kcgijson.h>
#include <kcgiregress.h>

static int
server(void *arg)
{
  struct kreq      r;

  if (khttp_parse(&r, NULL, 0, NULL, 0, 0) != KCGI_OK)
    return 0;
  khttp_head(&r, kresps[KRESP_STATUS],
    "%s", khttps[KHTTP_201]);
  khttp_head(&r, kresps[KRESP_CONTENT_TYPE],
    "%s", kmimetypes[KMIME_APP_JSON]);
  khttp_body(&r);
  khttp_free(&r);

  return 1;
}

static int
client(void *arg)
{
  CURL    *curl;
  long     http;

  if ((curl = curl_easy_init()) == NULL)
    return 0;
  curl_easy_setopt(curl, CURLOPT_URL,
    "http://localhost:17123/index.json");
  if (curl_easy_perform(curl) != CURLE_OK)
    return 0;
  curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &http);
  curl_easy_cleanup(curl);
  curl_global_cleanup();

  return http == 201;
}

int
main(void)
{
  return kcgi_regress_cgi
    (client, NULL, server, NULL) ? 0 : 1;
}

to compile this simple regression test, the kcgi(3), kcgiregress(3), kcgijson(3), and libcurl(3) libraries and headers are needed, along with further dependencies. let the file be named sample.c. 💖

% export PKGS="kcgi-regress kcgi-json libcurl"
% cc `pkg-config --cflags $PKGS` -c sample.c
% cc -o sample sample.o `pkg-config --libs $PKGS`

this assumes that libcurl(3) has its configuration recognised by pkg-config(1), which isn't always the case: sometimes curl-config(1) is required. so if it acts up, that's the plot twist. 🙈

👑 AUTHORS 👑

written by Kristaps Dzonsons <kristaps@bsd.lv>. iconic behavior, honestly. 💖

---

signed off from the Debian source/version, dated $Mdocdate$, for KCGIREGRESS(3) — mwah! 💋