Add handlers doc + fix bugs around HEAD request implementation

Author: jknack

docs/asciidoc/handlers.adoc

@@ -0,0 +1,9 @@
+== Handlers
+
+This section describes some built-in handler provided by Jooby.
+
+include::handlers/cors.adoc[]
+
+include::handlers/head.adoc[]
+
+include::handlers/trace.adoc[]

docs/asciidoc/cors.adoc docs/asciidoc/handlers/cors.adocdocs/asciidoc/cors.adoc renamed to docs/asciidoc/handlers/cors.adoc

@@ -1,4 +1,4 @@
-== CORS
+=== CorsHandler
 
 https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS[Cross-Origin Resource Sharing (CORS)] is a mechanism that uses additional HTTP headers to tell a 
 browser to let a web application running at one origin (domain) have permission to access selected

docs/asciidoc/handlers/head.adoc

@@ -0,0 +1,46 @@
+=== HeadHandler
+
+Jooby doesn't support `HTTP HEAD` requests by default. To support them you have two options:
+
+- Use the built-in `HeadHandler`
+- Write your own head handler
+
+The javadoc:HeadHandler[] supports `HEAD` requests over existing `GET` handlers.
+
+.Head Example
+[source, java, role = "primary"]
+----
+import io.jooby.Jooby;
+import io.jooby.HeadHandler;
+...
+{
+  
+  decorator(new HeadHandler()); <1>
+  
+  get("/", ctx -> {
+    ...
+  });
+}
+----
+
+.Kotlin
+[source, kotlin, role = "secondary"]
+----
+import io.jooby.Jooby
+import io.jooby.HeadHandler
+...
+{
+  decorator(HeadHandler())      <1>
+  
+  get("/") {
+    ...
+  }
+}
+----
+
+<1> Install HeadHandler
+
+`HEAD /` produces an empty response with a `Content-Length` header (when possible) and any other
+header produce it by the `GET` handler.
+
+The `GET` handler is executed but produces an empty response.

docs/asciidoc/handlers/trace.adoc

@@ -0,0 +1,44 @@
+=== TraceHandler
+
+Jooby doesn't support `HTTP Trace` requests by default. To support them you have two options:
+
+- Use the built-in `TraceHandler`
+- Write your own trace handler
+
+The javadoc:TraceHandler[] supports `TRACE` requests over existing handlers.
+
+.Head Example
+[source, java, role = "primary"]
+----
+import io.jooby.Jooby;
+import io.jooby.TraceHandler;
+...
+{
+  
+  decorator(new TraceHandler()); <1>
+  
+  get("/", ctx -> {
+    ...
+  });
+}
+----
+
+.Kotlin
+[source, kotlin, role = "secondary"]
+----
+import io.jooby.Jooby
+import io.jooby.TraceHandler
+...
+{
+  decorator(TraceHandler())      <1>
+  
+  get("/") {
+    ...
+  }
+}
+----
+
+<1> Install TraceHandler
+
+`TRACE /` performs a message loop-back test along the path to the target resource, providing a
+useful debugging mechanism.

docs/asciidoc/index.adoc

@@ -226,7 +226,7 @@ include::mvc-api.adoc[]
 
 include::error-handler.adoc[]
 
-include::cors.adoc[]
+include::handlers.adoc[]
 
 include::configuration.adoc[]
 

examples/src/main/java/examples/HelloApp.java

@@ -7,13 +7,16 @@
 
 import io.jooby.Jooby;
 import io.jooby.RouterOptions;
