+ * GET /assets/index.js {@literal ->} /assets/index.js
+ * GET /assets/js/index.js {@literal ->} /assets/js/index.js
+ *
+ *
+ * @return The asset requested path, includes the name.
+ */
+ @Nonnull
+ String path();
+
+ /**
+ * @return URL representing the resource.
+ */
+ @Nonnull
+ URL resource();
+
+ /**
+ * @return Generate a weak Etag using the {@link #path()}, {@link #lastModified()} and
+ * {@link #length()}.
+ */
+ @Nonnull
+ default String etag() {
+ try {
+ StringBuilder b = new StringBuilder(32);
+ b.append("W/\"");
+
+ BaseEncoding b64 = BaseEncoding.base64();
+ int lhash = resource().toURI().hashCode();
+
+ b.append(b64.encode(Longs.toByteArray(lastModified() ^ lhash)));
+ b.append(b64.encode(Longs.toByteArray(length() ^ lhash)));
+ b.append('"');
+ return b.toString();
+ } catch (URISyntaxException x) {
+ throw Throwing.sneakyThrow(x);
+ }
+ }
+
+ /**
+ * @return Asset size (in bytes) or -1 if undefined.
+ */
+ long length();
+
+ /**
+ * @return The last modified date if possible or -1 when isn't.
+ */
+ long lastModified();
+
+ /**
+ * @return The content of this asset.
+ * @throws Exception If content can't be read it.
+ */
+ @Nonnull
+ InputStream stream() throws Exception;
+
+ /**
+ * @return Asset media type.
+ */
+ @Nonnull
+ MediaType type();
+}
diff --git a/jooby/src/main/java/org/jooby/AsyncMapper.java b/jooby/src/main/java/org/jooby/AsyncMapper.java
new file mode 100644
index 00000000..e169c7a4
--- /dev/null
+++ b/jooby/src/main/java/org/jooby/AsyncMapper.java
@@ -0,0 +1,80 @@
+/*
+ * Copyright 2026 The Billing Project, LLC
+ *
+ * The Billing Project licenses this file to you under the Apache License, version 2.0
+ * (the "License"); you may not use this file except in compliance with the
+ * License. You may obtain a copy of the License at:
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+package org.jooby;
+
+import java.util.concurrent.Callable;
+import java.util.concurrent.CompletableFuture;
+
+import org.jooby.internal.mapper.CallableMapper;
+import org.jooby.internal.mapper.CompletableFutureMapper;
+
+/**
+ *
async-mapper
+ *
+ * Map {@link Callable} and {@link CompletableFuture} results to {@link Deferred Deferred API}.
+ *
+ *
+ * @author edgar
+ * @since 1.0.0
+ */
+@SuppressWarnings("rawtypes")
+public class AsyncMapper implements Route.Mapper {
+
+ @Override
+ public Object map(final Object value) throws Throwable {
+ if (value instanceof Callable) {
+ return new CallableMapper().map((Callable) value);
+ } else if (value instanceof CompletableFuture) {
+ return new CompletableFutureMapper().map((CompletableFuture) value);
+ }
+ return value;
+ }
+
+}
diff --git a/jooby/src/main/java/org/jooby/Cookie.java b/jooby/src/main/java/org/jooby/Cookie.java
new file mode 100644
index 00000000..d556214b
--- /dev/null
+++ b/jooby/src/main/java/org/jooby/Cookie.java
@@ -0,0 +1,553 @@
+/*
+ * Copyright 2026 The Billing Project, LLC
+ *
+ * The Billing Project licenses this file to you under the Apache License, version 2.0
+ * (the "License"); you may not use this file except in compliance with the
+ * License. You may obtain a copy of the License at:
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+package org.jooby;
+
+import com.google.common.base.Splitter;
+import com.google.common.base.Strings;
+import com.google.common.io.BaseEncoding;
+import static java.util.Objects.requireNonNull;
+import org.jooby.funzy.Throwing;
+import org.jooby.internal.CookieImpl;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import javax.crypto.Mac;
+import javax.crypto.spec.SecretKeySpec;
+import java.net.URLDecoder;
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.util.Collections;
+import java.util.Iterator;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.function.Function;
+import java.util.regex.Pattern;
+import java.util.stream.Collectors;
+
+/**
+ * Creates a cookie, a small amount of information sent by a server to
+ * a Web browser, saved by the browser, and later sent back to the server.
+ * A cookie's value can uniquely
+ * identify a client, so cookies are commonly used for session management.
+ *
+ *
+ * A cookie has a name, a single value, and optional attributes such as a comment, path and domain
+ * qualifiers, a maximum age, and a version number.
+ *
+ *
+ *
+ * The server sends cookies to the browser by using the {@link Response#cookie(Cookie)} method,
+ * which adds fields to HTTP response headers to send cookies to the browser, one at a time. The
+ * browser is expected to support 20 cookies for each Web server, 300 cookies total, and may limit
+ * cookie size to 4 KB each.
+ *
+ *
+ *
+ * The browser returns cookies to the server by adding fields to HTTP request headers. Cookies can
+ * be retrieved from a request by using the {@link Request#cookie(String)} method. Several cookies
+ * might have the same name but different path attributes.
+ *
+ *
+ *
+ * This class supports both the Version 0 (by Netscape) and Version 1 (by RFC 2109) cookie
+ * specifications. By default, cookies are created using Version 0 to ensure the best
+ * interoperability.
+ *
+ *
+ * @author edgar and various
+ * @since 0.1.0
+ */
+public interface Cookie {
+
+ /**
+ * Decode a cookie value using, like: k=v, multiple k=v pair are
+ * separated by &. Also, k and v are decoded using
+ * {@link URLDecoder}.
+ */
+ Function> URL_DECODER = value -> {
+ if (value == null) {
+ return Collections.emptyMap();
+ }
+ Throwing.Function decode = v -> URLDecoder
+ .decode(v, StandardCharsets.UTF_8.name());
+
+ return Splitter.on('&')
+ .trimResults()
+ .omitEmptyStrings()
+ .splitToList(value)
+ .stream()
+ .map(v -> {
+ Iterator it = Splitter.on('=').trimResults().omitEmptyStrings()
+ .split(v)
+ .iterator();
+ return new String[]{
+ decode.apply(it.next()),
+ it.hasNext() ? decode.apply(it.next()) : null
+ };
+ })
+ .filter(it -> Objects.nonNull(it[1]))
+ .collect(Collectors.toMap(it -> it[0], it -> it[1]));
+ };
+
+ /**
+ * Encode a hash into cookie value, like: k1=v1&...&kn=vn. Also,
+ * key and value are encoded using {@link URLEncoder}.
+ */
+ Function, String> URL_ENCODER = value -> {
+ Throwing.Function encode = v -> URLEncoder
+ .encode(v, StandardCharsets.UTF_8.name());
+ return value.entrySet().stream()
+ .map(e -> new StringBuilder()
+ .append(encode.apply(e.getKey()))
+ .append('=')
+ .append(encode.apply(e.getValue())))
+ .collect(Collectors.joining("&"))
+ .toString();
+ };
+
+ /**
+ * Build a {@link Cookie}.
+ *
+ * @author edgar
+ * @since 0.1.0
+ */
+ class Definition {
+
+ /** Cookie's name. */
+ private String name;
+
+ /** Cookie's value. */
+ private String value;
+
+ /** Cookie's domain. */
+ private String domain;
+
+ /** Cookie's path. */
+ private String path;
+
+ /** Cookie's comment. */
+ private String comment;
+
+ /** HttpOnly flag. */
+ private Boolean httpOnly;
+
+ /** True, ensure that the session cookie is only transmitted via HTTPS. */
+ private Boolean secure;
+
+ /**
+ * By default, -1 is returned, which indicates that the cookie will persist until
+ * browser shutdown.
+ */
+ private Integer maxAge;
+
+ /**
+ * Creates a new {@link Definition cookie's definition}.
+ */
+ protected Definition() {
+ }
+
+ /**
+ * Clone a new {@link Definition cookie's definition}.
+ *
+ * @param def A cookie's definition.
+ */
+ public Definition(final Definition def) {
+ this.comment = def.comment;
+ this.domain = def.domain;
+ this.httpOnly = def.httpOnly;
+ this.maxAge = def.maxAge;
+ this.name = def.name;
+ this.path = def.path;
+ this.secure = def.secure;
+ this.value = def.value;
+ }
+
+ /**
+ * Creates a new {@link Definition cookie's definition}.
+ *
+ * @param name Cookie's name.
+ * @param value Cookie's value.
+ */
+ public Definition(final String name, final String value) {
+ name(name);
+ value(value);
+ }
+
+ /**
+ * Creates a new {@link Definition cookie's definition}.
+ *
+ * @param name Cookie's name.
+ */
+ public Definition(final String name) {
+ name(name);
+ }
+
+ /**
+ * Produces a cookie from current definition.
+ *
+ * @return A new cookie.
+ */
+ @Nonnull
+ public Cookie toCookie() {
+ return new CookieImpl(this);
+ }
+
+ @Override
+ public String toString() {
+ return toCookie().encode();
+ }
+
+ /**
+ * Set/Override the cookie's name.
+ *
+ * @param name A cookie's name.
+ * @return This definition.
+ */
+ @Nonnull
+ public Definition name(final String name) {
+ this.name = requireNonNull(name, "A cookie name is required.");
+ return this;
+ }
+
+ /**
+ * @return Cookie's name.
+ */
+ @Nonnull
+ public Optional name() {
+ return Optional.ofNullable(name);
+ }
+
+ /**
+ * Set the cookie's value.
+ *
+ * @param value A value.
+ * @return This definition.
+ */
+ @Nonnull
+ public Definition value(final String value) {
+ this.value = requireNonNull(value, "A cookie value is required.");
+ return this;
+ }
+
+ /**
+ * @return Cookie's value.
+ */
+ @Nonnull
+ public Optional value() {
+ if (Strings.isNullOrEmpty(value)) {
+ return Optional.empty();
+ }
+ return Optional.of(value);
+ }
+
+ /**
+ * Set the cookie's domain.
+ *
+ * @param domain Cookie's domain.
+ * @return This definition.
+ */
+ @Nonnull
+ public Definition domain(final String domain) {
+ this.domain = requireNonNull(domain, "A cookie domain is required.");
+ return this;
+ }
+
+ /**
+ * @return A cookie's domain.
+ */
+ @Nonnull
+ public Optional domain() {
+ return Optional.ofNullable(domain);
+ }
+
+ /**
+ * Set the cookie's path.
+ *
+ * @param path Cookie's path.
+ * @return This definition.
+ */
+ @Nonnull
+ public Definition path(final String path) {
+ this.path = requireNonNull(path, "A cookie path is required.");
+ return this;
+ }
+
+ /**
+ * @return Get cookie's path.
+ */
+ @Nonnull
+ public Optional path() {
+ return Optional.ofNullable(path);
+ }
+
+ /**
+ * Set cookie's comment.
+ *
+ * @param comment A cookie's comment.
+ * @return This definition.
+ */
+ @Nonnull
+ public Definition comment(final String comment) {
+ this.comment = requireNonNull(comment, "A cookie comment is required.");
+ return this;
+ }
+
+ /**
+ * @return Cookie's comment.
+ */
+ @Nonnull
+ public Optional comment() {
+ return Optional.ofNullable(comment);
+ }
+
+ /**
+ * Set HttpOnly flag.
+ *
+ * @param httpOnly True, for HTTP Only.
+ * @return This definition.
+ */
+ @Nonnull
+ public Definition httpOnly(final boolean httpOnly) {
+ this.httpOnly = httpOnly;
+ return this;
+ }
+
+ /**
+ * @return HTTP only flag.
+ */
+ @Nonnull
+ public Optional httpOnly() {
+ return Optional.ofNullable(httpOnly);
+ }
+
+ /**
+ * True, ensure that the session cookie is only transmitted via HTTPS.
+ *
+ * @param secure True, ensure that the session cookie is only transmitted via HTTPS.
+ * @return This definition.
+ */
+ @Nonnull
+ public Definition secure(final boolean secure) {
+ this.secure = secure;
+ return this;
+ }
+
+ /**
+ * @return True, ensure that the session cookie is only transmitted via HTTPS.
+ */
+ @Nonnull
+ public Optional secure() {
+ return Optional.ofNullable(secure);
+ }
+
+ /**
+ * Sets the maximum age in seconds for this Cookie.
+ *
+ *
+ * A positive value indicates that the cookie will expire after that many seconds have passed.
+ * Note that the value is the maximum age when the cookie will expire, not the cookie's
+ * current age.
+ *
+ *
+ *
+ * A negative value means that the cookie is not stored persistently and will be deleted when
+ * the Web browser exits. A zero value causes the cookie to be deleted.
+ *
+ *
+ * @param maxAge an integer specifying the maximum age of the cookie in seconds; if negative,
+ * means the cookie is not stored; if zero, deletes the cookie.
+ * @return This definition.
+ */
+ @Nonnull
+ public Definition maxAge(final int maxAge) {
+ this.maxAge = maxAge;
+ return this;
+ }
+
+ /**
+ * Gets the maximum age in seconds for this Cookie.
+ *
+ *
+ * A positive value indicates that the cookie will expire after that many seconds have passed.
+ * Note that the value is the maximum age when the cookie will expire, not the cookie's
+ * current age.
+ *
+ *
+ *
+ * A negative value means that the cookie is not stored persistently and will be deleted when
+ * the Web browser exits. A zero value causes the cookie to be deleted.
+ *
+ *
+ * @return Cookie's max age in seconds.
+ */
+ @Nonnull
+ public Optional maxAge() {
+ return Optional.ofNullable(maxAge);
+ }
+
+ }
+
+ /**
+ * Sign cookies using a HMAC algorithm plus SHA-256 hash.
+ * Usage:
+ *
+ *
+ * String signed = Signature.sign("hello", "mysecretkey");
+ * ...
+ * // is it valid?
+ * assertEquals(signed, Signature.unsign(signed, "mysecretkey");
+ *
+ *
+ * @author edgar
+ * @since 0.1.0
+ */
+ public class Signature {
+
+ /** Remove trailing '='. */
+ private static final Pattern EQ = Pattern.compile("=+$");
+
+ /** Algorithm name. */
+ public static final String HMAC_SHA256 = "HmacSHA256";
+
+ /** Signature separator. */
+ private static final String SEP = "|";
+
+ /**
+ * Sign a value using a secret key. A value and secret key are required. Sign is done with
+ * {@link #HMAC_SHA256}.
+ * Signed value looks like:
+ *
+ *
+ * [signed value] '|' [raw value]
+ *
+ *
+ * @param value A value to sign.
+ * @param secret A secret key.
+ * @return A signed value.
+ */
+ @Nonnull
+ public static String sign(final String value, final String secret) {
+ requireNonNull(value, "A value is required.");
+ requireNonNull(secret, "A secret is required.");
+
+ try {
+ Mac mac = Mac.getInstance(HMAC_SHA256);
+ mac.init(new SecretKeySpec(secret.getBytes(), HMAC_SHA256));
+ byte[] bytes = mac.doFinal(value.getBytes());
+ return EQ.matcher(BaseEncoding.base64().encode(bytes)).replaceAll("") + SEP + value;
+ } catch (Exception ex) {
+ throw new IllegalArgumentException("Can't sing value", ex);
+ }
+ }
+
+ /**
+ * Un-sign a value, previously signed with {@link #sign(String, String)}.
+ * Try {@link #valid(String, String)} to check for valid signed values.
+ *
+ * @param value A signed value.
+ * @param secret A secret key.
+ * @return A new signed value or null.
+ */
+ @Nullable
+ public static String unsign(final String value, final String secret) {
+ requireNonNull(value, "A value is required.");
+ requireNonNull(secret, "A secret is required.");
+ int sep = value.indexOf(SEP);
+ if (sep <= 0) {
+ return null;
+ }
+ String str = value.substring(sep + 1);
+ String mac = sign(str, secret);
+
+ return mac.equals(value) ? str : null;
+ }
+
+ /**
+ * True, if the given signed value is valid.
+ *
+ * @param value A signed value.
+ * @param secret A secret key.
+ * @return True, if the given signed value is valid.
+ */
+ public static boolean valid(final String value, final String secret) {
+ return unsign(value, secret) != null;
+ }
+
+ }
+
+ /**
+ * @return Cookie's name.
+ */
+ @Nonnull
+ String name();
+
+ /**
+ * @return Cookie's value.
+ */
+ @Nonnull
+ Optional value();
+
+ /**
+ * @return An optional comment.
+ */
+ @Nonnull
+ Optional comment();
+
+ /**
+ * @return Cookie's domain.
+ */
+ @Nonnull
+ Optional domain();
+
+ /**
+ * Gets the maximum age of this cookie (in seconds).
+ *
+ *
+ * By default, -1 is returned, which indicates that the cookie will persist until
+ * browser shutdown.
+ *
+ *
+ * @return An integer specifying the maximum age of the cookie in seconds; if negative, means
+ * the cookie persists until browser shutdown
+ */
+ int maxAge();
+
+ /**
+ * @return Cookie's path.
+ */
+ @Nonnull
+ Optional path();
+
+ /**
+ * Returns true if the browser is sending cookies only over a secure protocol, or
+ * false if the browser can send cookies using any protocol.
+ *
+ * @return true if the browser uses a secure protocol, false otherwise.
+ */
+ boolean secure();
+
+ /**
+ * @return True if HTTP Only.
+ */
+ boolean httpOnly();
+
+ /**
+ * @return Encode the cookie.
+ */
+ @Nonnull
+ String encode();
+}
diff --git a/jooby/src/main/java/org/jooby/Deferred.java b/jooby/src/main/java/org/jooby/Deferred.java
new file mode 100644
index 00000000..0a505881
--- /dev/null
+++ b/jooby/src/main/java/org/jooby/Deferred.java
@@ -0,0 +1,458 @@
+/*
+ * Copyright 2026 The Billing Project, LLC
+ *
+ * The Billing Project licenses this file to you under the Apache License, version 2.0
+ * (the "License"); you may not use this file except in compliance with the
+ * License. You may obtain a copy of the License at:
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+package org.jooby;
+
+import static java.util.Objects.requireNonNull;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import java.util.Optional;
+import java.util.concurrent.Callable;
+import java.util.concurrent.Executor;
+import java.util.concurrent.ForkJoinPool;
+
+/**
+ *
async request processing
+ *
+ * A Deferred result, useful for async request processing.
+ *
+ *
+ * Application can produces a result from a different thread. Once result is ready, a call to
+ * {@link #resolve(Object)} is required. Please note, a call to {@link #reject(Throwable)} is
+ * required in case of errors.
+ *
+ *
+ * If you add the {@link AsyncMapper} then your controller method can return a {@link Callable}.
+ *
+ * Previous example runs in the default executor, which always run deferred results in the
+ * same/caller thread.
+ *
+ * To effectively run a deferred result in new/different thread you need to provide an
+ * {@link Executor}:
+ *
+ *
+ *
+ * A {@link Deferred} object works as a promise too, given you {@link #resolve(Object)} and
+ * {@link #reject(Throwable)} methods. Examples:
+ *
+ * As promise using the default executor (execute promise in same/caller thread):
+ *
+ *
+ * @author edgar
+ * @since 0.10.0
+ */
+public class Deferred extends Result {
+
+ /**
+ * Deferred initializer, useful to provide a more functional API.
+ *
+ * @author edgar
+ * @since 0.10.0
+ */
+ public interface Initializer0 {
+
+ /**
+ * Run the initializer block.
+ *
+ * @param deferred Deferred object.
+ * @throws Exception If something goes wrong.
+ */
+ void run(Deferred deferred) throws Exception;
+ }
+
+ /**
+ * Deferred initializer with {@link Request} access, useful to provide a more functional API.
+ *
+ * @author edgar
+ * @since 0.10.0
+ */
+ public interface Initializer {
+
+ /**
+ * Run the initializer block.
+ *
+ * @param req Current request.
+ * @param deferred Deferred object.
+ * @throws Exception If something goes wrong.
+ */
+ void run(Request req, Deferred deferred) throws Exception;
+ }
+
+ /**
+ * A deferred handler. Application code should never use this class. INTERNAL USE ONLY.
+ *
+ * @author edgar
+ * @since 0.10.0
+ */
+ public interface Handler {
+ void handle(@Nullable Result result, Throwable exception);
+ }
+
+ /** Deferred initializer. Optional. */
+ private Initializer initializer;
+
+ /** Deferred handler. Internal. */
+ private Handler handler;
+
+ private String executor;
+
+ private String callerThread;
+
+ /**
+ * Creates a new {@link Deferred} with an initializer.
+ *
+ * @param executor Executor to use.
+ * @param initializer An initializer.
+ */
+ public Deferred(final String executor, final Initializer0 initializer) {
+ this(executor, (req, deferred) -> initializer.run(deferred));
+ }
+
+ /**
+ * Creates a new {@link Deferred} with an initializer.
+ *
+ * @param initializer An initializer.
+ */
+ public Deferred(final Initializer0 initializer) {
+ this(null, initializer);
+ }
+
+ /**
+ * Creates a new {@link Deferred} with an initializer.
+ *
+ * @param initializer An initializer.
+ */
+ public Deferred(final Initializer initializer) {
+ this(null, initializer);
+ }
+
+ /**
+ * Creates a new {@link Deferred} with an initializer.
+ *
+ * @param executor Executor to use.
+ * @param initializer An initializer.
+ */
+ public Deferred(@Nullable final String executor, final Initializer initializer) {
+ this.executor = executor;
+ this.initializer = requireNonNull(initializer, "Initializer is required.");
+ this.callerThread = Thread.currentThread().getName();
+ }
+
+ /**
+ * Creates a new {@link Deferred}.
+ */
+ public Deferred() {
+ }
+
+ /**
+ * {@link #resolve(Object)} or {@link #reject(Throwable)} the given value.
+ *
+ * @param value Resolved value.
+ */
+ @Override
+ @Nonnull
+ public Result set(final Object value) {
+ if (value instanceof Throwable) {
+ reject((Throwable) value);
+ } else {
+ resolve(value);
+ }
+ return this;
+ }
+
+ /**
+ * Get an executor to run this deferred result. If the executor is present, then it will be use it
+ * to execute the deferred object. Otherwise it will use the global/application executor.
+ *
+ * @return Executor to use or fallback to global/application executor.
+ */
+ @Nonnull
+ public Optional executor() {
+ return Optional.ofNullable(executor);
+ }
+
+ /**
+ * Name of the caller thread (thread that creates this deferred object).
+ *
+ * @return Name of the caller thread (thread that creates this deferred object).
+ */
+ @Nonnull
+ public String callerThread() {
+ return callerThread;
+ }
+
+ /**
+ * Resolve the deferred value and handle it. This method will send the response to a client and
+ * cleanup and close all the resources.
+ *
+ * @param value A value for this deferred.
+ */
+ public void resolve(@Nullable final Object value) {
+ if (value == null) {
+ handler.handle(null, null);
+ } else {
+ Result result;
+ if (value instanceof Result) {
+ super.set(value);
+ result = (Result) value;
+ } else {
+ super.set(value);
+ result = clone();
+ }
+ handler.handle(result, null);
+ }
+ }
+
+ /**
+ * Resolve the deferred with an error and handle it. This method will handle the given exception,
+ * send the response to a client and cleanup and close all the resources.
+ *
+ * @param cause A value for this deferred.
+ */
+ public void reject(final Throwable cause) {
+ super.set(cause);
+ handler.handle(null, cause);
+ }
+
+ /**
+ * Setup a handler for this deferred. Application code should never call this method: INTERNAL USE
+ * ONLY.
+ *
+ * @param req Current request.
+ * @param handler A response handler.
+ * @throws Exception If initializer fails to start.
+ */
+ public void handler(final Request req, final Handler handler) throws Exception {
+ this.handler = requireNonNull(handler, "Handler is required.");
+ if (initializer != null) {
+ initializer.run(req, this);
+ }
+ }
+
+ /**
+ * Functional version of {@link Deferred#Deferred(Initializer)}.
+ *
+ * Using the default executor (current thread):
+ *
+ *
+ *
+ * This handler automatically {@link Deferred#resolve(Object)} or
+ * {@link Deferred#reject(Throwable)} a route handler response.
+ *
+ * @param executor Executor to run the deferred.
+ * @param handler Application block.
+ * @return A new deferred handler.
+ */
+ @Nonnull
+ public static Deferred deferred(final String executor, final Route.ZeroArgHandler handler) {
+ return deferred(executor, req -> handler.handle());
+ }
+
+ /**
+ * Functional version of {@link Deferred#Deferred(Initializer)}. To use ideally with one
+ * or more {@link Executor}:
+ *
+ *
+ *
+ * This handler automatically {@link Deferred#resolve(Object)} or
+ * {@link Deferred#reject(Throwable)} a route handler response.
+ *
+ * @param executor Executor to run the deferred.
+ * @param handler Application block.
+ * @return A new deferred handler.
+ */
+ @Nonnull
+ public static Deferred deferred(final String executor, final Route.OneArgHandler handler) {
+ return new Deferred(executor, (req, deferred) -> {
+ try {
+ deferred.resolve(handler.handle(req));
+ } catch (Throwable x) {
+ deferred.reject(x);
+ }
+ });
+ }
+
+}
diff --git a/jooby/src/main/java/org/jooby/Env.java b/jooby/src/main/java/org/jooby/Env.java
new file mode 100644
index 00000000..502029d7
--- /dev/null
+++ b/jooby/src/main/java/org/jooby/Env.java
@@ -0,0 +1,622 @@
+/*
+ * Copyright 2026 The Billing Project, LLC
+ *
+ * The Billing Project licenses this file to you under the Apache License, version 2.0
+ * (the "License"); you may not use this file except in compliance with the
+ * License. You may obtain a copy of the License at:
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+package org.jooby;
+
+import com.google.common.base.Splitter;
+import com.google.common.collect.ImmutableList;
+import com.google.inject.Key;
+import com.google.inject.name.Names;
+import com.typesafe.config.Config;
+import static java.util.Objects.requireNonNull;
+import org.jooby.funzy.Throwing;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.NoSuchElementException;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.function.BiFunction;
+import java.util.function.BinaryOperator;
+import java.util.function.Consumer;
+import java.util.function.Function;
+import java.util.function.Supplier;
+
+/**
+ * Allows to optimize, customize or apply defaults values for application services.
+ *
+ *
+ * A env is represented by it's name. For example: dev, prod, etc... A
+ * dev env is special and a module provider could do some special configuration for
+ * development, like turning off a cache, reloading of resources, etc.
+ *
+ *
+ * Same is true for not dev environments. For example, a module provider might
+ * create a high performance connection pool, caches, etc.
+ *
+ *
+ * By default env is set to dev, but you can change it by setting the
+ * application.env property to anything else.
+ *
+ *
+ * @author edgar
+ * @since 0.1.0
+ */
+public interface Env extends LifeCycle {
+
+ /**
+ * Property source for {@link Resolver}
+ *
+ * @author edgar
+ * @since 1.1.0
+ */
+ interface PropertySource {
+
+ /**
+ * Get a property value or throw {@link NoSuchElementException}.
+ *
+ * @param key Property key/name.
+ * @return Value or throw {@link NoSuchElementException}.
+ * @throws NoSuchElementException If property is missing.
+ */
+ @Nonnull
+ String get(String key) throws NoSuchElementException;
+ }
+
+ /**
+ * {@link PropertySource} for {@link Config}.
+ *
+ * @author edgar
+ * @since 1.1.0
+ */
+ class ConfigSource implements PropertySource {
+
+ private Config source;
+
+ public ConfigSource(final Config source) {
+ this.source = source;
+ }
+
+ @Override
+ public String get(final String key) throws NoSuchElementException {
+ if (source.hasPath(key)) {
+ return source.getString(key);
+ }
+ throw new NoSuchElementException(key);
+ }
+
+ }
+
+ /**
+ * {@link PropertySource} for {@link Map}.
+ *
+ * @author edgar
+ * @since 1.1.0
+ */
+ class MapSource implements PropertySource {
+
+ private Map source;
+
+ public MapSource(final Map source) {
+ this.source = source;
+ }
+
+ @Override
+ public String get(final String key) throws NoSuchElementException {
+ Object value = source.get(key);
+ if (value != null) {
+ return value.toString();
+ }
+ throw new NoSuchElementException(key);
+ }
+
+ }
+
+ /**
+ * Template literal implementation, replaces ${expression} from a String using a
+ * {@link Config} object.
+ *
+ * @author edgar
+ */
+ class Resolver {
+ private String startDelim = "${";
+
+ private String endDelim = "}";
+
+ private PropertySource source;
+
+ private boolean ignoreMissing;
+
+ /**
+ * Set property source.
+ *
+ * @param source Source.
+ * @return This resolver.
+ */
+ public Resolver source(final Map source) {
+ return source(new MapSource(source));
+ }
+
+ /**
+ * Set property source.
+ *
+ * @param source Source.
+ * @return This resolver.
+ */
+ public Resolver source(final PropertySource source) {
+ this.source = source;
+ return this;
+ }
+
+ /**
+ * Set property source.
+ *
+ * @param source Source.
+ * @return This resolver.
+ */
+ public Resolver source(final Config source) {
+ return source(new ConfigSource(source));
+ }
+
+ /**
+ * Set start and end delimiters.
+ *
+ * @param start Start delimiter.
+ * @param end End delimiter.
+ * @return This resolver.
+ */
+ public Resolver delimiters(final String start, final String end) {
+ this.startDelim = requireNonNull(start, "Start delimiter required.");
+ this.endDelim = requireNonNull(end, "End delmiter required.");
+ return this;
+ }
+
+ /**
+ * Ignore missing property replacement and leave the expression untouch.
+ *
+ * @return This resolver.
+ */
+ public Resolver ignoreMissing() {
+ this.ignoreMissing = true;
+ return this;
+ }
+
+ /**
+ * Returns a string with all substitutions (the ${foo.bar} syntax,
+ * see the
+ * spec) resolved. Substitutions are looked up using the source param as the
+ * root object, that is, a substitution ${foo.bar} will be replaced with
+ * the result of getValue("foo.bar").
+ *
+ * @param text Text to process.
+ * @return A processed string.
+ */
+ public String resolve(final String text) {
+ requireNonNull(text, "Text is required.");
+ if (text.length() == 0) {
+ return "";
+ }
+
+ BiFunction, RuntimeException> err = (
+ start, ex) -> {
+ String snapshot = text.substring(0, start);
+ int line = Splitter.on('\n').splitToList(snapshot).size();
+ int column = start - snapshot.lastIndexOf('\n');
+ return ex.apply(line, column);
+ };
+
+ StringBuilder buffer = new StringBuilder();
+ int offset = 0;
+ int start = text.indexOf(startDelim);
+ while (start >= 0) {
+ int end = text.indexOf(endDelim, start + startDelim.length());
+ if (end == -1) {
+ throw err.apply(start, (line, column) -> new IllegalArgumentException(
+ "found '" + startDelim + "' expecting '" + endDelim + "' at " + line + ":"
+ + column));
+ }
+ buffer.append(text.substring(offset, start));
+ String key = text.substring(start + startDelim.length(), end);
+ Object value;
+ try {
+ value = source.get(key);
+ } catch (NoSuchElementException x) {
+ if (ignoreMissing) {
+ value = text.substring(start, end + endDelim.length());
+ } else {
+ throw err.apply(start, (line, column) -> new NoSuchElementException(
+ "Missing " + startDelim + key + endDelim + " at " + line + ":" + column));
+ }
+ }
+ buffer.append(value);
+ offset = end + endDelim.length();
+ start = text.indexOf(startDelim, offset);
+ }
+ if (buffer.length() == 0) {
+ return text;
+ }
+ if (offset < text.length()) {
+ buffer.append(text.substring(offset));
+ }
+ return buffer.toString();
+ }
+ }
+
+ /**
+ * Utility class for generating {@link Key} for named services.
+ *
+ * @author edgar
+ */
+ class ServiceKey {
+ private Map instances = new HashMap<>();
+
+ /**
+ * Generate at least one named key for the provided type. If this is the first call for the
+ * provided type then it generates an unnamed key.
+ *
+ * @param type Service type.
+ * @param name Service name.
+ * @param keys Key callback. Invoked once with a named key, and optionally again with an unamed
+ * key.
+ * @param Service type.
+ */
+ public void generate(final Class type, final String name, final Consumer> keys) {
+ Integer c = instances.put(type, instances.getOrDefault(type, 0) + 1);
+ if (c == null) {
+ // def key
+ keys.accept(Key.get(type));
+ }
+ keys.accept(Key.get(type, Names.named(name)));
+ }
+ }
+
+ /**
+ * Build an jooby environment.
+ *
+ * @author edgar
+ */
+ interface Builder {
+
+ /**
+ * Build a new environment from a {@link Config} object. The environment is created from the
+ * application.env property. If such property is missing, env's name must be:
+ * dev.
+ *
+ * Please note an environment created with this method won't have a {@link Env#router()}.
+ *
+ * @param config A config instance.
+ * @return A new environment.
+ */
+ @Nonnull
+ default Env build(final Config config) {
+ return build(config, null, Locale.getDefault());
+ }
+
+ /**
+ * Build a new environment from a {@link Config} object. The environment is created from the
+ * application.env property. If such property is missing, env's name must be:
+ * dev.
+ *
+ * @param config A config instance.
+ * @param router Application router.
+ * @param locale App locale.
+ * @return A new environment.
+ */
+ @Nonnull
+ Env build(Config config, @Nullable Router router, Locale locale);
+ }
+
+ /**
+ * Default builder.
+ */
+ Env.Builder DEFAULT = (config, router, locale) -> {
+ requireNonNull(config, "Config required.");
+ String name = config.hasPath("application.env") ? config.getString("application.env") : "dev";
+ return new Env() {
+
+ private ImmutableList.Builder> start = ImmutableList.builder();
+
+ private ImmutableList.Builder> started = ImmutableList.builder();
+
+ private ImmutableList.Builder> shutdown = ImmutableList.builder();
+
+ private Map> xss = new HashMap<>();
+
+ private Map globals = new HashMap<>();
+
+ private ServiceKey key = new ServiceKey();
+
+ public Env set(Key key, T value) {
+ globals.put(key, value);
+ return this;
+ }
+
+ public T unset(Key key) {
+ return (T) globals.remove(key);
+ }
+
+ public Optional get(Key key) {
+ T value = (T) globals.get(key);
+ return Optional.ofNullable(value);
+ }
+
+ @Override
+ public String name() {
+ return name;
+ }
+
+ @Override
+ public ServiceKey serviceKey() {
+ return key;
+ }
+
+ @Override
+ public Router router() {
+ if (router == null) {
+ throw new UnsupportedOperationException();
+ }
+ return router;
+ }
+
+ @Override
+ public Config config() {
+ return config;
+ }
+
+ @Override
+ public Locale locale() {
+ return locale;
+ }
+
+ @Override
+ public String toString() {
+ return name();
+ }
+
+ @Override
+ public List> stopTasks() {
+ return shutdown.build();
+ }
+
+ @Override
+ public Env onStop(final Throwing.Consumer task) {
+ this.shutdown.add(task);
+ return this;
+ }
+
+ @Override
+ public Env onStart(final Throwing.Consumer task) {
+ this.start.add(task);
+ return this;
+ }
+
+ @Override
+ public LifeCycle onStarted(final Throwing.Consumer task) {
+ this.started.add(task);
+ return this;
+ }
+
+ @Override
+ public List> startTasks() {
+ return this.start.build();
+ }
+
+ @Override
+ public List> startedTasks() {
+ return this.started.build();
+ }
+
+ @Override
+ public Map> xss() {
+ return Collections.unmodifiableMap(xss);
+ }
+
+ @Override
+ public Env xss(final String name, final Function escaper) {
+ xss.put(requireNonNull(name, "Name required."),
+ requireNonNull(escaper, "Function required."));
+ return this;
+ }
+ };
+ };
+
+ /**
+ * @return Env's name.
+ */
+ @Nonnull
+ String name();
+
+ /**
+ * Application router.
+ *
+ * @return Available {@link Router}.
+ * @throws UnsupportedOperationException if router isn't available.
+ */
+ @Nonnull
+ Router router() throws UnsupportedOperationException;
+
+ /**
+ * @return environment properties.
+ */
+ @Nonnull
+ Config config();
+
+ /**
+ * @return Default locale from application.lang.
+ */
+ @Nonnull
+ Locale locale();
+
+ /**
+ * @return Utility method for generating keys for named services.
+ */
+ @Nonnull
+ default ServiceKey serviceKey() {
+ return new ServiceKey();
+ }
+
+ /**
+ * Returns a string with all substitutions (the ${foo.bar} syntax,
+ * see the
+ * spec) resolved. Substitutions are looked up using the {@link #config()} as the root object,
+ * that is, a substitution ${foo.bar} will be replaced with
+ * the result of getValue("foo.bar").
+ *
+ * @param text Text to process.
+ * @return A processed string.
+ */
+ @Nonnull
+ default String resolve(final String text) {
+ return resolver().resolve(text);
+ }
+
+ /**
+ * Creates a new environment {@link Resolver}.
+ *
+ * @return A resolver object.
+ */
+ @Nonnull
+ default Resolver resolver() {
+ return new Resolver().source(config());
+ }
+
+ /**
+ * Runs the callback function if the current env matches the given name.
+ *
+ * @param name A name to test for.
+ * @param fn A callback function.
+ * @param A resulting type.
+ * @return A resulting object.
+ */
+ @Nonnull
+ default Optional ifMode(final String name, final Supplier fn) {
+ if (name().equals(name)) {
+ return Optional.of(fn.get());
+ }
+ return Optional.empty();
+ }
+
+ /**
+ * @return XSS escape functions.
+ */
+ @Nonnull
+ Map> xss();
+
+ /**
+ * Get or chain the required xss functions.
+ *
+ * @param xss XSS to combine.
+ * @return Chain of required xss functions.
+ */
+ @Nonnull
+ default Function xss(final String... xss) {
+ Map> fn = xss();
+ BinaryOperator> reduce = Function::andThen;
+ return Arrays.asList(xss)
+ .stream()
+ .map(fn::get)
+ .filter(Objects::nonNull)
+ .reduce(Function.identity(), reduce);
+ }
+
+ /**
+ * Set/override a XSS escape function.
+ *
+ * @param name Escape's name.
+ * @param escaper Escape function.
+ * @return This environment.
+ */
+ @Nonnull
+ Env xss(String name, Function escaper);
+
+ /**
+ * @return List of start tasks.
+ */
+ @Nonnull
+ List> startTasks();
+
+ /**
+ * @return List of start tasks.
+ */
+ @Nonnull
+ List> startedTasks();
+
+ /**
+ * @return List of stop tasks.
+ */
+ @Nonnull
+ List> stopTasks();
+
+ /**
+ * Add a global object.
+ *
+ * @param key Object key.
+ * @param value Object value.
+ * @param Object type.
+ * @return This environment.
+ */
+ @Nonnull
+ Env set(Key key, T value);
+
+ /**
+ * Add a global object.
+ *
+ * @param key Object key.
+ * @param value Object value.
+ * @param Object type.
+ * @return This environment.
+ */
+ @Nonnull
+ default Env set(Class key, T value) {
+ return set(Key.get(key), value);
+ }
+
+ /**
+ * Remove a global object.
+ *
+ * @param key Object key.
+ * @param Object type.
+ * @return Object value might be null.
+ */
+ @Nullable T unset(Key key);
+
+ /**
+ * Get an object by key or empty when missing.
+ *
+ * @param key Object key.
+ * @param Object type.
+ * @return Object valur or empty.
+ */
+ @Nonnull
+ Optional get(Key key);
+
+ /**
+ * Get an object by key or empty when missing.
+ *
+ * @param key Object key.
+ * @param Object type.
+ * @return Object valur or empty.
+ */
+ @Nonnull
+ default Optional get(Class key) {
+ return get(Key.get(key));
+ }
+}
diff --git a/jooby/src/main/java/org/jooby/Err.java b/jooby/src/main/java/org/jooby/Err.java
new file mode 100644
index 00000000..ab25c6e6
--- /dev/null
+++ b/jooby/src/main/java/org/jooby/Err.java
@@ -0,0 +1,327 @@
+/*
+ * Copyright 2026 The Billing Project, LLC
+ *
+ * The Billing Project licenses this file to you under the Apache License, version 2.0
+ * (the "License"); you may not use this file except in compliance with the
+ * License. You may obtain a copy of the License at:
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+package org.jooby;
+
+import java.util.*;
+import java.util.function.BiFunction;
+import java.util.function.Function;
+import java.util.function.Supplier;
+
+import com.typesafe.config.Config;
+import org.jooby.funzy.Try;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import com.google.common.base.Throwables;
+
+import javax.annotation.Nullable;
+
+/**
+ * An exception that carry a {@link Status}. The status field will be set in the HTTP
+ * response.
+ *
+ * See {@link Err.Handler} for more details on how to deal with exceptions.
+ *
+ * @author edgar
+ * @since 0.1.0
+ */
+@SuppressWarnings("serial")
+public class Err extends RuntimeException {
+
+ /**
+ * Exception thrown from {@link MediaType#parse(String)} in case of encountering an invalid media
+ * type specification String.
+ *
+ * @author edgar
+ */
+ public static class BadMediaType extends Err {
+
+ /**
+ * Creates a new {@link BadMediaType}.
+ *
+ * @param message Error message.
+ */
+ public BadMediaType(final String message) {
+ super(Status.BAD_REQUEST, message);
+ }
+
+ }
+
+ /**
+ * Missing parameter/header or request attribute.
+ *
+ * @author edgar
+ */
+ public static class Missing extends Err {
+
+ /**
+ * Creates a new {@link Missing} error.
+ *
+ * @param name Name of the missing parameter/header or request attribute.
+ */
+ public Missing(final String name) {
+ super(Status.BAD_REQUEST, name);
+ }
+
+ }
+
+ /**
+ * Default err handler it does content negotation.
+ *
+ * On text/html requests the err handler creates an err view and use the
+ * {@link Err#toMap()} result as model.
+ *
+ * @author edgar
+ * @since 0.1.0
+ */
+ public static class DefHandler implements Err.Handler {
+
+ /** Default err view. */
+ public static final String VIEW = "err";
+
+ /** logger, logs!. */
+ private final Logger log = LoggerFactory.getLogger(Err.class);
+
+ @Override
+ public void handle(final Request req, final Response rsp, final Err ex) throws Throwable {
+ log.error("execution of: {}{} resulted in exception\nRoute:\n{}\n\nStacktrace:",
+ req.method(), req.path(), req.route().print(6), ex);
+ Config conf = req.require(Config.class);
+ Env env = req.require(Env.class);
+ boolean stackstrace = Try.apply(() -> conf.getBoolean("err.stacktrace"))
+ .orElse(env.name().equals("dev"));
+
+ Function xssFilter = env.xss("html").compose(Objects::toString);
+ BiFunction escaper = (k, v) -> xssFilter.apply(v);
+
+ Map details = ex.toMap(stackstrace);
+ details.compute("message", escaper);
+ details.compute("reason", escaper);
+
+ rsp.send(
+ Results
+ .when(MediaType.html, () -> Results.html(VIEW).put("err", details))
+ .when(MediaType.all, () -> details));
+ }
+
+ }
+
+ /**
+ * Handle and render exceptions. Error handlers are executed in the order they were provided, the
+ * first err handler that send an output wins!
+ *
+ * The default err handler does content negotation on error, see {@link DefHandler}.
+ *
+ * @author edgar
+ * @since 0.1.0
+ */
+ public interface Handler {
+
+ /**
+ * Handle a route exception by properly logging the error and sending a err response to the
+ * client.
+ *
+ * Please note you always get an {@link Err} whenever you throw it or not. For example if your
+ * application throws an {@link IllegalArgumentException} exception you will get an {@link Err}
+ * and you can retrieve the original exception by calling {@link Err#getCause()}.
+ *
+ * Jooby always give you an {@link Err} with an optional root cause and an associated status
+ * code.
+ *
+ * @param req HTTP request.
+ * @param rsp HTTP response.
+ * @param ex Error found and status code.
+ * @throws Throwable If something goes wrong.
+ */
+ void handle(Request req, Response rsp, Err ex) throws Throwable;
+ }
+
+ /**
+ * The status code. Required.
+ */
+ private int status;
+
+ /**
+ * Creates a new {@link Err}.
+ *
+ * @param status A HTTP status. Required.
+ * @param message A error message. Required.
+ * @param cause The cause of the problem.
+ */
+ public Err(final Status status, final String message, final Throwable cause) {
+ super(message(status, message), cause);
+ this.status = status.value();
+ }
+
+ /**
+ * Creates a new {@link Err}.
+ *
+ * @param status A HTTP status. Required.
+ * @param message A error message. Required.
+ * @param cause The cause of the problem.
+ */
+ public Err(final int status, final String message, final Throwable cause) {
+ super(message("", status, message), cause);
+ this.status = status;
+ }
+
+ /**
+ * Creates a new {@link Err}.
+ *
+ * @param status A web socket close status. Required.
+ * @param message Close message.
+ */
+ public Err(final WebSocket.CloseStatus status, final String message) {
+ super(message(status.reason(), status.code(), message));
+ this.status = status.code();
+ }
+
+ /**
+ * Creates a new {@link Err}.
+ *
+ * @param status A HTTP status. Required.
+ * @param message A error message. Required.
+ */
+ public Err(final Status status, final String message) {
+ super(message(status, message));
+ this.status = status.value();
+ }
+
+ /**
+ * Creates a new {@link Err}.
+ *
+ * @param status A HTTP status. Required.
+ * @param message A error message. Required.
+ */
+ public Err(final int status, final String message) {
+ this(Status.valueOf(status), message);
+ }
+
+ /**
+ * Creates a new {@link Err}.
+ *
+ * @param status A HTTP status. Required.
+ * @param cause The cause of the problem.
+ */
+ public Err(final Status status, final Throwable cause) {
+ super(message(status, null), cause);
+ this.status = status.value();
+ }
+
+ /**
+ * Creates a new {@link Err}.
+ *
+ * @param status A HTTP status. Required.
+ * @param cause The cause of the problem.
+ */
+ public Err(final int status, final Throwable cause) {
+ this(Status.valueOf(status), cause);
+ }
+
+ /**
+ * Creates a new {@link Err}.
+ *
+ * @param status A HTTP status. Required.
+ */
+ public Err(final Status status) {
+ super(message(status, null));
+ this.status = status.value();
+ }
+
+ /**
+ * Creates a new {@link Err}.
+ *
+ * @param status A HTTP status. Required.
+ */
+ public Err(final int status) {
+ this(Status.valueOf(status));
+ }
+
+ /**
+ * @return The status code to send as response.
+ */
+ public int statusCode() {
+ return status;
+ }
+
+ /**
+ * Produces a friendly view of the err, resulting map has these attributes:
+ *
+ *
+ * message: exception message (if present)
+ * status: status code
+ * reason: a status code reason
+ *
+ *
+ * @return A lightweight view of the err.
+ */
+ public Map toMap() {
+ return toMap(false);
+ }
+
+ /**
+ * Produces a friendly view of the err, resulting map has these attributes:
+ *
+ *
+ * message: exception message (if present)
+ * stacktrace: array with the stacktrace
+ * status: status code
+ * reason: a status code reason
+ *
+ *
+ * @param stacktrace True for adding stacktrace.
+ * @return A lightweight view of the err.
+ */
+ public Map toMap(boolean stacktrace) {
+ Status status = Status.valueOf(this.status);
+ Throwable cause = Optional.ofNullable(getCause()).orElse(this);
+ String message = Optional.ofNullable(cause.getMessage()).orElse(status.reason());
+
+ Map err = new LinkedHashMap<>();
+ err.put("message", message);
+ if (stacktrace) {
+ err.put("stacktrace", Throwables.getStackTraceAsString(cause).replace("\r", "").split("\\n"));
+ }
+ err.put("status", status.value());
+ err.put("reason", status.reason());
+
+ return err;
+ }
+
+ /**
+ * Build an error message using the HTTP status.
+ *
+ * @param status The HTTP Status.
+ * @param tail A message to append.
+ * @return An error message.
+ */
+ private static String message(final Status status, @Nullable final String tail) {
+ return message(status.reason(), status.value(), tail);
+ }
+
+ /**
+ * Build an error message using the HTTP status.
+ *
+ * @param reason Reason.
+ * @param status The Status.
+ * @param tail A message to append.
+ * @return An error message.
+ */
+ private static String message(final String reason, final int status, @Nullable final String tail) {
+ return reason + "(" + status + ")" + (tail == null ? "" : ": " + tail);
+ }
+
+}
diff --git a/jooby/src/main/java/org/jooby/FlashScope.java b/jooby/src/main/java/org/jooby/FlashScope.java
new file mode 100644
index 00000000..c856ec1d
--- /dev/null
+++ b/jooby/src/main/java/org/jooby/FlashScope.java
@@ -0,0 +1,144 @@
+/*
+ * Copyright 2026 The Billing Project, LLC
+ *
+ * The Billing Project licenses this file to you under the Apache License, version 2.0
+ * (the "License"); you may not use this file except in compliance with the
+ * License. You may obtain a copy of the License at:
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+package org.jooby;
+
+import static java.util.Objects.requireNonNull;
+
+import java.util.Map;
+import java.util.Optional;
+import java.util.function.Function;
+
+import org.jooby.internal.handlers.FlashScopeHandler;
+import org.jooby.mvc.Flash;
+
+import com.google.inject.Binder;
+import com.typesafe.config.Config;
+
+/**
+ *
flash scope
+ *
+ * The flash scope is designed to transport success and error messages, between requests. The flash
+ * scope is similar to {@link Session} but lifecycle is shorter: data are kept for only one request.
+ *
+ *
+ * The flash scope is implemented as client side cookie, so it helps to keep application stateless.
+ *
+ * Worth to mention that flash attributes are accessible from template engine by prefixing
+ * attributes with flash.. Here is a handlebars.java example:
+ *
+ * By default Jooby looks for an application.conf. If
+ * you want to specify a different file or location, you can do it with {@link #conf(String)}.
+ *
+ *
+ *
+ * TypeSafe Config uses a hierarchical model to
+ * define and override properties.
+ *
+ *
+ * A {@link Jooby.Module} might provides his own set of properties through the
+ * {@link Jooby.Module#config()} method. By default, this method returns an empty config object.
+ *
+ *
+ * Previous example had the following order (first-listed are higher priority):
+ *
+ *
arguments properties
+ *
System properties
+ *
application.conf
+ *
M3 properties
+ *
M2 properties
+ *
M1 properties
+ *
+ *
+ * Command line argmuents or system properties takes precedence over any application specific
+ * property.
+ *
+ *
+ *
env
+ *
+ * Jooby defines one mode or environment: dev. In Jooby, dev
+ * is special and some modules could apply special settings while running in dev.
+ * Any other env is usually considered a prod like env. But that depends on module
+ * implementor.
+ *
+ *
+ * An environment can be defined in your .conf file using the
+ * application.env property. If missing, Jooby set the env for you to
+ * dev.
+ *
+ *
+ * There is more at {@link Env} please read the {@link Env} javadoc.
+ *
+ *
+ *
modules: the jump to full-stack framework
+ *
+ * {@link Jooby.Module Modules} are quite similar to a Guice modules except that the configure
+ * callback has been complementing with {@link Env} and {@link Config}.
+ *
+ *
+ *
+ * public class MyModule implements Jooby.Module {
+ * public void configure(Env env, Config config, Binder binder) {
+ * }
+ * }
+ *
+ *
+ * From the configure callback you can bind your services as you usually do in a Guice app.
+ *
+ * There is more at {@link Jooby.Module} so please read the {@link Jooby.Module} javadoc.
+ *
+ *
+ *
path patterns
+ *
+ * Jooby supports Ant-style path patterns:
+ *
+ *
+ * Some examples:
+ *
+ *
+ *
{@code com/t?st.html} - matches {@code com/test.html} but also {@code com/tast.html} or
+ * {@code com/txst.html}
+ *
{@code com/*.html} - matches all {@code .html} files in the {@code com} directory
+ *
com/{@literal **}/test.html - matches all {@code test.html} files underneath the
+ * {@code com} path
+ *
{@code **}/{@code *} - matches any path at any level.
+ *
{@code *} - matches any path at any level, shorthand for {@code **}/{@code *}.
+ *
+ *
+ *
variables
+ *
+ * Jooby supports path parameters too:
+ *
+ *
+ * Some examples:
+ *
+ *
+ *
/user/{id} - /user/* and give you access to the id var.
+ *
/user/:id - /user/* and give you access to the id var.
+ *
/user/{id:\\d+} - /user/[digits] and give you access to the numeric
+ * id var.
+ *
+ *
+ *
routes
+ *
+ * Routes perform actions in response to a server HTTP request.
+ *
+ *
+ * Routes are executed in the order they are defined, for example:
+ *
+ *
+ *
+ * get("/", (req, rsp) {@literal ->} {
+ * log.info("first"); // start here and go to second
+ * });
+ *
+ * get("/", (req, rsp) {@literal ->} {
+ * log.info("second"); // execute after first and go to final
+ * });
+ *
+ * get("/", (req, rsp) {@literal ->} {
+ * rsp.send("final"); // done!
+ * });
+ *
+ *
+ * Previous example can be rewritten using {@link Route.Filter}:
+ *
+ *
+ * get("/", (req, rsp, chain) {@literal ->} {
+ * log.info("first"); // start here and go to second
+ * chain.next(req, rsp);
+ * });
+ *
+ * get("/", (req, rsp, chain) {@literal ->} {
+ * log.info("second"); // execute after first and go to final
+ * chain.next(req, rsp);
+ * });
+ *
+ * get("/", (req, rsp) {@literal ->} {
+ * rsp.send("final"); // done!
+ * });
+ *
+ *
+ * Due to the use of lambdas a route is a singleton and you should NOT use global variables. For
+ * example this is a bad practice:
+ *
+ *
+ * List{@literal <}String{@literal >} names = new ArrayList{@literal <}{@literal >}(); // names produces side effects
+ * get("/", (req, rsp) {@literal ->} {
+ * names.add(req.param("name").value();
+ * // response will be different between calls.
+ * rsp.send(names);
+ * });
+ *
+ *
+ *
mvc routes
+ *
+ * A Mvc route use annotations to define routes:
+ *
+ * Programming model is quite similar to JAX-RS/Jersey with some minor differences and/or
+ * simplifications.
+ *
+ *
+ *
+ * To learn more about Mvc Routes, please check {@link org.jooby.mvc.Path},
+ * {@link org.jooby.mvc.Produces} {@link org.jooby.mvc.Consumes} javadoc.
+ *
+ *
+ *
static files
+ *
+ * Static files, like: *.js, *.css, ..., etc... can be served with:
+ *
+ *
+ *
+ * assets("assets/**");
+ *
+ *
+ * Classpath resources under the /assets folder will be accessible from client/browser.
+ *
+ *
+ *
lifecyle
+ *
+ * We do provide {@link #onStart(Throwing.Consumer)} and {@link #onStop(Throwing.Consumer)} callbacks.
+ * These callbacks are executed are application startup or shutdown time:
+ *
{@code
+ * {
+ * on("dev", () -> {
+ * // run something on dev
+ * }).orElse(conf -> {
+ * // run something on prod
+ * });
+ * }
+ * }
+ *
+ * @param callback Env callback.
+ */
+ void orElse(Consumer callback);
+
+ }
+
+ /**
+ * A module can publish or produces: {@link Route.Definition routes}, {@link Parser},
+ * {@link Renderer}, and any other application specific service or contract of your choice.
+ *
+ * It is similar to {@link com.google.inject.Module} except for the callback method receives a
+ * {@link Env}, {@link Config} and {@link Binder}.
+ *
+ *
+ *
+ * A module can provide his own set of properties through the {@link #config()} method. By
+ * default, this method returns an empty config object.
+ *