nixpkgs/docs/reference/functions.md

Library Functions

Documentation for library functions available in m3ta-nixpkgs.

Overview

The library provides helper functions for your NixOS and Home Manager configurations.

Available Libraries

m3ta-lib.ports

Port management utilities for managing service ports across hosts.

Port Management Functions

mkPortHelpers

Create port helper functions from a ports configuration.

Signature

mkPortHelpers :: portsConfig -> portHelpers

Arguments

portsConfig - An attribute set with structure:

{
  ports = { service-name = port-number; ... };
  hostPorts = { hostname = { service-name = port-number; ... }; ... };
}

Returns

An attribute set containing helper functions:

{
  getPort = service: host -> port-number-or-null;
  getHostPorts = host -> ports-attrs;
  listServices = -> [string];
}

Usage

{config, inputs, ...}: let
  m3taLib = inputs.m3ta-nixpkgs.lib.${config.system};

  myPorts = {
    ports = {
      nginx = 80;
      grafana = 3000;
    };
    hostPorts = {
      laptop = {
        nginx = 8080;
      };
    };
  };

  portHelpers = m3taLib.ports.mkPortHelpers myPorts;
in {
  # Get port with host override
  services.nginx.port = portHelpers.getPort "nginx" config.networking.hostName;

  # Get all ports for host
  laptopPorts = portHelpers.getHostPorts "laptop";

  # List all services
  allServices = portHelpers.listServices;
}

getPort (from portHelpers)

Get port for a service, with optional host-specific override.

Signature

getPort :: string -> string -> int-or-null

Arguments

1. service - The service name (string)
2. host - The hostname (string), or null for default

Returns

Port number (int) or null if service not found.

Usage

services.nginx = {
  port = portHelpers.getPort "nginx" "laptop";  # Returns host-specific port
  # or
  port = portHelpers.getPort "nginx" null;     # Returns default port
};

getHostPorts (from portHelpers)

Get all ports for a specific host (merges defaults with host overrides).

Signature

getHostPorts :: string -> attrs

Arguments

1. host - The hostname (string)

Returns

Attribute set of all ports for the host.

Usage

laptopPorts = portHelpers.getHostPorts "laptop";
# Returns: { nginx = 8080; grafana = 3000; prometheus = 9090; ... }

listServices (from portHelpers)

List all defined service names.

Signature

listServices :: -> [string]

Returns

List of service names (strings).

Usage

allServices = portHelpers.listServices;
# Returns: ["nginx" "grafana" "prometheus" "homepage"]

getDefaultPort

Simple helper to get a port without host override.

Signature

getDefaultPort :: portsConfig -> string -> int-or-null

Arguments

1. portsConfig - Same structure as mkPortHelpers
2. service - The service name (string)

Returns

Port number (int) or null if service not found.

Usage

services.my-service = {
  port = m3taLib.ports.getDefaultPort myPorts "my-service";
};

Using Library Functions

Importing

{config, inputs, ...}: let
  # Import library
  m3taLib = inputs.m3ta-nixpkgs.lib.${config.system};
in {
  # Use library functions
}

Example: Custom Port Management

{config, inputs, ...}: let
  m3taLib = inputs.m3ta-nixpkgs.lib.${config.system};

  myPorts = {
    ports = {
      web = 80;
      api = 8080;
      db = 5432;
    };
    hostPorts = {
      dev = {
        web = 8080;
        api = 8081;
      };
    };
  };

  portHelpers = m3taLib.ports.mkPortHelpers myPorts;

  hostname = config.networking.hostName;
in {
  services.nginx = {
    enable = true;
    virtualHosts.${hostname} = {
      locations."/" = {
        proxyPass = "http://localhost:${toString (portHelpers.getPort "api" hostname)}";
      };
    };
  };

  services.postgresql = {
    enable = true;
    port = portHelpers.getPort "db" hostname;
  };
}

Example: Generate Config Files

{inputs, ...}: let
  m3taLib = inputs.m3ta-nixpkgs.lib.${system};

  myPorts = {
    ports = {
      service1 = 3000;
      service2 = 3001;
    };
  };

  portHelpers = m3taLib.ports.mkPortHelpers myPorts;
in {
  environment.etc."ports.toml".text = generators.toTOML {} {
    services = portHelpers.getHostPorts "desktop";
  };
}

Function Reference Summary

Function	Purpose	Return Type
mkPortHelpers	Create port helper functions	portHelpers attrs
getPort	Get port with optional host override	int or null
getHostPorts	Get all ports for host	attrs
listServices	List all service names	[string]
getDefaultPort	Get default port only	int or null

Related

• Port Management Guide - Detailed usage guide
• NixOS Ports Module - Port management module
• Home Manager Ports Module - User-level port management
• Architecture - Understanding library functions