Map port conflict on start error into a known error

[mdegat01]

Proposed change

Port conflict errors between addons happen fairly frequently. This is when an addon tries to start and bind to the port the user listed in the config and fails because something has already bound that port. This shows up a lot in sentry for a variety of reasons:

1. The user installed a different version of the same addon (dev, beta, stable) and expected the same config to just work but both then use the same port
2. User accidentally listed the same port on multiple addons or multiple addons defaulted to the same port
3. User had no idea something was already bound to a particular port because that something was Home Assistant, a plugin or an addon running on host network. None of which clearly enumerate what ports they use in the UI

The common request here is to handle this with static checking on save of the config. Unfortunately 3 above makes this impossible. Particularly the addons running on host network case as those do not clearly list their ports anywhere, the service can just bind to them as needed in code.

The best we can do is return a known and well-described error to the user that makes it very clear that a port conflict was the issue and what port is the problem.

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New feature (which adds functionality to the supervisor)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

• This PR fixes or closes issue: fixes Process port conflicts on container start in a user friendly way #6312
• This PR is related to issue:
• Link to documentation pull request:
• Link to cli pull request:
• Link to client library pull request:

Checklist

• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• I have followed the development checklist
• The code has been formatted using Ruff (ruff format supervisor tests)
• Tests have been added to verify that the new code works.

If API endpoints or add-on configuration are added/changed:

• Documentation added/updated for developers.home-assistant.io
• CLI updated (if necessary)
• Client library updated (if necessary)

[mdegat01]

To answer some likely questions in advance:

1. Why is observer in here?

It's the only plugin that does not run on host and binds to a port. Its incredibly unlikely to ever run into this issue in truth since observer is always started first and spends very little time down during updates and such. An addon would have to start and steal port 4357 during one of those small windows. But figured I'd handle it for completeness just in case.

2. What about addons that run on host network?

Addons which run on the host network can also fail due to port conflict if something else has already bound a port they need. However as mentioned in the description, these addons do not enumerate the ports they use anywhere. The service itself just binds to ports as needed in code. Which means from a docker perspective these containers are fine, they start without issue. This won't present as a docker issue in this case, it will present as an issue with the service itself. Docker won't even know anything is wrong at all unless the container crashes with the service or there is a healthcheck, in which case watchdog will kick in but it won't know why. The only thing the user can do here is check the logs and hopefully the service outputs an intelligible error.

Unfortunately this applies to the Home Assistant container as well since it also runs on the host network. Supervisor isn't going to be able to detect and report a port conflict error, Home Assistant core is going to have to do that if we want that behavior.