mdebray/tvl-depot
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
tvl-depot/web/bubblegum/README.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

69 lines
2 KiB
Markdown
Raw Normal View History

feat(web/bubblegum): nix CGI programming framework So here is what has been keeping me up at night: At some point I realized that nix actually made a somewhat passable language for CGI programming: * That `builtins.getEnv` exists as one of the impurities of Nix is perfect as environment variables are the main way of communication from the web server to the CGI application. * We can actually read from the filesystem via builtins.readDir and builtins.readFile with bearable overhead if we avoid importing the used paths into the nix store. * Templating and routing are convenient to implement via indented strings and attribute sets respectively. Of course there are obvious limitation: * The overhead of derivations is probably much to great for them to be useful via IfD. * Even without derivations, nix evaluation is very slow to the point were a trivial application takes between 100ms and 400ms to produce a response. * We can't really cause effects other than producing a response which makes it not viable for a lot of applications. There are some ways around this: * With a custom interpreter we could have streaming and multiplexed I/O (using lazy lists emulated via attrsets) to cause such effects, but it would probably perform terribly. * We can use builtins.fetchurl to call other HTTP-based microservices, but only in very limited constraints, i. e. only GET, no headers, and only if the tarball ttl is set to 0 in the global nix.conf. * Terrible error handling capabilities because builtins.tryEval actually doesn't catch a lot of errors. To prove that it actually works, there are some demo applications, which I invite you to run and potentially break horribly: nix-build -A web.bubblegum.examples && ./result # navigate to http://localhost:9000 The setup uses thttpd and executes the nix CGI scripts using users.sterni.nint which automatically passed `depot`, so they can import the cgi library. Change-Id: I3a22a749612211627e5f8301c31ec2e7a872812c Reviewed-on: https://cl.tvl.fyi/c/depot/+/2746 Tested-by: BuildkiteCI Reviewed-by: tazjin <mail@tazj.in>
2021-02-21 12:57:40 +01:00
# //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
chore(nint): move from //users/sterni to //nix Since //web/bubblegum depends on nint, we need to move it to a non user directory to conform with the policy established via cl/3434. Note that this likely doesn't mean greater stability (which isn't really implied in depot anyways), since I still would like to use a more elaborate calling convention to allow for additional useful features. Change-Id: I616f905d8df13e3363674aab69a797b0d39fdd79 Reviewed-on: https://cl.tvl.fyi/c/depot/+/3506 Tested-by: BuildkiteCI Reviewed-by: tazjin <mail@tazj.in>
2021-09-09 18:26:03 +02:00
using [//nix/nint](../../nix/nint/README.md) convenient.
feat(web/bubblegum): nix CGI programming framework So here is what has been keeping me up at night: At some point I realized that nix actually made a somewhat passable language for CGI programming: * That `builtins.getEnv` exists as one of the impurities of Nix is perfect as environment variables are the main way of communication from the web server to the CGI application. * We can actually read from the filesystem via builtins.readDir and builtins.readFile with bearable overhead if we avoid importing the used paths into the nix store. * Templating and routing are convenient to implement via indented strings and attribute sets respectively. Of course there are obvious limitation: * The overhead of derivations is probably much to great for them to be useful via IfD. * Even without derivations, nix evaluation is very slow to the point were a trivial application takes between 100ms and 400ms to produce a response. * We can't really cause effects other than producing a response which makes it not viable for a lot of applications. There are some ways around this: * With a custom interpreter we could have streaming and multiplexed I/O (using lazy lists emulated via attrsets) to cause such effects, but it would probably perform terribly. * We can use builtins.fetchurl to call other HTTP-based microservices, but only in very limited constraints, i. e. only GET, no headers, and only if the tarball ttl is set to 0 in the global nix.conf. * Terrible error handling capabilities because builtins.tryEval actually doesn't catch a lot of errors. To prove that it actually works, there are some demo applications, which I invite you to run and potentially break horribly: nix-build -A web.bubblegum.examples && ./result # navigate to http://localhost:9000 The setup uses thttpd and executes the nix CGI scripts using users.sterni.nint which automatically passed `depot`, so they can import the cgi library. Change-Id: I3a22a749612211627e5f8301c31ec2e7a872812c Reviewed-on: https://cl.tvl.fyi/c/depot/+/2746 Tested-by: BuildkiteCI Reviewed-by: tazjin <mail@tazj.in>
2021-02-21 12:57:40 +01:00
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):
```nix
#!/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](./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](./examples). You can also start a local
server running the examples like this:
```
$ nix-build -A web.bubblegum.examples && ./result
# navigate to http://localhost:9000
```
Reference in a new issue Copy permalink