i spent the last year just spinning

flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/JacksonExtension.java

@@ -1,9 +1,11 @@
 package dev.relism.ext.jackson;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
 import com.fasterxml.jackson.databind.json.JsonMapper;
 import dev.relism.extension.FlashContext;
 import dev.relism.extension.FlashExtension;
+import dev.relism.routing.Middleware;
 
 /**
  * Registers JSON support into the Flash extension layer.
@@ -15,6 +17,9 @@ import dev.relism.extension.FlashExtension;
  * <p>The raw {@link ObjectMapper} is also registered under {@code ObjectMapper.class}
  * for extensions that need direct mapper access (e.g. OpenAPI schema generation).
  *
+ * <p>{@link JacksonMiddleware} is provided under {@code JacksonMiddleware.class} and
+ * exposes opinionated JSON auto-marshalling middleware via {@link JacksonMiddleware#autoJson()}.
+ *
  * <h3>Usage — composition (preferred)</h3>
  * <pre>{@code
  * public class MyHandler extends RequestHandler {
@@ -45,21 +50,43 @@ import dev.relism.extension.FlashExtension;
 public class JacksonExtension implements FlashExtension {
 
     private final ObjectMapper mapper;
+    private final JacksonMiddleware middleware;
 
-    /** Installs with a default {@link JsonMapper} (no extra modules). */
+    /**
+     * Installs with an opinionated default {@link JsonMapper}:
+     * auto-discovers modules on classpath (e.g. Java Time) and writes dates as ISO strings.
+     */
     public JacksonExtension() {
-        this(JsonMapper.builder().build());
+        this(JsonMapper.builder()
+                .findAndAddModules()
+                .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
+                .build());
     }
 
     /** Installs with a fully configured custom {@link ObjectMapper}. */
     public JacksonExtension(ObjectMapper mapper) {
         this.mapper = mapper;
+        this.middleware = new JacksonMiddleware(mapper);
+    }
+
+    /**
+     * Opinionated outbound JSON middleware factory.
+     *
+     * <p>Use for app/scope-level registration:
+     * <pre>{@code
+     * JacksonExtension jackson = new JacksonExtension();
+     * app.install(jackson).use(jackson.autoJson());
+     * }</pre>
+     */
+    public Middleware autoJson() {
+        return middleware.autoJson();
     }
 
     @Override
     public void provide(FlashContext ctx) {
         Json json = new Json(mapper);
-        ctx.provide(Json.class,         json);
-        ctx.provide(ObjectMapper.class, mapper);
+        ctx.provide(Json.class,               json);
+        ctx.provide(ObjectMapper.class,       mapper);
+        ctx.provide(JacksonMiddleware.class,  middleware);
     }
 }

flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/JacksonMiddleware.java

@@ -0,0 +1,62 @@
+package dev.relism.ext.jackson;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import dev.relism.http.ContentType;
+import dev.relism.models.Response;
+import dev.relism.routing.Middleware;
+
+/**
+ * Outbound JSON marshalling middleware for class-based and lambda routes.
+ *
+ * <p>{@link #autoJson()} marshals any non-body-native return value to JSON bytes,
+ * writes {@code Content-Type: application/json}, and returns {@code byte[]} so
+ * the Flash write path stays direct.
+ *
+ * <p>Pass-through return types:
+ * <ul>
+ *   <li>{@code null}</li>
+ *   <li>{@link Response}</li>
+ *   <li>{@code byte[]}</li>
+ *   <li>{@link String}</li>
+ *   <li>{@link CharSequence}</li>
+ * </ul>
+ */
+public final class JacksonMiddleware {
+
+    private final ObjectMapper mapper;
+
+    JacksonMiddleware(ObjectMapper mapper) {
+        this.mapper = mapper;
+    }
+
+    /**
+     * Automatic JSON marshalling policy.
+     *
+     * <p>For non-pass-through return values, serializes with Jackson directly to
+     * {@code byte[]} and sets response content type to JSON.
+     *
+     * @throws IllegalStateException when serialization fails
+     */
+    public Middleware autoJson() {
+        return next -> (req, res) -> {
+            Object out = next.handle(req, res);
+            if (isPassThrough(out)) return out;
+
+            res.type(ContentType.JSON);
+            try {
+                return mapper.writeValueAsBytes(out);
+            } catch (JsonProcessingException e) {
+                throw new IllegalStateException(
+                        "Failed to serialize handler result as JSON: " + out.getClass().getName(), e);
+            }
+        };
+    }
+
+    private static boolean isPassThrough(Object out) {
+        return out == null
+                || out instanceof Response
+                || out instanceof byte[]
+                || out instanceof CharSequence;
+    }
+}

flash-extensions/flash-ext-jackson/src/test/java/dev/relism/ext/jackson/JacksonExtensionTest.java

