Issue #1087 - add documentation and distribution test

Signed-off-by: Lachlan Roberts <lachlan@webtide.com>

documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-alpn.adoc

@@ -12,7 +12,7 @@
 //
 
 [[og-module-alpn]]
-==== Module `alpn`
+===== Module `alpn`
 
 The `alpn` module enables support for the ALPN negotiation mechanism of the TLS protocol.
 

documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-well-known.adoc

@@ -0,0 +1,27 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+// ========================================================================
+//
+
+[[og-module-well-known]]
+===== Module `well-known`
+
+The `well-known` creates a `ResourceHandler` deployed at the `/.well-known` context path.
+This `Handler` serves files from a directory created at `${jetty.base}/.well-known`, note that this may be seen as a hidden directory by the filesystem.
+
+The concept of well-known URIs has been defined in RFC5785.
+It may be used for things like automation of the renewal for Let's Encrypt certificates.
+
+The module file is `$JETTY_HOME/modules/well-known.mod`:
+
+----
+include::{JETTY_HOME}/modules/well-known.mod[]
+----

documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules-standard.adoc

@@ -29,3 +29,4 @@ include::module-ssl-reload.adoc[]
 include::module-test-keystore.adoc[]
 include::module-threadpool.adoc[]
 include::module-console-capture.adoc[]
+include::module-well-known.adoc[]

jetty-server/src/main/config/modules/well-known.mod

@@ -15,9 +15,6 @@ etc/well-known.xml
 [files]
 .well-known/
 
-[ini]
-jetty.wellknown.dir?=.well-known
-
 [ini-template]
 ## Well Known Directory (relative to $jetty.base)
 # jetty.wellknown.dir=.well-known

tests/test-distribution/src/test/java/org/eclipse/jetty/tests/distribution/DistributionTests.java

@@ -15,6 +15,7 @@ package org.eclipse.jetty.tests.distribution;
 
 import java.io.BufferedWriter;
 import java.io.File;
+import java.io.FileWriter;
 import java.net.URI;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
@@ -24,6 +25,7 @@ import java.nio.file.StandardCopyOption;
 import java.nio.file.StandardOpenOption;
 import java.util.Arrays;
 import java.util.List;
+import java.util.UUID;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
 
@@ -35,6 +37,7 @@ import org.eclipse.jetty.http.HttpStatus;
 import org.eclipse.jetty.http2.client.HTTP2Client;
 import org.eclipse.jetty.http2.client.http.HttpClientTransportOverHTTP2;
 import org.eclipse.jetty.io.ClientConnector;
+import org.eclipse.jetty.start.FS;
 import org.eclipse.jetty.unixsocket.client.HttpClientTransportOverUnixSockets;
 import org.eclipse.jetty.unixsocket.server.UnixSocketConnector;
 import org.eclipse.jetty.util.BlockingArrayQueue;
@@ -964,4 +967,53 @@ public class DistributionTests extends AbstractJettyHomeTest
             }
         }
     }
+
+    @Test
+    public void testWellKnownModule() throws Exception
+    {
+        String jettyVersion = System.getProperty("jettyVersion");
+        JettyHomeTester distribution = JettyHomeTester.Builder.newInstance()
+            .jettyVersion(jettyVersion)
+            .mavenLocalRepository(System.getProperty("mavenRepoPath"))
+            .build();
+        String[] args1 = {
+            "--approve-all-licenses",
+            "--add-modules=http,well-known"
+        };
+        try (JettyHomeTester.Run run1 = distribution.start(args1))
+        {
+            assertTrue(run1.awaitFor(10, TimeUnit.SECONDS));
+            assertEquals(0, run1.getExitValue());
+
+            // Ensure .well-known directory exists.
+            Path wellKnown = distribution.getJettyBase().resolve(".well-known");
+            assertTrue(FS.exists(wellKnown));
+
+            // Write content to a file in the .well-known directory.
+            String testFileContent = "hello world " + UUID.randomUUID();
+            File testFile = wellKnown.resolve("testFile").toFile();
+            assertTrue(testFile.createNewFile());
+            testFile.deleteOnExit();
+            FileWriter fileWriter = new FileWriter(testFile);
+            fileWriter.write(testFileContent);
+            fileWriter.close();
+
+            int port = distribution.freePort();
+            String[] args2 = {
+                "jetty.http.port=" + port
+                //"jetty.server.dumpAfterStart=true"
+            };
+
+            try (JettyHomeTester.Run run2 = distribution.start(args2))
+            {
+                assertTrue(run2.awaitConsoleLogsFor("Started Server@", 10, TimeUnit.SECONDS));
+
+                // Test we can access the file in the .well-known directory.
+                startHttpClient();
+                ContentResponse response = client.GET("http://localhost:" + port + "/.well-known/testFile");
+                assertThat(response.getStatus(), is(HttpStatus.OK_200));
+                assertThat(response.getContentAsString(), is(testFileContent));
+            }
+        }
+    }
 }