nginx_proxy: Support HTTP/3 (QUIC)

[kmhallen]

Add option to nginx_proxy for HTTP/3 (QUIC) support over UDP.

Try it out here with this custom addon repository: https://github.com/kmhallen/ha-addon-nginx_proxy_quic

HTTP/3 should enable more seamless roaming from WiFi to cellular because the connection ID feature enables a connection to continue when the client IP address changes.

I couldn't find any reliable online HTTP/3 test websites, but browser developer consoles can be used to verify if HTTP/3 is being used. Chromium based browsers seem to be more likely to use HTTP/3 than Firefox. I'm not sure about the Android and iOS companion apps.

The port is specified both in options and ports because I couldn't find a way to read the port value directly. The port is needed to advertise HTTP/3 support in the Alt-Svc header.

Summary by CodeRabbit

• New Features

  • Added HTTP/3 (QUIC) support with an option to enable/disable and a configurable UDP port mapping (443/udp).

• Documentation

  • Updated docs, translations, and changelog with HTTP/3 usage guidance, port/UDP notes, troubleshooting tips, and a new 3.15.0 entry.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[home-assistant[bot]]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks :+1:

Learn more about our pull request process.

[coderabbitai[bot]]

📝 Walkthrough

Walkthrough

Adds HTTP/3 (QUIC) support surface: bumps addon version to 3.15.0, exposes UDP port 443, detects/configures a quic_port at runtime, passes quic_port into the nginx template, conditions QUIC listeners and Alt‑Svc on the presence of quic_port, and updates docs, changelog, and translations. No other API/signature changes.

Changes

Cohort / File(s)	Summary
Changelog nginx_proxy/CHANGELOG.md	Adds a new 3.15.0 entry with "Support HTTP/3 (QUIC)".
Configuration nginx_proxy/config.yaml	Bumps addon version to 3.15.0 and adds 443/udp port mapping. (No other schema signature changes detected.)
Runtime init / template vars nginx_proxy/rootfs/etc/s6-overlay/s6-rc.d/nginx/run	Detects QUIC_PORT by querying the addon for UDP port 443, coerces empty value to null, and passes quic_port as a JSON number into the template renderer (replaces prior string-based jq invocation).
Nginx template nginx_proxy/rootfs/etc/nginx/nginx.conf.gtpl	Replaces .options.http3.active gating with checks on .variables.quic_port; when quic_port is set, adds listen 443 quic (and reuseport/proxy_protocol variants), enables http3 on, and appends an Alt-Svc header. Existing HTTP/2, SSL, and proxy_protocol logic remains.
Documentation nginx_proxy/DOCS.md	Adds documentation for HTTP/3 (QUIC) UDP port usage, optional port section, and troubleshooting note about Alt‑Svc/header and firewall/port requirements.
Translations nginx_proxy/translations/en.yaml	Adds 443/udp network mapping description ("HTTP/3 (QUIC) Port") and related labels for HTTP/3.

Sequence Diagram(s)

sequenceDiagram
    participant s6run as s6-run script
    participant Addon as Addon metadata
    participant Template as nginx.conf.gtpl
    participant nginx as nginx

    Addon->>s6run: provide mapped ports (tcp/udp)
    s6run->>s6run: QUIC_PORT = UDP 443 or null
    s6run->>Template: render with JSON { port: <tcp>, quic_port: <number|null> }
    Template->>nginx: write generated nginx.conf
    nginx->>nginx: enable listeners based on quic_port presence

    alt quic_port set
        note right of nginx `#DFF2E1`: UDP QUIC listeners added\nlisten ... quic\nhttp3 on\nAlt-Svc header emitted
    else quic_port null
        note right of nginx `#F7F2E8`: No QUIC/HTTP3 configuration emitted
    end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Pay attention to:
  • Correct passing and type of quic_port into the template (JSON number vs string).
  • Proper conditional checks in nginx.conf.gtpl (uses .variables.quic_port) and consistent usage across all server blocks.
  • Correct listen ... quic / http3 on syntax matching the targeted nginx/quic build.
  • s6 run script handling when UDP port is absent (null) and fallback behavior.
  • Documentation and Alt‑Svc header value consistency with the configured port.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'nginx_proxy: Support HTTP/3 (QUIC)' directly and clearly describes the main change—adding HTTP/3 (QUIC) support to the nginx_proxy addon. It accurately reflects the changeset across all modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to data retention organization setting

