listeners: Add support for named socket activation

[Siomachkin]

This PR implements support for named socket activation in systemd, allowing users to reference sockets by name using fdname/name and fdgramname/name syntax instead of only numeric fd/N and fdgram/N references.

Solution Logic

The implementation uses an early normalization approach:

1. New function getFdByName() - reads systemd environment variable LISTEN_FDNAMES and maps socket names to file descriptor numbers

2. Extended ParseNetworkAddressWithDefaults() - detects fdname/ and fdgramname/ prefixes and converts them to standard fd/N and fdgram/N syntax internally

3. Backward compatibility - existing fd/N syntax continues to work unchanged

The conversion happens at parse time, so all downstream code continues to work with the standard fd syntax without modifications.

Testing Results

Unit Tests

• TestGetFdByName: 7 test cases covering environment variable parsing, multiple sockets, error handling
• TestParseNetworkAddressFdName: 9 test cases covering address parsing with both old and new syntax

Manual Testing

• Verified backward compatibility with fd/3 and fdgram/4 syntax
• Tested new fdname/http and fdgramname/dns syntax with environment variables
• Confirmed proper error handling for missing environment variables and invalid socket names

Usage Examples

Before (numeric references)

fd/3
fdgram/4

After (named references)

fdname/http
fdgramname/dns

Assistance Disclosure
I consulted Claude to understand the project architecture, but I authored/coded the fix myself

Resolves #6792

[francislavoie]

Hmm. I don't know much about socket activation (not something I've ever used/needed) but generally we try to avoid having configuration via env vars. Are you sure that's necessary? Why can't it be in the config itself?

[Siomachkin]

From the issue description:

"Systemd supports using multiple socket files for a single service, but does not define an ordering of the sockets between those socket files. Instead, systemd provides the names of the socket files within environment variables (LISTEN_FDS and LISTEN_FDNAMES combine to name the fds)."

Without LISTEN_FDNAMES, there's no way to know which FD number corresponds to which socket - the ordering is unpredictable. This follows the same pattern as systemd's standard sd_listen_fds_with_names() C function.

[codyps]

Referring to #6792 (comment), it's possible (even likely) to have multiple sockets with the same name by defining those sockets within the same systemd.socket file. The manual for sd_listen_fds_with_names() says: "Note that the names used are not unique in any way."

Additionally, the current sock activation pattern (using fd/N) exposes and requires uses the existence of multiple sockets in a systemd.socket file (but simply can't handle multiple socket files).

To fully support named socket activation, we need to be able to express to caddy the "index" of a socket with a given name.

The current impl in this PR always returns the first socket with a given name. To allow full utilization of named socket activation, it could be adjusted to provide a way to return the Nth socket with a given name.

[Siomachkin]

I've added full support for indexed named sockets. Now supports:

bind fdname/web        # first socket named "web" (default :0)
bind fdname/web:0      # same as above (explicit)
bind fdname/web:1      # second socket named "web"
bind fdgramname/dns:2  # third UDP socket named "dns"

[francislavoie]

Ah, so LISTEN_FDNAMES is a standard env var outside of Caddy? That's okay, then. I had the impression you were adding this as a way to configure Caddy specifically.

[eriksjolund]

This is just a matter of personal taste but I think the default syntax could be dropped

bind fdname/web        # first socket named "web" (default :0)

Intiutively, no number could also be understood as all sockets named "web".

I would instead always require a number when an fdname is provided.

[Siomachkin]

I prefer keeping the default for single sockets (fdname/web). In practice, I think socket files define one socket with a given name in most cases. Requiring :0 always would make the simple case unnecessarily verbose.

[francislavoie]

LGTM! Simple and narrow change, with tests. Thanks!

[MayCXC]

did you see http://github.com/MayCXC/caddy-systemd-socket-activation ? it supports the indices from systemd.socket. for this to go into main, I would like to take your test cases and use the implementation from the extension and add them to the _linux target. are you able to test that the extension works for you?