1c0f89f4ca
We can actually catch some errors that may be generated in bubblegum applications where we can report them to the user in a way that doesn't require curl -vv: * Type errors in the status argument: By removing yants completely we not only (presumably) gain some performance, but also the ability to return an internal server error on an unexpected type instead of throwing. * User generated evaluation errors: by using builtins.tryEval we can catch throws and asserts the user inserted when generating the body and report to the user that something went wrong. To do: also support for the headers. Change-Id: I8363b9825c6c730e624eb8016a5482d63cbc1890 Reviewed-on: https://cl.tvl.fyi/c/depot/+/2849 Tested-by: BuildkiteCI Reviewed-by: sterni <sternenseemann@systemli.org> |
||
---|---|---|
.. | ||
examples | ||
default.nix | ||
OWNERS | ||
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 //users/sterni/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