SPAs support using asset handler #1339

Author: jknack

docs/asciidoc/static-files.adoc

@@ -94,8 +94,36 @@ The `assets` route works for static sites too. Just need to use a special path m
 The key difference is the `/?*` mapping. This mapping add support for base root mapping:
 
 - GET `/docs`            => `/docs/index.html`
+- GET `/docs/index.html` => `/docs/index.html`
 - GET `/docs/about.html` => `/docs/about.html`
-- GET `/docs/note`        => `/docs/index.html`
+- GET `/docs/note`        => `/docs/note/index.html`
+
+=== SPAs
+
+The `assets` route works for single page applications (SPAs) too. Just need to use a special path mapping plus a fallback asset:
+ 
+.Classpath resources:
+[source, java, role="primary"]
+----
+{
+  AssetSource docs = AssetSource.create(Paths.get("docs")); <1>
+  assets("/docs/?*", new AssetHandler("index.html", docs)); <2>
+}
+----
+
+.Kotlin
+[source, kotlin, role="secondary"]
+----
+{
+  val docs = AssetSource.create(Paths.get("docs"))          <1>
+  assets("/docs/?*", AssetHandler("index.html", docs))      <2>
+}
+----
+
+<1> Serve from `docs` directory
+<2> Use the `/?*` mapping and uses `index.html` as fallback asset
+
+SPAs mode never generates a `NOT FOUND (404)` response, unresolved assets fallback to `index.html`
 
 === Options
 

jooby/src/main/java/io/jooby/AssetHandler.java

@@ -13,6 +13,8 @@
 /**
  * Handler for static resources represented by the {@link Asset} contract.
  *
+ * It has built-in support for static-static as well as SPAs (single page applications).
+ *
  * @author edgar
  * @since 2.0.0
  */
@@ -29,6 +31,28 @@ public class AssetHandler implements Route.Handler {
 
   private String filekey;
 
+  private String fallback;
+
+  /**
+   * Creates a new asset handler that fallback to the given fallback asset when the asset
+   * is not found. Instead of produces a <code>404</code> its fallback to the given asset.
+   *
+   * <pre>{@code
+   * {
+   *    assets("/?*", new AssetHandler("index.html", AssetSource.create(Paths.get("...")));
+   * }
+   * }</pre>
+   *
+   * The fallback option makes the asset handler to work like a SPA (Single-Application-Page).
+   *
+   * @param fallback Fallback asset.
+   * @param sources Asset sources.
+   */
+  public AssetHandler(@Nonnull String fallback, AssetSource... sources) {
+    this.fallback = fallback;
+    this.sources = sources;
+  }
+
   /**
    * Creates a new asset handler.
    *
@@ -42,8 +66,14 @@ public AssetHandler(AssetSource... sources) {
     String filepath = ctx.pathMap().getOrDefault(filekey, "index.html");
     Asset asset = resolve(filepath);
     if (asset == null) {
-      ctx.sendError(new StatusCodeException(StatusCode.NOT_FOUND));
-      return ctx;
+      if (fallback != null) {
+        asset = resolve(fallback);
+      }
+      // Still null?
+      if (asset == null) {
+        ctx.sendError(new StatusCodeException(StatusCode.NOT_FOUND));
+        return ctx;
+      }
     }
 
     // handle If-None-Match

jooby/src/main/java/io/jooby/Jooby.java

@@ -144,6 +144,15 @@ public Jooby() {
     return env;
   }
 
+  /**
+   * Application class loader.
+   *
+   * @return Application class loader.
+   */
+  public @Nonnull ClassLoader getClassLoader() {
+    return env == null ? environmentOptions.getClassLoader() : env.getClassLoader();
+  }
+
   /**
    * Application configuration. It is a shortcut for {@link Environment#getConfig()}.
    *
@@ -451,7 +460,7 @@ public Jooby errorCode(@Nonnull Class<? extends Throwable> type,
     return require(ServiceKey.key(type));
   }
 
-  @Override public  @Nonnull <T> T require(@Nonnull ServiceKey<T> key) {
+  @Override public @Nonnull <T> T require(@Nonnull ServiceKey<T> key) {
     ServiceRegistry services = getServices();
     T service = services.getOrNull(key);
     if (service == null) {

tests/src/test/java/io/jooby/FeaturedTest.java

@@ -1982,6 +1982,43 @@ public void varOnCatchAll() {
     });
   }
 
+  @Test
+  public void singlePageApp() {
+    new JoobyRunner(app -> {
+
+      app.assets("/?*", new AssetHandler("fallback.html", AssetSource.create(app.getClassLoader(), "/www")));
+
+    }).ready(client -> {
+      client.get("/docs", rsp -> {
+        assertEquals("fallback.html", rsp.body().string().trim());
+      });
+
+      client.get("/docs/index.html", rsp -> {
+        assertEquals("fallback.html", rsp.body().string().trim());
+      });
+
+      client.get("/docs/v1", rsp -> {
+        assertEquals("fallback.html", rsp.body().string().trim());
+      });
+
+      client.get("/", rsp -> {
+        assertEquals("index.html", rsp.body().string().trim());
+      });
+
+      client.get("/index.html", rsp -> {
+        assertEquals("index.html", rsp.body().string().trim());
+      });
+
+      client.get("/note", rsp -> {
+        assertEquals("note.html", rsp.body().string().trim());
+      });
+
+      client.get("/note/index.html", rsp -> {
+        assertEquals("note.html", rsp.body().string().trim());
+      });
+    });
+  }
+
   @Test
   public void staticSiteFromCp() {
    new JoobyRunner(app -> {

tests/src/test/resources/www/fallback.html

@@ -0,0 +1 @@
+fallback.html