depot/lib/fetchers.nix

# snippets that can be shared by multiple fetchers (pkgs/build-support)
{ lib }:
let
  commonH = hashTypes: rec {
    hashNames = [ "hash" ] ++ hashTypes;
    hashSet = lib.genAttrs hashNames (lib.const { });
  };

  fakeH = {
    hash = lib.fakeHash;
    sha256 = lib.fakeSha256;
    sha512 = lib.fakeSha512;
  };
in
rec {

  proxyImpureEnvVars = [
    # We borrow these environment variables from the caller to allow
    # easy proxy configuration.  This is impure, but a fixed-output
    # derivation like fetchurl is allowed to do so since its result is
    # by definition pure.
    "http_proxy"
    "https_proxy"
    "ftp_proxy"
    "all_proxy"
    "no_proxy"
    "HTTP_PROXY"
    "HTTPS_PROXY"
    "FTP_PROXY"
    "ALL_PROXY"
    "NO_PROXY"

    # https proxies typically need to inject custom root CAs too
    "NIX_SSL_CERT_FILE"
  ];

  /**
    Converts an attrset containing one of `hash`, `sha256` or `sha512`,
    into one containing `outputHash{,Algo}` as accepted by `mkDerivation`.

    An appropriate “fake hash” is substituted when the hash value is `""`,
    as is the [convention for fetchers](#sec-pkgs-fetchers-updating-source-hashes-fakehash-method).

    All other attributes in the set remain as-is.

    # Example

    ```nix
    normalizeHash { } { hash = ""; foo = "bar"; }
    =>
    {
      outputHash = lib.fakeHash;
      outputHashAlgo = null;
      foo = "bar";
    }
    ```

    ```nix
    normalizeHash { } { sha256 = lib.fakeSha256; }
    =>
    {
      outputHash = lib.fakeSha256;
      outputHashAlgo = "sha256";
    }
    ```

    ```nix
    normalizeHash { } { sha512 = lib.fakeSha512; }
    =>
    {
      outputHash = lib.fakeSha512;
      outputHashAlgo = "sha512";
    }
    ```

    # Type
    ```
    normalizeHash :: { hashTypes :: List String, required :: Bool } -> AttrSet -> AttrSet
    ```

    # Arguments

    hashTypes
    : the set of attribute names accepted as hash inputs, in addition to `hash`

    required
    : whether to throw if no hash was present in the input; otherwise returns the original input, unmodified
  */
  normalizeHash =
    {
      hashTypes ? [ "sha256" ],
      required ? true,
    }:
    let
      inherit (lib)
        concatMapStringsSep
        head
        tail
        throwIf
        ;
      inherit (lib.attrsets)
        attrsToList
        intersectAttrs
        removeAttrs
        optionalAttrs
        ;

      inherit (commonH hashTypes) hashNames hashSet;
    in
    args:
    if args ? "outputHash" then
      args
    else
      let
        # The argument hash, as a {name, value} pair
        h =
          # All hashes passed in arguments (possibly 0 or >1) as a list of {name, value} pairs
          let
            hashesAsNVPairs = attrsToList (intersectAttrs hashSet args);
          in
          if hashesAsNVPairs == [ ] then
            throwIf required "fetcher called without `hash`" null
          else if tail hashesAsNVPairs != [ ] then
            throw "fetcher called with mutually-incompatible arguments: ${
              concatMapStringsSep ", " (a: a.name) hashesAsNVPairs
            }"
          else
            head hashesAsNVPairs;
      in
      removeAttrs args hashNames
      // (optionalAttrs (h != null) {
        outputHashAlgo = if h.name == "hash" then null else h.name;
        outputHash =
          if h.value == "" then
            fakeH.${h.name} or (throw "no “fake hash” defined for ${h.name}")
          else
            h.value;
      });

  /**
    Wraps a function which accepts `outputHash{,Algo}` into one which accepts `hash` or `sha{256,512}`

    # Example
    ```nix
    withNormalizedHash { hashTypes = [ "sha256" "sha512" ]; } (
      { outputHash, outputHashAlgo, ... }:
      ...
    )
    ```
    is a function which accepts one of `hash`, `sha256`, or `sha512` (or the original's `outputHash` and `outputHashAlgo`).

    Its `functionArgs` metadata only lists `hash` as a parameter, optional iff. `outputHash` was an optional parameter of
    the original function.  `sha256`, `sha512`, `outputHash`, or `outputHashAlgo` are not mentioned in the `functionArgs`
    metadata.

    # Type
    ```
    withNormalizedHash :: { hashTypes :: List String } -> (AttrSet -> T) -> (AttrSet -> T)
    ```

    # Arguments

    hashTypes
    : the set of attribute names accepted as hash inputs, in addition to `hash`
    : they must correspond to a valid value for `outputHashAlgo`, currently one of: `md5`, `sha1`, `sha256`, or `sha512`.

    f
    : the function to be wrapped

    ::: {.note}
    In nixpkgs, `mkDerivation` rejects MD5 `outputHash`es, and SHA-1 is being deprecated.

    As such, there is no reason to add `md5` to `hashTypes`, and
    `sha1` should only ever be included for backwards compatibility.
    :::

    # Output

    `withNormalizedHash { inherit hashTypes; } f` is functionally equivalent to
    ```nix
    args: f (normalizeHash {
      inherit hashTypes;
      required = !(lib.functionArgs f).outputHash;
    } args)
    ```

    However, `withNormalizedHash` preserves `functionArgs` metadata insofar as possible,
    and is implemented somewhat more efficiently.
  */
  withNormalizedHash =
    {
      hashTypes ? [ "sha256" ],
    }:
    fetcher:
    let
      inherit (lib.attrsets) genAttrs intersectAttrs removeAttrs;
      inherit (lib.trivial) const functionArgs setFunctionArgs;

      inherit (commonH hashTypes) hashSet;
      fArgs = functionArgs fetcher;

      normalize = normalizeHash {
        inherit hashTypes;
        required = !fArgs.outputHash;
      };
    in
    # The o.g. fetcher must *only* accept outputHash and outputHashAlgo
    assert fArgs ? outputHash && fArgs ? outputHashAlgo;
    assert intersectAttrs fArgs hashSet == { };

    setFunctionArgs (args: fetcher (normalize args)) (
      removeAttrs fArgs [
        "outputHash"
        "outputHashAlgo"
      ]
      // {
        hash = fArgs.outputHash;
      }
    );
}