318d10e608
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>
68 lines
2 KiB
Markdown
68 lines
2 KiB
Markdown
# //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](../../nix/nint/README.md) 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):
|
|
|
|
```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
|
|
```
|