From 731ba22f6077e6e1d3202ee55f5fa41bcadd3ee1 Mon Sep 17 00:00:00 2001 From: Alex David Date: Tue, 14 Apr 2026 22:23:19 -0700 Subject: [PATCH] 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. --- lib/combinators.nix | 22 ++++++++++++++----- lib/jail.nix | 5 +++-- tests/spec/TestPrelude.hs | 4 ++-- website/flake.nix | 20 +++++++++++++++-- website/static-docs/advanced-configuration.md | 6 +++++ 5 files changed, 45 insertions(+), 12 deletions(-) diff --git a/lib/combinators.nix b/lib/combinators.nix index ec0e1f4..bb65039 100644 --- a/lib/combinators.nix +++ b/lib/combinators.nix @@ -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; diff --git a/lib/jail.nix b/lib/jail.nix index 84edc45..26ffb43 100644 --- a/lib/jail.nix +++ b/lib/jail.nix @@ -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; diff --git a/tests/spec/TestPrelude.hs b/tests/spec/TestPrelude.hs index d96e0e7..e562393 100644 --- a/tests/spec/TestPrelude.hs +++ b/tests/spec/TestPrelude.hs @@ -158,7 +158,7 @@ runNixDrvWithinVm vmConfig nixDrvExpr = do }; script = let jail-nix = import {}; - 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 = jail-nix.extend { inherit pkgs; }; + jail = jail-nix.extend { inherit pkgs; suppressExperimentalWarnings = true; }; in #{nixExpr} |] liftIO $ diff --git a/website/flake.nix b/website/flake.nix index 5bca6a6..6995070 100644 --- a/website/flake.nix +++ b/website/flake.nix @@ -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 = { diff --git a/website/static-docs/advanced-configuration.md b/website/static-docs/advanced-configuration.md index b8a4266..41d7444 100644 --- a/website/static-docs/advanced-configuration.md +++ b/website/static-docs/advanced-configuration.md @@ -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.