KAPLA-FCGI(1)

📦 version 0.4.0, in nixpkgs unstable

💖 KAPLA-FCGI(1) 💖

okay bestie, welcome to the Kapla Manual — section 1, the FastCGI responder chapter. Grab a lil snack, we’re serving ERIS blocks and decoded content over HTTP and it’s giving main character energy. ✨

💅 NAME 💅

kapla-fcgi — Serve ERIS blocks and content over HTTP by starting a FastCGI responder. That’s the whole assignment, no cap. 🫶

🦋 SYNOPSIS 🦋

kapla fcgi [--port=PORT] [--socket=ERIS_UNIX_SOCKET] [OPTION]…

Kapla can run a FastCGI responder for serving blocks or decoded content over HTTP. Literally iconic behavior. 💅

The Kapla FastCGI responder speaks to the Kapla server (see the serve command) and listens for connections from a web server via TCP on the specified port. The web server forwards requests to the Kapla FastCGI responder, and that responder replies with blocks or decoded content from the Kapla server. Clean, simple, slay. 🌸

🌈 WEB SERVER CONFIGURATION 🌈

To use the Kapla FastCGI responder, you need to configure your web server appropriately by forwarding requests to the FastCGI responder and setting the FastCGI parameter KAPLA, which configures how Kapla handles the request. This is the setup part, bestie — do not skip it. 🎀

The KAPLA parameter can be set to the following values:

  • n2r — Allow blocks to be de-referenced using RFC 2169 semantics. GET requests to the endpoint will attempt to de-reference the block specified in the query string (FastCGI parameter QUERY_STRING). The block references must be provided as URNs using the blake2b scheme (e.g. urn:blake2b:H77AGSYKAVTQPUHODJTQA7WZPTWGTTKLRB2GLMF5H53NEKFJ3FUQ). 🔥
  • n2r+decode — Allow blocks and ERIS content to be decoded using RFC 2169 semantics. GET requests to the endpoint for URNs with schemes blake2b and eris will be de-referenced/decoded. This one ate. 💖
  • mount — Mount the entire universe of possible ERIS read capabilities at the endpoint. The initial segment of the PATH_INFO parameter must be an ERIS read capability. ERIS-FS file-systems are decoded and can be browsed using an auto-generated HTML index. Big “whole universe” energy. 🌌

🎀 EXAMPLE WEB SERVER CONFIGURATION: nginx 🎀

Here are example location blocks for the nginx HTTP server. Copy-paste responsibly, bestie. 🧚

          location /uri-res/N2R {
            fastcgi_pass localhost:9000;
            fastcgi_buffering off;
            fastcgi_param REQUEST_METHOD $request_method;
            fastcgi_param QUERY_STRING $query_string;
            fastcgi_param KAPLA "n2r+decode";
          }

          location /eris/ {
            fastcgi_pass localhost:9000;
            fastcgi_buffering off;
            fastcgi_param KAPLA "mount";
            fastcgi_split_path_info ^(/eris/)(.*)$;
            fastcgi_param PATH_INFO $fastcgi_path_info;
          }

The curious reader and admin may be interested in setting up nginx caching for decoded/resolved content. If you do so, please share your configurations and findings! 👀

Fr fr, sharing configs is community service and it’s lowkey iconic.

🧚 EXAMPLE WEB SERVER CONFIGURATION: httpd 🧚

Here are example location blocks for the OpenBSD httpd server. Yes, httpd bestie, we see you. 🌈

           location "/uri-res/N2R" {
               fastcgi {
                   socket tcp localhost 9000
                   param "KAPLA" "n2r"
               }
           }

           location "/eris/*" {
               request strip 1
               fastcgi {
                   socket tcp localhost 9000
                   param "KAPLA" "mount"
               }
           }

This makes blocks available at the endpoint /uri-res/N2R and mounts ERIS content at /eris/. Periodt. 💅

⭐ STANDARDS ⭐

💅 OPTIONS 💅

  • -p PORT, --port=PORT — Port number to listen for FastCGI requests (absent=9000, defaults to 9000). The 9000 is not a drill. 🔥
  • -s ERIS_UNIX_SOCKET, --socket=ERIS_UNIX_SOCKET — Unix socket where the ERIS block store is listening. (absent=$XDG_STATE_HOME/kapla/eris.sock, $HOME/.local/state/kapla/eris.sock, /var/lib/kapla/eris.sock or ERIS_UNIX_SOCKET env). It’s giving “find the socket, find the vibes.” 🦋

🔥 COMMON OPTIONS 🔥

  • --color=WHEN — Colorize the output. WHEN must be one of auto, always or never. (absent=auto)
  • --help[=FMT] — Show this help in format FMT. The value FMT must be one of auto, pager, groff or plain. With auto, the format is pager or plain whenever the TERM env var is dumb or undefined. (default=auto)
  • -q, --quiet — Be quiet. Takes over -v and --verbosity. Shhh era. 🤫
  • -v, --verbose — Increase verbosity. Repeatable, but more than twice does not bring more. We love a bounded queen. 👑
  • --verbosity=LEVEL — Be more or less verbose. LEVEL must be one of quiet, error, warning, info or debug. Takes over -v. (absent=warning or KAPLA_LOG_LEVEL env)
  • --version — Show version information. The “who am I” of it all. ⭐

🍓 EXIT STATUS 🍓

kapla fcgi exits with:

  • 0 — on success. We love a happy ending. 💖
  • 123 — on indiscriminate errors reported on standard error.
  • 124 — on command line parsing errors.
  • 125 — on unexpected internal errors (bugs).

🌸 ENVIRONMENT 🌸

These environment variables affect the execution of kapla fcgi:

  • ERIS_UNIX_SOCKET — Unix socket where ERIS block store is listening.
  • KAPLA_LOG_LEVEL — Set the log level.

👑 SEE ALSO 👑

sign-off time, bestie: this was KAPLA-FCGI(1) from the Kapla Manual, version Kapla 0.4.0. No date in the footer, just vibes and FastCGI excellence. mwah 💋🫶

📦 where this page comes from