@@ -0,0 +1,60 @@
+package dev.relism.ext.jackson;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import dev.relism.extension.FlashContext;
+import dev.relism.http.ContentType;
+import dev.relism.models.Request;
+import dev.relism.models.RequestHandler;
+import dev.relism.models.Response;
+import org.junit.jupiter.api.Test;
+
+import java.nio.charset.StandardCharsets;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class JacksonExtensionTest {
+
+    @Test
+    void provide_registers_json_mapper_and_middleware() {
+        FlashContext ctx = new FlashContext();
+        ObjectMapper mapper = new ObjectMapper();
+        JacksonExtension ext = new JacksonExtension(mapper);
+
+        ext.provide(ctx);
+
+        assertNotNull(ctx.require(Json.class));
+        assertNotNull(ctx.require(JacksonMiddleware.class));
+        assertSame(mapper, ctx.require(ObjectMapper.class));
+    }
+
+    @Test
+    void autoJson_factory_delegates_to_middleware_policy() throws Exception {
+        ObjectMapper mapper = new ObjectMapper();
+        JacksonExtension ext = new JacksonExtension(mapper);
+        RequestHandler next = new RequestHandler() {
+            @Override
+            public Object handle(Request request, Response response) {
+                return new Payload("ok");
+            }
+        };
+        RequestHandler wrapped = new RequestHandler() {
+            private final dev.relism.models.SimpleHandler.FunctionalHandler delegate = ext.autoJson().wrap(next);
+
+            @Override
+            public Object handle(Request request, Response response) throws Exception {
+                return delegate.handle(request, response);
+            }
+        };
+
+        Response res = new Response(200, ContentType.TEXT_PLAIN);
+        Object out = wrapped.handle(null, res);
+
+        assertTrue(out instanceof byte[]);
+        assertEquals("application/json", new String(res.getContentType(), StandardCharsets.UTF_8));
+    }
+
+    private record Payload(String status) {}
+}

flash-extensions/flash-ext-jackson/src/test/java/dev/relism/ext/jackson/JacksonMiddlewareTest.java

@@ -0,0 +1,89 @@
+package dev.relism.ext.jackson;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import dev.relism.http.ContentType;
+import dev.relism.models.Request;
+import dev.relism.models.RequestHandler;
+import dev.relism.models.Response;
+import org.junit.jupiter.api.Test;
+
+import java.nio.charset.StandardCharsets;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class JacksonMiddlewareTest {
+
+    private static final Request REQ = null;
+
+    @Test
+    void autoJson_marshalsPojo_toJsonBytes_and_setsJsonContentType() throws Exception {
+        JacksonMiddleware mw = new JacksonMiddleware(new ObjectMapper());
+        RequestHandler wrapped = wrap(mw, new UserDto("u1", "alice"));
+        Response res = new Response(200, ContentType.TEXT_PLAIN);
+
+        Object out = wrapped.handle(REQ, res);
+
+        assertInstanceOf(byte[].class, out);
+        assertEquals("application/json", new String(res.getContentType(), StandardCharsets.UTF_8));
+        assertEquals("{\"id\":\"u1\",\"name\":\"alice\"}", new String((byte[]) out, StandardCharsets.UTF_8));
+    }
+
+    @Test
+    void autoJson_passThrough_for_response_string_charSequence_bytes_and_null() throws Exception {
+        JacksonMiddleware mw = new JacksonMiddleware(new ObjectMapper());
+
+        Response payloadResponse = new Response(201, ContentType.TEXT_PLAIN).body("ok");
+        RequestHandler wrappedResponse = wrap(mw, payloadResponse);
+        Response res = new Response(200, ContentType.TEXT_PLAIN);
+        assertSame(payloadResponse, wrappedResponse.handle(REQ, res));
+
+        String s = "hello";
+        assertSame(s, wrap(mw, s).handle(REQ, res));
+
+        CharSequence cs = new StringBuilder("hello-cs");
+        assertSame(cs, wrap(mw, cs).handle(REQ, res));
+
+        byte[] bytes = new byte[]{1, 2, 3};
+        assertSame(bytes, wrap(mw, bytes).handle(REQ, res));
+
+        assertSame(null, wrap(mw, null).handle(REQ, res));
+    }
+
+    @Test
+    void autoJson_wraps_serialization_errors_as_illegal_state() {
+        JacksonMiddleware mw = new JacksonMiddleware(new ObjectMapper());
+        RequestHandler wrapped = wrap(mw, new CyclicDto());
+        Response res = new Response(200, ContentType.TEXT_PLAIN);
+
+        IllegalStateException ex = assertThrows(IllegalStateException.class, () -> wrapped.handle(REQ, res));
+        assertEquals("application/json", new String(res.getContentType(), StandardCharsets.UTF_8));
+        assertTrue(ex.getMessage().startsWith("Failed to serialize handler result as JSON:"));
+    }
+
+    private static RequestHandler wrap(JacksonMiddleware mw, Object fixedReturn) {
+        RequestHandler next = new RequestHandler() {
+            @Override
+            public Object handle(Request request, Response response) {
+                return fixedReturn;
+            }
+        };
+        return new RequestHandler() {
+            private final dev.relism.models.SimpleHandler.FunctionalHandler delegate = mw.autoJson().wrap(next);
+
+            @Override
+            public Object handle(Request request, Response response) throws Exception {
+                return delegate.handle(request, response);
+            }
+        };
+    }
+
+    private record UserDto(String id, String name) {}
+
+    private static final class CyclicDto {
+        CyclicDto self = this;
+    }
+}

