Add experimental combinator handling

I have a few combinator ideas that I'd like to try adding but I still
haven't fully fleshed them out yet. In order to reduce breaking people's
setup, this introduces a new `experimental` flag on combinators that
separates them on the docs website to let users know that their design
may not be fully finalized yet.
This commit is contained in:
Alex David 2026-04-14 22:23:19 -07:00
commit 731ba22f60
5 changed files with 45 additions and 12 deletions

View file

@ -1,4 +1,9 @@
pkgs: jail: {
pkgs,
suppressExperimentalWarnings ? false,
...
}:
jail:
let let
inherit (pkgs) lib; inherit (pkgs) lib;
helpers = import ./helpers.nix pkgs; helpers = import ./helpers.nix pkgs;
@ -21,21 +26,26 @@ let
combinators = combinators =
let let
foldCombinator = foldCombinator =
acc: names: combinatorImpl: acc: names: combinator:
if lib.length names == 0 then if lib.length names == 0 then
acc acc
else else
let let
name = lib.head names; name = lib.head names;
combinatorImpl =
if combinator.experimental or false && !suppressExperimentalWarnings then
builtins.warn "jail.nix combinator ${name} is experimental!" combinator.impl
else
combinator.impl;
in in
if acc ? ${name} then if acc ? ${name} then
throw "duplicate combinator ${name}" throw "duplicate combinator ${name}"
else else
foldCombinator (acc // { ${name} = combinatorImpl; }) (lib.tail names) combinatorImpl; foldCombinator (acc // { ${name} = combinatorImpl; }) (lib.tail names) combinator;
in in
lib.foldl' ( lib.foldl' (acc: { name, value }: foldCombinator acc ([ name ] ++ value.aliases or [ ]) value) { } (
acc: { name, value }: foldCombinator acc ([ name ] ++ value.aliases or [ ]) value.impl lib.attrsToList rawCombinators
) { } (lib.attrsToList rawCombinators); );
in in
{ {
inherit combinators; inherit combinators;

View file

@ -1,13 +1,14 @@
{ jailNixCfg@{
pkgs, pkgs,
additionalCombinators ? _: { }, additionalCombinators ? _: { },
basePermissions ? import ./base-permissions.nix pkgs, basePermissions ? import ./base-permissions.nix pkgs,
bubblewrapPackage ? pkgs.bubblewrap, bubblewrapPackage ? pkgs.bubblewrap,
...
}: }:
let let
inherit (pkgs) lib; inherit (pkgs) lib;
builtinCombinators = (import ./combinators.nix pkgs jail).combinators; builtinCombinators = (import ./combinators.nix jailNixCfg jail).combinators;
allCombinators = builtinCombinators // additionalCombinators builtinCombinators; allCombinators = builtinCombinators // additionalCombinators builtinCombinators;

View file

@ -158,7 +158,7 @@ runNixDrvWithinVm vmConfig nixDrvExpr = do
}; };
script = let script = let
jail-nix = import <jail-nix> {}; jail-nix = import <jail-nix> {};
jail = jail-nix.extend { inherit pkgs; }; jail = jail-nix.extend { inherit pkgs; suppressExperimentalWarnings = true; };
testToRun = #{nixDrvExpr}; testToRun = #{nixDrvExpr};
in '' in ''
( (
@ -204,7 +204,7 @@ evalNixExpr nixExpr = do
lib = pkgs.lib; lib = pkgs.lib;
sh = script: (pkgs.writeShellApplication { name = "test-script"; text = script; }); sh = script: (pkgs.writeShellApplication { name = "test-script"; text = script; });
jail-nix = import <jail-nix> {}; jail-nix = import <jail-nix> {};
jail = jail-nix.extend { inherit pkgs; }; jail = jail-nix.extend { inherit pkgs; suppressExperimentalWarnings = true; };
in #{nixExpr} in #{nixExpr}
|] |]
liftIO $ liftIO $

View file

@ -51,7 +51,9 @@
combinatorDocs = combinatorDocs =
let let
allCombinators = allCombinators =
(import (docsFileSet + /lib/combinators.nix) pkgs (throw "Docs must not depend on jail arg")).docs; (import (docsFileSet + /lib/combinators.nix) { inherit pkgs; } (
throw "Docs must not depend on jail arg"
)).docs;
formatSection = formatSection =
filter: filter:
@ -82,7 +84,7 @@
${hr} ${hr}
${formatSection (v: !(is "includedInBasePermissions" v || is "internal" v))} ${formatSection (v: !(is "includedInBasePermissions" v || is "internal" v || is "experimental" v))}
${hr} ${hr}
@ -93,6 +95,20 @@
`basePermissions`](advanced-configuration.md#basepermissions). `basePermissions`](advanced-configuration.md#basepermissions).
${formatSection (is "includedInBasePermissions")} ${formatSection (is "includedInBasePermissions")}
${hr}
## Experimental Combinators
The following combinators are experimental, and may be removed, or
have breaking changes in the future. Please reach out if you have any
feedback on them.
Using these combinators will emit an evaluation warning, you can
suppress this warning with
[suppressExperimentalWarnings](advanced-configuration.md#suppressexperimentalwarnings).
${formatSection (is "experimental")}
''; '';
mkdocsSettings = { mkdocsSettings = {

View file

@ -76,3 +76,9 @@ jail = jail-nix.lib.extend {
This configuration option allows you to override what bubblewrap package This configuration option allows you to override what bubblewrap package
jail.nix uses for its jails. The default value is `pkgs.bubblewrap`. jail.nix uses for its jails. The default value is `pkgs.bubblewrap`.
## suppressExperimentalWarnings
By default, jail.nix will emit an evaluation warning if you use an
[experimental combinator](combinators.md#experimental-combinators). Setting
this to true suppresses these warnings.