@schneems I think you should make tests fixes in its own branch/PR, so we can merge that independent of this PR!

I think you should make tests fixes in its own branch/PR, so we can merge that independent of this PR!

Done 💚

I'm not actually sure how large this change is. I had to adjust the tests to get it to pass for windows (switching from 127.0.0.1 to localhost) so it is a breaking change for some users, for sure, but I believe it's a small breaking change (if there is such a thing). To be on the safe side, this would be a minor at least (7.1 -> 7.2). If we were doing strict semver (we aren't) this would need to be (7.1 -> 8.0).

I'm not actually sure how large this change is.

Because it's a prod change, I'd prefer to mark this as a full breaking change.

he Rails issue notes there are ipv6-only hosts b/c it can be disabled at the kernel level. That definitely warrants breaking change to me, do we have any idea how often this occurs?

I've yet to find any sort of docker setup that reproduces that behavior. I believe it may exists, but given the difficulty to induce it makes me think the actual occurrence is small.

Currently this raises and dies with non-zero exit. Should we do something else?

Without a system to test against it’s hard to say. In the scenario where IPv6 isn’t available I’m unclear if it still binds to IPv4 and behaves like 0.0.0.0 or if it fully fails. It might also be OS dependent.

We could catch and retry with 0.0.0.0 as an option. I would ideally not want to do that unless the error was clear and we aren’t retrying for all socket binding failures.

As a parallel thought: We could also allow setting tcp host via env var PUMA_TCP_HOST or just PUMA_HOST. Though it would only help people using something like the buildpack and not others who are running on a machine that doesn't have an IPv4 network.

Maybe adding env var support for config makes it less risky as someone could put the old 0.0.0.0 in their dot files if it failed for them.

Adding a datapoint: I changed the Heroku docs for recommended puma config to use IPv6 November 22 of 2024. People leave feedback on articles, and I've not had any issues, granted these people are also likely using Heroku for prod, but I also know these docs show up in general search, and people sometimes copy and use them on other infrastructure. It's not an overwhelming signal that no one has complained, but it is a signal.

Tested how this change behaves in environments where IPv6 is partially or fully disabled:

1. IPv6 disabled partially (sysctl net.ipv6.conf.all.disable_ipv6 return 1)
   In this case, TCPServer.new('::', 9292) does not raise an error.
   The socket is created with AF_INET6 family. However, it only accepts IPv4 traffic.

The issue: Puma will log Listening on http://[::]:9292, but IPv6 connections will fail with "Can’t be reached". The logs will be misleading for users who expect real IPv6 connectivity.

In this case table for :: looks like this:

2. When the IPv6 kernel module is not loaded at all
   IPv6 disabled (sudo vim /etc/default/grub; GRUB_CMDLINE_LINUX_DEFAULT="... ipv6.disable=1")
   In this case, TCPServer.new('::', 9292) raises a fatal error:
   Errno::EAFNOSUPPORT (Address family not supported by protocol - socket(2) for "::" port 9292)
   This will break Puma startup for any user who relies on the default binding if their kernel has IPv6 disabled.

Suggestion: Perhaps checking for available IPv6 interfaces before deciding which address to bind to would help. For example:

has_real_ipv6 = Socket.getifaddrs.any? do |ifaddr|
  ifaddr.addr&.ipv6? && !ifaddr.addr&.ipv6_loopback?
end

Using this check (or a similar one) would allow Puma to:

Bind to 0.0.0.0 automatically if IPv6 is missing or disabled at the kernel level (partially or fully disabled), preventing startup crashes. Provide more accurate logging about which protocol is actually being used.

Codex speaking below.

Puma uses TCPServer.new(host, port) and does not set IPV6_V6ONLY, so behavior is inherited from the OS/kernel default for IPv6 sockets.

bind "tcp://[::]:PORT" can be either:

1. dual-stack (:: accepts both IPv6 and IPv4-mapped traffic) or
2. v6-only (:: accepts IPv6 only)

depending on platform/runtime configuration.

A few concrete data points:

• Windows docs for IPV6_V6ONLY say default is nonzero (v6-only):
  https://learn.microsoft.com/en-us/windows/win32/winsock/ipproto-ipv6-socket-options
• Linux ipv6(7) documents net.ipv6.bindv6only default 0 (dual-stack), but this is tunable:
  https://man7.org/linux/man-pages/man7/ipv6.7.html

I also reproduced the behavior with Ruby sockets:

• v6-only socket bound to :: rejects 127.0.0.1 with ECONNREFUSED
• same socket accepts ::1
• connecting to localhost succeeds (resolver picks a compatible address)

User impact

• Users who explicitly set bind/host are unaffected.
• Users relying on defaults may see tooling drift if local scripts/healthchecks hardcode 127.0.0.1.
  • e.g. curl http://127.0.0.1:$PORT may fail in v6-only environments
  • curl http://localhost:$PORT or curl http://[::1]:$PORT will still work

The new fallback in this PR (no non-loopback IPv6 interface => rewrite to 0.0.0.0) helps with the "IPv6 absent" case, but not with the dual-stack-vs-v6-only semantic differences when IPv6 exists.

This is manageable as a breaking-change note: if someone depends on IPv4 loopback checks, they should either use localhost/[::1] or set an explicit IPv4 bind.

i fail to see the purpose here. are people using puma on public addresses directly instead of behind proxies?

@glaszig

are people using puma on public addresses directly instead of behind proxies?

README.md:

With SSL support, zero-downtime rolling restarts and a built-in request bufferer, you can deploy Puma without any reverse proxy.

I believe it is an intended use case.