+import io.jooby.TraceHandler;
 import io.jooby.annotations.QueryParam;
 
 import java.util.stream.Stream;
 
 public class HelloApp extends Jooby {
 
   {
+    decorator(new TraceHandler());
+
     setRouterOptions(new RouterOptions().setIgnoreCase(false).setIgnoreTrailingSlash(true));
 
     get("/", ctx -> {

jooby/src/main/java/io/jooby/Context.java

@@ -759,6 +759,13 @@ public interface Context extends Registry {
    */
   @Nonnull Context setResponseLength(long length);
 
+  /**
+   * Get response content length or <code>-1</code> when none was set.
+   *
+   * @return Response content length or <code>-1</code> when none was set.
+   */
+  long getResponseLength();
+
   /**
    * Set/add a cookie to response.
    *

jooby/src/main/java/io/jooby/ForwardingContext.java

@@ -330,6 +330,10 @@ public Context setResponseHeader(@Nonnull String name, @Nonnull Instant value) {
     return this;
   }
 
+  @Override public long getResponseLength() {
+    return ctx.getResponseLength();
+  }
+
   @Override @Nonnull public Context setResponseLength(long length) {
     ctx.setResponseLength(length);
     return this;

jooby/src/main/java/io/jooby/internal/HeadContext.java

@@ -7,7 +7,6 @@
 
 import io.jooby.AttachedFile;
 import io.jooby.Context;
-import io.jooby.DefaultContext;
 import io.jooby.ForwardingContext;
 import io.jooby.MediaType;
 import io.jooby.MessageEncoder;
@@ -43,6 +42,7 @@ public HeadContext(@Nonnull Context context) {
   @Nonnull @Override public Context send(@Nonnull Path file) {
     try {
       ctx.setResponseLength(Files.size(file));
+      checkSizeHeaders();
       ctx.setResponseType(MediaType.byFile(file));
       ctx.send(StatusCode.OK);
       return this;
@@ -53,6 +53,7 @@ public HeadContext(@Nonnull Context context) {
 
   @Nonnull @Override public Context send(@Nonnull byte[] data) {
     ctx.setResponseLength(data.length);
+    checkSizeHeaders();
     ctx.send(StatusCode.OK);
     return this;
   }
@@ -63,13 +64,15 @@ public HeadContext(@Nonnull Context context) {
 
   @Nonnull @Override public Context send(@Nonnull ByteBuffer data) {
     ctx.setResponseLength(data.remaining());
+    checkSizeHeaders();
     ctx.send(StatusCode.OK);
     return this;
   }
 
   @Nonnull @Override public Context send(@Nonnull FileChannel file) {
     try {
       ctx.setResponseLength(file.size());
+      checkSizeHeaders();
       ctx.send(StatusCode.OK);
       return this;
     } catch (IOException x) {
@@ -80,12 +83,13 @@ public HeadContext(@Nonnull Context context) {
   @Nonnull @Override public Context send(@Nonnull AttachedFile file) {
     ctx.setResponseLength(file.getFileSize());
     ctx.setResponseType(file.getContentType());
+    checkSizeHeaders();
     ctx.send(StatusCode.OK);
     return this;
   }
 
   @Nonnull @Override public Context send(@Nonnull InputStream input) {
-    ctx.setResponseHeader("Transfer-Encoding", "chunked");
+    checkSizeHeaders();
     ctx.send(input);
     ctx.send(StatusCode.OK);
     return this;
@@ -97,13 +101,14 @@ public HeadContext(@Nonnull Context context) {
   }
 
   @Nonnull @Override public Context send(@Nonnull ReadableByteChannel channel) {
-    ctx.setResponseHeader("Transfer-Encoding", "chunked");
+    checkSizeHeaders();
     ctx.send(StatusCode.OK);
     return this;
   }
 
   @Nonnull @Override public Context send(@Nonnull String data, @Nonnull Charset charset) {
     ctx.setResponseLength(data.getBytes(charset).length);
+    checkSizeHeaders();
     ctx.send(StatusCode.OK);
     return this;
   }
@@ -127,13 +132,13 @@ public HeadContext(@Nonnull Context context) {
   }
 
   @Nonnull @Override public Sender responseSender() {
-    ctx.setResponseHeader("Transfer-Encoding", "chunked");
+    checkSizeHeaders();
     ctx.send(StatusCode.OK);
     return new NoopSender();
   }
 
   @Nonnull @Override public OutputStream responseStream() {
-    ctx.setResponseHeader("Transfer-Encoding", "chunked");
+    checkSizeHeaders();
     ctx.send(StatusCode.OK);
     return new NoopOutputStream();
   }
@@ -142,6 +147,14 @@ public HeadContext(@Nonnull Context context) {
     return new PrintWriter(responseStream());
   }
 
+  private void checkSizeHeaders() {
+    if (ctx.getResponseLength() < 0) {
+      ctx.setResponseHeader("Transfer-Encoding", "chunked");
+    } else {
+      ctx.removeResponseHeader("Transfer-Encoding");
+    }
+  }
+
   private static class NoopOutputStream extends OutputStream {
     @Override public void write(@NotNull byte[] b) throws IOException {
     }

modules/jooby-jetty/src/main/java/io/jooby/internal/jetty/JettyContext.java

@@ -298,6 +298,10 @@ public Context setResponseType(@Nonnull MediaType contentType, @Nullable Charset
     return this;
   }
 
+  @Override public long getResponseLength() {
+    return response.getContentLength();
+  }
+
   @Nonnull public Context setResponseCookie(@Nonnull Cookie cookie) {
     if (responseCookies == null) {
       responseCookies = new HashMap<>();