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
inherit (pkgs) lib;
helpers = import ./helpers.nix pkgs;
@ -21,21 +26,26 @@ let
combinators =
let
foldCombinator =
acc: names: combinatorImpl:
acc: names: combinator:
if lib.length names == 0 then
acc
else
let
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
if acc ? ${name} then
throw "duplicate combinator ${name}"
else
foldCombinator (acc // { ${name} = combinatorImpl; }) (lib.tail names) combinatorImpl;
foldCombinator (acc // { ${name} = combinatorImpl; }) (lib.tail names) combinator;
in
lib.foldl' (
acc: { name, value }: foldCombinator acc ([ name ] ++ value.aliases or [ ]) value.impl
) { } (lib.attrsToList rawCombinators);
lib.foldl' (acc: { name, value }: foldCombinator acc ([ name ] ++ value.aliases or [ ]) value) { } (
lib.attrsToList rawCombinators
);
in
{
inherit combinators;

View file

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

View file

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

View file

@ -51,7 +51,9 @@
combinatorDocs =
let
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 =
filter:
@ -82,7 +84,7 @@
${hr}
${formatSection (v: !(is "includedInBasePermissions" v || is "internal" v))}
${formatSection (v: !(is "includedInBasePermissions" v || is "internal" v || is "experimental" v))}
${hr}
@ -93,6 +95,20 @@
`basePermissions`](advanced-configuration.md#basepermissions).
${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 = {

View file

@ -76,3 +76,9 @@ jail = jail-nix.lib.extend {
This configuration option allows you to override what bubblewrap package
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.