Add a configuration to serve a local directory with a static handler

[mathias82]

Summary

This PR introduces support for serving static files from a local directory,
configurable via quarkus.http.local-static-resources.*.

New configuration

quarkus.http.local-static-resources.enabled=true
quarkus.http.local-static-resources.path=/local-static/
quarkus.http.local-static-resources.directory=local-static

Tests

Added LocalStaticResourcesTest which verifies:

• Serving an existing file
• Returning 404 when missing

[ia3andy]

LGTM, just cleaning non changed files

[ia3andy]

I also forgot, you need to add those files as watched for livereload

[mathias82]

I also forgot, you need to add those files as watched for livereload

ii have added @ia3andy

[mathias82]

Improve validation and handling of local static resources directory

• Introduce normalizedDirectory() with safety checks
• I used validated directory in both build steps
• Remove unnecessary endpoint trailing-slash logic
• Simplify dev-mode directory guard

[ia3andy]

Thanks!

[ia3andy]

@mathias82 the code is LGTM, could you add the doc part also, I remember an old doc doing this with the StaticHandler (which was bad), but maybe it was removed.

[ia3andy]

The more I look at it the more I think using local and resources are confusing, with META-INF/resources which are also local static resources.

path is the path on disk which also makes it clear that it is not the endpoint.

Using / as default is also better as most of the time those static directory are serving at root.

I would suggest using this as default:

quarkus.http.static-dir.enabled=false
quarkus.http.static-dir.endpoint=/
quarkus.http.static-dir.path=static

[sberyozkin]

@ia3andy If I understand the @FroMage's comment correctly, quarkus.http.static-dir.endpoint=/ should enable it, without having to also type quarkus.http.static-dir.enabled=true.

Having a default static (static-resources ?) value for quarkus.http.static-dir.path is good.
Perhaps quarkus.http.static-resources-dir or quarkus.http.static-resources-directory is clearer, even if more verbose ? Though I'll let you and @mathias82 agree on this one, thanks

[ia3andy]

ok that's good too, just don't add resources or local in the naming as explained that makes it confusing.

[mathias82]

Makes sense, thanks both. I'll avoid using local or resources in the naming to prevent confusion with META-INF/resources, and I'll stick with the clearer static directory naming as suggested.
I have updated the configuration keys accordingly and push the changes.

[ia3andy]

Suggested change

	/**
	* The URL path under which the local directory is exposed,
	* e.g. {@code /local-static}.
	*/
	@WithDefault("/local-static")
	String endpoint();
	/**
	* The base endpoint under which the local directory is exposed,
	* <p>
	* e.g. {@code /static} with hello.txt will be serve at <code>/static/hello.txt</code>.
	*/
	@WithDefault("/static")
	String endpoint();

[ia3andy]

@mathias82 ☝

[mathias82]

done

[ia3andy]

Suggested change

	To expose the contents of a `static/` directory under the `/local-static` path:
	[source,properties]
	----
	quarkus.http.static-dir.path=/local-static
	quarkus.http.static-dir.directory=static
	----
	With this configuration, a file located at `static/index.html` will be available at:
	`http://localhost:8080/local-static/index.html`.
	To disable serving local static resources explicitly:
	To expose the contents of a `static/` directory under the `/static` endpoint:
	[source,properties]
	----
	quarkus.http.static-dir.endpoint=/static
	quarkus.http.static-dir.path=static
	----
	With this configuration, a file located at `static/index.html` will be available at:
	`http://localhost:8080/static/index.html`.
	To disable serving local static resources explicitly:

[ia3andy]

@mathias82 any reason not to auto enable when endpoint or path is not empty as @FroMage suggested?

[mathias82]

@ia3andy @FroMage There is one reason: this feature exposes a local filesystem directory over HTTP.

If we auto-enable it as soon as endpoint or path is set, it becomes easier
for large apps with layered configuration to accidentally expose a directory
just because some partial config was inherited or left behind.

By keeping enabled as an explicit opt-in switch, we avoid accidental exposure
and make the intent very clear: nothing is served unless the user consciously
enables it.

That said, if the project convention is to auto-enable on config, I can update
the implementation accordingly, I just wanted to highlight the security/ops
angle behind the current design.

[ia3andy]

@FroMage I let you decide on that one :)

[ia3andy]

@mathias82 the change I suggested is still appllicable

[ia3andy]

@mathias82 what is this?

[mathias82]

@ia3andy This registers a catch-all Vert.x route for the configured static directory.

registerHttpStaticDirRoute collects all discovered static files at build time and
passes them to registerHttpStaticDir(...), which at runtime installs:

router.route(basePath + "/*").handler(new HttpStaticDirHandler(staticFiles));

So this line effectively exposes every file under the configured static-dir.path
at <basePath>/*, and delegates the resolution to HttpStaticDirHandler.

[quarkus-bot]

Status for workflow Quarkus Documentation CI

This is the status report for running Quarkus Documentation CI on commit 1dc209d.

✅ The latest workflow run for the pull request has completed successfully.

It should be safe to merge provided you have a look at the other checks in the summary.

Warning

There are other workflow runs running, you probably need to wait for their status before merging.