📥 Commits

Reviewing files that changed from the base of the PR and between 11466d1e11284f0be28ff8a27277179835494c70 and 332cf7ab07b3a152689abd0eed7b79bdc87fcafb.

📒 Files selected for processing (5)

• nginx_proxy/DOCS.md (1 hunks)
• nginx_proxy/config.yaml (2 hunks)
• nginx_proxy/rootfs/etc/nginx/nginx.conf.gtpl (2 hunks)
• nginx_proxy/rootfs/etc/s6-overlay/s6-rc.d/nginx/run (1 hunks)
• nginx_proxy/translations/en.yaml (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (3)

• nginx_proxy/translations/en.yaml
• nginx_proxy/DOCS.md
• nginx_proxy/rootfs/etc/nginx/nginx.conf.gtpl

🧰 Additional context used

📓 Path-based instructions (1)

*/**(html|markdown|md)

⚙️ CodeRabbit configuration file

*/**(html|markdown|md): - For instructional content in documentation, use a direct and authoritative tone. Avoid expressions of politeness such as 'may' or 'please', and ensure the goal of the instruction is fronted.

• Apply the Microsoft Style Guide to ensure documentation maintains clarity and conciseness.
• In step-by-step instructions, front the location phrase in the instructional sentence.
• In step-by-step instructions, front the 'goal' in the instructional sentence.
• In step-by-step instructions, if in doubt what to front, front the 'goal' before the location phrase in the instructional sentence.
• do not hyphenate terms like 'top-right' or 'bottom-left' with 'corner'

*/**(html|markdown|md): - Use bold to mark UI strings.

• If "" are used to mark UI strings, replace them by bold.

• Be brief in your replies and don't add fluff like "thank you for..." and "Please let me know if"

• Use sentence-style capitalization also in headings.

do not comment on HTML used for icons

Avoid flagging inline HTML for embedding videos in future reviews for this repository.

Files:

• nginx_proxy/config.yaml

🔇 Additional comments (4)

nginx_proxy/config.yaml (2)

2-2: LGTM: Version bump is appropriate.

The minor version increment from 3.14.0 to 3.15.0 correctly reflects the addition of HTTP/3 (QUIC) support as a new feature.

---

32-32: LGTM: UDP port configuration is correct.

The addition of 443/udp: null correctly configures the UDP port for QUIC/HTTP3 as an opt-in feature, following the same pattern as the optional TCP port 80.

nginx_proxy/rootfs/etc/s6-overlay/s6-rc.d/nginx/run (2)

10-13: LGTM: QUIC port detection follows maintainer guidance.

The implementation correctly retrieves the UDP port configuration using bashio::addon.port '443/udp' as suggested by maintainer agners in the PR comments. The empty-string-to-null coercion ensures compatibility with the subsequent --argjson usage.

---

17-18: LGTM: Type-safe JSON argument passing.

The refactored jq invocation correctly uses --argjson for both port and quic_port, ensuring they are passed as JSON numbers (or null) rather than strings. This improves type safety in the template processing. The unquoted variable expansions are appropriate here since --argjson expects raw JSON literals.

[!TIP]

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions: | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context. Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[agners]

Thank you for your PR, nice addition :star_struck:

The port is specified both in options and ports because I couldn't find a way to read the port value directly. The port is needed to advertise HTTP/3 support in the Alt-Svc header.

It should be possible to read the port using quic_port="$(bashio::addon.port '443/udp')".