Add documentation to combinators

This adds structured documentation and signatures to all combinators. A
future commit will consume this to generate a documentation website.

But for now having the docs in the source code is helpful to anyone
viewing `combinators.nix`.
This commit is contained in:
Alex David 2025-06-07 12:28:44 -07:00
commit cb157b9dce
2 changed files with 517 additions and 108 deletions

13
lib.nix
View file

@ -4,16 +4,13 @@
exe-str = if builtins.typeOf exe == "string" then lib.escapeShellArg exe else lib.getExe exe;
helpers = rec {
escape = rawOrStr: if builtins.typeOf rawOrStr == "string" then lib.strings.escapeShellArg rawOrStr else rawOrStr.raw;
noescape = value: { raw = value; };
dataDir = "~/.local/share/jail.nix";
dataDirSubPath = subPath: "${dataDir}/${escape subPath}";
deprecatedCombinator = message: combinator: lib.warn "jail ${name}: ${message}" combinator;
dataDirSubPath = subPath: "${dataDir}/${combinators.escape subPath}";
};
combinators = import ./combinators.nix {
inherit pkgs lib helpers;
};
combinators = lib.mapAttrs
(_: v: v.impl combinators)
(import ./combinators.nix { inherit pkgs lib helpers; });
initial-state = {
cmd = "${lib.getExe pkgs.bubblewrap}";
@ -59,7 +56,7 @@ in lib.pipe initial-state (
# apply post-user combinators
++ (with combinators; [
(s:
# See `--unshare-*` from man bwrap
# See `--unshare-*` in BWRAP(1)
lib.pipe ["user" "ipc" "pid" "net" "uts" "cgroup"] [
(lib.filter (ns: !(s.namespaces.${ns} or false)))
(map (ns: "--unshare-${ns}"))