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

```nix
mkPortHelpers :: portsConfig -> portHelpers
```

#### Arguments

`portsConfig` - An attribute set with structure:

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

#### Returns

An attribute set containing helper functions:

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

#### Usage

```nix
{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

```nix
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

```nix
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

```nix
getHostPorts :: string -> attrs
```

#### Arguments

1. `host` - The hostname (string)

#### Returns

Attribute set of all ports for the host.

#### Usage

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

### `listServices` (from portHelpers)

List all defined service names.

#### Signature

```nix
listServices :: -> [string]
```

#### Returns

List of service names (strings).

#### Usage

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

### `getDefaultPort`

Simple helper to get a port without host override.

#### Signature

```nix
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

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

## Using Library Functions

### Importing

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

### Example: Custom Port Management

```nix
{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

```nix
{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](../guides/port-management.md) - Detailed usage guide
- [NixOS Ports Module](../modules/nixos/ports.md) - Port management module
- [Home Manager Ports Module](../modules/home-manager/ports.md) - User-level port management
- [Architecture](../ARCHITECTURE.md) - Understanding library functions