Clean up combinator/permission naming

The term `combinator` was overloaded before, being used to refer both to
the functions that are exposed to help build a jail, and their return
value to be passed into `jail`/`basePermissions`. This commit renames
the latter to `Permission`.
This commit is contained in:
Alex David 2025-08-07 15:42:36 -07:00
commit 09edd097b9
4 changed files with 60 additions and 51 deletions

View file

@ -45,6 +45,15 @@
(docs: ''
# Combinators
jail.nix combinators are the building blocks to create `Permission`s,
which grant a program specific permissions at runtime.
These permissions can be passed into the third argument to `jail`
funciton, as well as
[`basePermissions`](../advanced-configuration/#basepermissions).
---
${docs}
'')
];

View file

@ -8,30 +8,30 @@ All configuration options on this page can be passed into `jail-nix.lib.extend`.
`jail.combinators` and in jail definitions. If passed a funciton, jail.nix will
inject the builtin combinators.
For example, this creates a `jail` function that exposes a `my-combinator`
For example, this creates a `jail` function that exposes a `my-permission`
combinator:
```nix
jail = jail-nix.lib.extend {
inherit pkgs;
additionalCombinators = builtinCombinators: with builtinCombinators; [
my-combinator = compose [
my-permission = compose [
(readonly "/foo")
(readonly "/bar")
];
];
};
# Now my-combinator is exposed in all the places the builtin combinators are exposed:
# Now my-permission is exposed in all the places the builtin combinators are exposed:
jailed-hello = jail "jailed-hello" pkgs.hello (c: with c; [
my-combinator
my-permission
]);
# Alternatively, using jail.combinators:
jailed-hello = jail "jailed-hello" pkgs.hello [
jail.combinators.my-combinator
jail.combinators.my-permission
];
```

View file

@ -66,7 +66,7 @@ following positional arguments:
be a derivation like `pkgs.hello`, or a string like
`"${pkgs.hello}/bin/hello"`. If a derivation is passed it will call
`nixpkgs.lib.getExe` on it to get the entrypoint.
* **combinators**: (List of **Combinators**) - The third argument allows you to
* **permissions**: (List of **Permissions**) - The third argument allows you to
control the permissions of the jail. By default, the wrapped program runs
with very few permissions and to get it to even work you will need to define
what you want it to have access to here. For convenience, if this argument is