firefox: add handlers.json configuration

[kugland]

Description

Adds support for configuring Firefox's handlers.json file to manage MIME type and URL scheme handlers declaratively (at programs.firefox.profiles.<profile>.handlers). Handlers control how Firefox opens files and protocols (e.g., PDF viewers, mailto handlers).

The implementation validates handler configurations and generates properly formatted JSON output. Includes comprehensive test coverage for edge cases and assertions.

Checklist

• Change is backwards compatible.

• Code formatted with nix fmt or
  nix-shell -p treefmt nixfmt deadnix keep-sorted --run treefmt.

• Code tested through nix run .#tests -- test-all or
  nix-shell --pure tests -A run.all.

• Test cases updated/added. See example.

• Commit messages are formatted like

  {component}: {description}
  
  {long description}
  

  See CONTRIBUTING for more information and recent commit messages for examples.

• If this PR adds a new module

  • Added myself as module maintainer. See example.
  • Generate a news entry. See News
  • Basic tests added. See Tests

• If this PR adds an exciting new feature or contains a breaking change.

  • Generate a news entry. See News

[Copilot]

Pull request overview

This PR adds declarative configuration support for Firefox's handlers.json file, enabling users to manage MIME type and URL scheme handlers through Home Manager. This complements existing Firefox profile configuration options like bookmarks, search engines, and extensions.

Key Changes

• New programs.firefox.profiles.<profile>.handlers option for declarative handler configuration
• Validation logic to ensure handlers are only used with appropriate action values
• Comprehensive test coverage including edge cases (empty handlers, multiple handlers, validation failures)

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
modules/programs/firefox/profiles/handlers.nix	Core module implementation defining handler options, validation logic, and JSON generation
modules/programs/firefox/mkFirefoxModule.nix	Integration of handlers option into profile configuration and assertion/file generation
tests/modules/programs/firefox/profiles/handlers/default.nix	Basic functionality test with MIME types and URL schemes
tests/modules/programs/firefox/profiles/handlers/multiple-handlers.nix	Test for multiple handlers per MIME type/scheme
tests/modules/programs/firefox/profiles/handlers/empty-handler.nix	Test for empty handler objects (no default handler)
tests/modules/programs/firefox/profiles/handlers/handlers-without-action.nix	Validation test ensuring handlers require action=2
tests/modules/programs/firefox/profiles/handlers/both-path-and-uri.nix	Validation test ensuring mutual exclusivity of path and uriTemplate
tests/modules/programs/firefox/profiles/handlers/expected-*.json	Expected JSON output for test assertions
tests/modules/programs/firefox/common.nix	Test registration for new handler tests
modules/misc/news/2025/12/2025-12-10_04-15-59.nix	User-facing announcement of new feature

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[kugland]

Closes #5617

[teto]

what happens in firefox when there are several handlers ? Does it ask the user to choose ?

[kugland]

If ask = true, yes. If it’s not, it goes with the first handler.

[teto]

could be a nice addition. How is this different than setting the policies as shown in this comment #5617 (comment) ?

[kugland]

could be a nice addition. How is this different than setting the policies as shown in this comment #5617 (comment) ?

This is per profile, and it does sanity checking with the config; policies are global and are not checked.

Furthermore, Home Manager currently has programs.firefox.profiles.<name>.bookmarks, programs.firefox.profiles.<name>.containers and programs.firefox.profiles.<name>.search, all of which can be set through policies also.

[khaneliman]

Not a fan of how much manual work is done in the module that limits the possible configuration for what amounts to a basic generator option to create a json file. I'd MUCH rather simplify everything to reduce maintenance burden and increase freedom.

There are many examples of how this is done throughout the repo, at this point. We can leverage submodules with freeformTypes and options to guide a user, but make sure to think forward and what could be and not what the state is now.