flash-extensions/flash-ext-jackson/src/test/java/dev/relism/ext/jackson/JsonTest.java

@@ -0,0 +1,116 @@
+package dev.relism.ext.jackson;
+
+import com.fasterxml.jackson.annotation.JsonView;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import dev.relism.exceptions.HttpException;
+import dev.relism.http.ContentType;
+import dev.relism.http.HttpMethod;
+import dev.relism.models.HeaderMap;
+import dev.relism.models.Request;
+import dev.relism.models.RequestLine;
+import dev.relism.models.Response;
+import dev.relism.routing.routers.fastpathrouter.FastPathViews;
+import org.junit.jupiter.api.Test;
+
+import java.nio.charset.StandardCharsets;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class JsonTest {
+
+    @Test
+    void body_parses_valid_json_and_maps_bad_payload_to_http_400() throws Exception {
+        Json json = new Json(new ObjectMapper());
+
+        Request ok = request("{\"id\":\"u1\",\"name\":\"alice\"}");
+        UserDto dto = json.body(ok, UserDto.class);
+        assertEquals("u1", dto.id);
+        assertEquals("alice", dto.name);
+
+        Request bad = request("not-json");
+        HttpException ex = assertThrows(HttpException.class, () -> json.body(bad, UserDto.class));
+        assertEquals(400, ex.status());
+        assertTrue(ex.getMessage().startsWith("Invalid request body:"));
+    }
+
+    @Test
+    void bodyFrom_parses_stream_and_maps_bad_payload_to_http_400() throws Exception {
+        Json json = new Json(new ObjectMapper());
+
+        Request ok = request("{\"id\":\"u2\",\"name\":\"bob\"}");
+        UserDto dto = json.bodyFrom(ok, UserDto.class);
+        assertEquals("u2", dto.id);
+        assertEquals("bob", dto.name);
+
+        Request bad = request("[");
+        HttpException ex = assertThrows(HttpException.class, () -> json.bodyFrom(bad, UserDto.class));
+        assertEquals(400, ex.status());
+    }
+
+    @Test
+    void write_and_writeView_set_content_type_and_render_expected_payload() throws Exception {
+        Json json = new Json(new ObjectMapper());
+        Response res = new Response(200, ContentType.TEXT_PLAIN);
+
+        String payload = json.write(res, new UserDto("u3", "carol"));
+        assertEquals("application/json", new String(res.getContentType(), StandardCharsets.UTF_8));
+        assertEquals("{\"id\":\"u3\",\"name\":\"carol\"}", payload);
+
+        Response viewRes = new Response(200, ContentType.TEXT_PLAIN);
+        String viewed = json.writeView(viewRes, new ViewDto("u4", "hidden"), PublicView.class);
+        assertEquals("application/json", new String(viewRes.getContentType(), StandardCharsets.UTF_8));
+        assertEquals("{\"id\":\"u4\"}", viewed);
+    }
+
+    @Test
+    void mapper_returns_underlying_object_mapper_instance() {
+        ObjectMapper mapper = new ObjectMapper();
+        Json json = new Json(mapper);
+        assertSame(mapper, json.mapper());
+    }
+
+    private static Request request(String body) {
+        return request(body.getBytes(StandardCharsets.UTF_8));
+    }
+
+    private static Request request(byte[] body) {
+        RequestLine line = new RequestLine(
+                HttpMethod.POST,
+                new FastPathViews.StringByteView("/json"),
+                null,
+                new FastPathViews.StringByteView("HTTP/1.1"),
+                new HeaderMap()
+        );
+        return new Request(line, body);
+    }
+
+    private static final class UserDto {
+        public String id;
+        public String name;
+
+        public UserDto() {}
+
+        private UserDto(String id, String name) {
+            this.id = id;
+            this.name = name;
+        }
+    }
+
+    private interface PublicView {}
+    private interface InternalView {}
+
+    private static final class ViewDto {
+        @JsonView(PublicView.class)
+        public String id;
+        @JsonView(InternalView.class)
+        public String secret;
+
+        private ViewDto(String id, String secret) {
+            this.id = id;
+            this.secret = secret;
+        }
+    }
+}