History

sterni e7c0d6eb12 refactor(web/bubblegum): avoid dumping depot into store cleanSource needs to import the path into store which is quite slow at this point. Since we are filtering the path later anyways, using the original path is probably perfectly fine and speeds up builds (which is nice when iterating on something). Change-Id: I0628854d754b5903eb4ae93a3c3e2539b2c1c7e9 Reviewed-on: https://cl.tvl.fyi/c/depot/+/3705 Tested-by: BuildkiteCI Reviewed-by: tazjin <mail@tazj.in>		2021-10-10 10:03:03 +00:00
..
examples	fix(bubblegum): import lib from the new correct place	2021-04-20 08:42:58 +00:00
default.nix	refactor(web/bubblegum): avoid dumping depot into store	2021-10-10 10:03:03 +00:00
OWNERS	chore(web/bubblegum): add OWNERS file	2021-04-01 22:05:31 +00:00
README.md	chore(nint): move from //users/sterni to //nix	2021-09-10 11:08:03 +00:00

README.md

//web/bubblegum

bubblegum is a CGI programming library for the Nix expression language. It provides a few helpers to make writing CGI scripts which are executable using //nix/nint convenient.

An example nix.cgi script looks like this (don't worry about the shebang too much, you can use web.bubblegum.writeCGI to set this up without thinking twice):

#!/usr/bin/env nint --arg depot '(import /path/to/depot {})'
{ depot, ... }:

let
  inherit (depot.web.bubblegum)
    respond
    ;
in

respond "OK" {
  "Content-type" = "text/html";
  # further headers…
} ''
  <!doctype html>
  <html>
    <head>
      <meta charset="utf-8">
      <title>hello world</title>
    </head>
    <body>
      hello world!
    </body>
  </html>
''

As you can see, the core component of bubblegum is the respond function which takes three arguments:

The response status as the textual representation which is also returned to the client in the HTTP protocol, e. g. "OK", "Not Found", "Bad Request", …
An attribute set mapping header names to header values to be sent.
The response body as a string.

Additionally it exposes a few helpers for working with the CGI environment like pathInfo which is a wrapper around builtins.getEnv "PATH_INFO". The documentation for all exposed helpers is inlined in default.nix (you should be able to use nixdoc to render it).

For deployment purposes it is recommended to use writeCGI which takes a nix CGI script in the form of a derivation, path or string and builds an executable nix CGI script which has the correct shebang set and is automatically passed a version of depot from the nix store, so the script has access to the bubblegum library.

For example nix CGI scripts and a working deployment using thttpd see the examples directory. You can also start a local server running the examples like this:

$ nix-build -A web.bubblegum.examples && ./result
# navigate to http://localhost:9000