feat: Add build-time Caddy early hints generation

[gocanto]

Summary

• add a build script that scans the built HTML and updates a reusable Early Hints snippet for Caddy
• import the generated snippet across the local and internal Caddyfiles and mount it in Docker/local setups
• ensure the production image runs the generator after npm run build and ships the snippet alongside the config

Testing

• make format
• Tests not run (npm install blocked by 403 from registry)

Summary by CodeRabbit

• New Features
  • Added Early Hints support to optimize resource loading performance by enabling proactive resource communication between server and client.

[gemini-code-assist]

Summary of Changes

Hello @gocanto, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant performance optimization by implementing build-time generation of HTTP Early Hints for the Caddy web server. By proactively identifying critical assets from the built HTML, the system can now instruct browsers to preload these resources, potentially reducing perceived page load times and improving user experience. The changes span across build scripts, Caddy configurations, and Docker setup to seamlessly integrate this new capability into the deployment pipeline.

Highlights

• Automated Early Hints Generation: A new build script, generate-early-hints.mjs, has been added to automatically scan the built HTML (dist/index.html) and generate Caddy Early Hints configuration.
• Caddy Configuration Integration: The generated Early Hints snippet (caddy/snippets/early_hints.caddy) is now imported and applied across the WebCaddyfile.internal and WebCaddyfile.local configurations to various request handling blocks.
• Build and Deployment Workflow Updates: The Dockerfile has been modified to execute the Early Hints generation script after npm run build, and the docker-compose.yml now mounts the Caddy snippets directory, ensuring the generated hints are deployed with the application.
• Package Script Automation: A new generate:early-hints script has been added to package.json and integrated into the postbuild hook, automating the Early Hints generation process during the build phase.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Walkthrough

This PR adds HTTP Early Hints support to the Caddy web server. It introduces a Node.js build script that scans HTML files for external resources, generates corresponding Early Hints directives, and embeds them into Caddy configuration snippets. The changes include build infrastructure updates, new Caddy imports, and Docker configuration to support the generated snippets.

Changes

Cohort / File(s)	Summary
Build Makefile Targets build/makefiles/caddy.mk	Added phony target caddy-generate-early-hints, public variables EARLY_HINTS_HTML and EARLY_HINTS_SNIPPET, and a corresponding build rule that executes a Node.js script. Minor indentation adjustment to caddy-validate command.
Build Scripts build/scripts/generate-early-hints.mjs	New Node.js utility that parses HTML files, extracts external resources (links and scripts), generates deduplicated Early Hints directives, and updates a Caddy snippet file between BEGIN/END markers. Supports --html, --snippet, and --verbose command-line options.
Caddy Configuration caddy/WebCaddyfile.internal, caddy/WebCaddyfile.local	Added top-level import and per-handler import early_hints directives to force_seo, share_post_bots, sharebots, and SPA handler blocks.
Caddy Snippets caddy/snippets/early_hints.caddy	New auto-generated snippet file defining an early_hints snippet with a matcher excluding asset paths. Contains placeholder comment and BEGIN/END markers for script-managed content.
Infrastructure Configuration docker-compose.yml, docker/Dockerfile	Added read-only volume mount for caddy/snippets in compose file and make installation plus snippet copying in Docker builder and final stages.
Package Configuration package.json	Added generate:early-hints script (invokes makefile target), postbuild script (runs generate:early-hints), and trailing comma to build:stats script.

Sequence Diagram

sequenceDiagram
    participant npm as npm/package.json
    participant make as Make
    participant script as generate-early-hints.mjs
    participant html as dist/index.html
    participant caddy as caddy/snippets/early_hints.caddy
    participant server as Caddy Server
    
    npm->>make: postbuild → make caddy-generate-early-hints
    make->>script: Execute with --html and --snippet paths
    script->>html: Read and parse HTML
    script->>script: Extract links & scripts,<br/>deduplicate resources
    script->>caddy: Locate BEGIN/END markers
    script->>caddy: Replace content with generated<br/>early_hint directives
    caddy->>server: Caddy loads snippet on startup
    server->>server: Apply early_hints matcher<br/>to eligible responses

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Special attention areas:
  • build/scripts/generate-early-hints.mjs: Review the resource extraction logic, deduplication key construction, and regex/parsing correctness
  • Marker-based file manipulation in the snippet file—verify edge cases (missing markers, ordering, file writes)
  • Caddy matcher correctness in caddy/snippets/early_hints.caddy and proper import placement in handler blocks

Possibly related PRs

• hotfix: Caddy server #40: Modifies the same Caddy integration in build/makefiles/caddy.mk and related Caddy configuration, introducing complementary Makefile targets and Caddy wiring.
• feat: Make local env work #76: Updates caddy/WebCaddyfile.local for local development; this PR extends that file with early hints directive integration.
• [feature] Integrate docker and caddy #4: Establishes the foundational Caddy configuration in caddy/WebCaddyfile.internal and docker-compose.yml; this PR builds upon that infrastructure.

Poem

🐰 Links and hints now fly ahead,
Resource paths we gently tread,
Early signals Caddy sends,
Swift delivery that never ends!

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The pull request title "feat: Add build-time Caddy early hints generation" directly and accurately summarizes the main change across the changeset. The title clearly conveys that the PR adds a build-time process to generate Early Hints directives for Caddy, which is the central objective tying together all the modifications (the Node.js script, makefile target, Caddyfile imports, Docker setup, and npm scripts). The title is concise, avoids vague terminology, uses conventional commit formatting, and is specific enough that a developer scanning the history would immediately understand the primary change without needing to review the details.

---

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.}

[gemini-code-assist]

Code Review

This pull request introduces a script to generate Caddy Early Hints. However, the implementation is incorrect and will not produce Early Hints (103 responses) but rather Link headers on the final response due to improper use of Caddy directives. I've provided critical feedback on the generation script and the Caddy snippet to correct this. Additionally, there's a redundant command in the Dockerfile that should be removed to rely on the postbuild npm script.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".