feat(api): json -> transit

Author: goshatch

deps.edn

@@ -3,6 +3,15 @@
  {org.clojure/clojure {:mvn/version "1.12.0"}
   http-kit/http-kit {:mvn/version "2.8.0"}
   metosin/reitit {:mvn/version "0.7.2"}
+
+  ;;
+  ;; Transit support, and format negotiation library
+  ;; https://github.com/cognitect/transit-format
+  ;; https://github.com/metosin/muuntaja
+  com.cognitect/transit-clj {:mvn/version "1.0.333"}
+  com.cognitect/transit-cljs {:mvn/version "0.8.280"}
+  metosin/muuntaja {:mvn/version "0.6.11"}
+
   ;;
   ;; Auth-related things
   buddy/buddy-auth {:mvn/version "3.0.323"}
@@ -14,7 +23,6 @@
   migratus/migratus {:mvn/version "1.6.3"}
   com.github.seancorfield/honeysql {:mvn/version "2.6.1270"}
 
-  ring/ring-json {:mvn/version "0.5.1"}
   ring/ring-mock {:mvn/version "0.4.0"}
 
   ;; Logging

src/main/parts/entity/system.clj

@@ -4,7 +4,6 @@
    relationships (edges)."
   (:require
    [clojure.spec.alpha :as s]
-   [clojure.data.json :as json]
    [parts.utils :refer [validate-spec]]
    [parts.db :as db]))
 

src/main/parts/server.clj

@@ -1,4 +1,8 @@
 (ns parts.server
+  "Primary namespace for the Parts server setup, handling route definitions,
+   middleware configuration, and server lifecycle management. This namespace
+   organizes the application's API routes with appropriate content types
+   and authentication controls."
   (:require
    [clojure.core.async :as async]
    [com.brunobonacci.mulog :as mulog]
@@ -7,115 +11,148 @@
    [parts.api.auth :as api.auth]
    [parts.api.systems :as api.systems]
    [parts.auth :as auth]
-   [parts.config :as config]
    [parts.db :as db]
    [parts.handlers.pages :as pages]
    [parts.handlers.waitlist :as waitlist]
    [parts.middleware :as middleware]
-   [reitit.coercion.spec]
+   [reitit.coercion.spec :as rcs]
    [reitit.ring :as ring]
-   [reitit.swagger :as swagger]
-   [reitit.swagger-ui :as swagger-ui]
-   [ring.middleware.json :refer [wrap-json-body wrap-json-response]]
+   [reitit.ring.coercion :as rrc]
+   [reitit.ring.middleware.muuntaja :as muuntaja-middleware]
+   [muuntaja.core :as muuntaja]
    [ring.middleware.params :refer [wrap-params]])
   (:gen-class))
 
+;; ===== Content Type Configuration =====
+
+(def transit-format
+  "A configured Muuntaja instance that restricts API format negotiation to
+  Transit only (application/transit+json). This instance transforms Clojure
+  data structures to/from Transit format when used with appropriate middleware.
+  The default format is explicitly set to Transit, so requests without
+  an Accept header will receive Transit responses."
+  (-> muuntaja/default-options
+      (update :formats select-keys ["application/transit+json"])
+      (assoc :default-format "application/transit+json")
+      muuntaja/create))
+
+;; ===== Middleware Configuration =====
+
+(def base-middleware
+  "Common middleware applied to all routes for essential functionality."
+  [wrap-params
+   middleware/exception
+   middleware/logging])
+
+(def html-middleware
+  "Middleware specific to HTML routes that ensures responses are properly
+  formatted as text/html."
+  {:data {:middleware (into base-middleware
+                            [middleware/wrap-html-response])}})
+
+(def api-middleware
+  "Middleware for API endpoints that need Transit formatting.
+  Includes JWT authentication setup but doesn't force authentication
+  (individual routes can require auth with the with-auth helper)."
+  {:data {:middleware (into base-middleware
+                            [muuntaja-middleware/format-middleware
+                             rrc/coerce-exceptions-middleware
+                             rrc/coerce-request-middleware
+                             rrc/coerce-response-middleware
+                             middleware/wrap-jwt-authentication])
+          :muuntaja transit-format
+          :coercion rcs/coercion}})
+
+(defn with-auth
+  "Helper function to require authentication for a route."
+  [route-data]
+  (update route-data :middleware (fnil conj []) middleware/jwt-auth))
+
+;; ===== Route Definitions =====
+
 (def html-routes
+  "Public routes that return HTML content. These routes:
+  - Don't require authentication
+  - Return text/html content type
+  - Use the html-middleware stack"
   [["/" {:get {:handler #(pages/home-page %)}}]
    ["/system" {:get {:handler #(pages/system-graph %)}}]
    ["/up" {:get {:handler (fn [_] {:status 200 :body "OK"})}}]
    ["/waitlist-signup" {:post {:handler #(waitlist/signup %)}}]])
 
 (def api-routes
-  [["/swagger.json"
-    {:get {:no-doc true
-           :swagger {:info {:title "Parts API"
-                            :description "API for Parts"}}
-           :handler (swagger/create-swagger-handler)}}]
-   ["/api"
+  "API routes that return Transit data. Contains both public and authenticated routes.
+  All routes:
+  - Return application/transit+json content type
+  - Use the api-middleware stack
+
+  Authenticated routes use the with-auth helper to require authentication."
+  [["/api"
     ["/ping"
-     {:get {:swagger {:tags ["Utility"]}
-            :handler (fn [_] {:status 200 :body {:message "Pong!"}})}}]
+     {:get {:handler (fn [_] {:status 200 :body {:message "Pong!"}})}}]
 
     ;; Auth routes
-    ["/auth" {:swagger {:tags ["Authentication"]}}
+    ["/auth"
      ["/login"
       {:post {:handler api.auth/login}}]
      ["/refresh"
       {:post {:handler api.auth/refresh}}]
      ["/logout"
-      {:post {:handler api.auth/logout
-              :middleware [middleware/jwt-auth]}}]]
+      {:post (with-auth {:handler api.auth/logout})}]]
 
     ;; Account routes
-    ["/account" {:swagger {:tags ["Account"]}}
-     [""
-      {:get {:handler api.account/get-account}
-       :patch {:handler api.account/update-account}
-       :delete {:handler api.account/delete-account}
-       :middleware [middleware/jwt-auth]}]
+    ["/account"
      ["/register"
-      {:post {:handler api.account/register-account}}]]
+      {:post {:handler api.account/register-account}}]
+     [""
+      (with-auth {:get {:handler api.account/get-account}
+                  :patch {:handler api.account/update-account}
+                  :delete {:handler api.account/delete-account}})]]
 
     ;; Systems routes
-    ;; TODO: Put these behind jwt-auth middleware once the UI is ready
-    ["/systems" {:swagger {:tags ["Systems"]}
-                 :middleware [middleware/jwt-auth]}
-     ["" {:get {:summary "List all systems for current user"
-                :handler api.systems/list-systems}
-          :post {:summary "Create new system"
-                 :handler api.systems/create-system}}]
+    ["/systems"
+     ["" {:get {:handler api.systems/list-systems}
+          :post {:handler api.systems/create-system}}]
      ["/:id" {:parameters {:path {:id string?}}}
-      ["" {:get {:summary "Get system by ID"
-                 :handler api.systems/get-system}
-           :put {:summary "Update entire system"
-                 :handler api.systems/update-system}
-           :delete {:summary "Delete system"
-                    :handler api.systems/delete-system}}]
-      ["/pdf" {:get {:summary "Generate PDF export of system"
-                     :handler api.systems/export-pdf}}]]]]])
-
-(defn create-handler [routes middleware-config swagger?]
-  (ring/ring-handler
-   (ring/router routes middleware-config)
-   (if swagger?
-     (ring/routes
-      (swagger-ui/create-swagger-ui-handler
-       {:path "/swagger-ui"
-        :url "/swagger.json"
-        :config {:validatorUrl nil
-                 :operationsSorter "alpha"}})
-      (ring/create-default-handler))
-     (ring/create-default-handler))))
+      ["" {:get {:handler api.systems/get-system}
+           :put {:handler api.systems/update-system}
+           :delete {:handler api.systems/delete-system}}]
+      ["/pdf" {:get {:handler api.systems/export-pdf}}]]]]])
 
-(def html-middleware
-  {:data {:middleware [wrap-params
-                       middleware/exception
-                       middleware/logging
-                       middleware/wrap-html-response]}})
+;; ===== Router Configuration =====
 
-(def api-middleware
-  {:data {:middleware [wrap-params
-                       middleware/exception
-                       middleware/logging
-                       [wrap-json-body {:keywords? true}]
-                       wrap-json-response
-                       middleware/wrap-jwt-authentication]
-          :coercion reitit.coercion.spec/coercion}})
-
-(defn app []
-  (let [routes (if (config/dev?)
-                 (concat html-routes api-routes)
-                 html-routes)
-        middleware (if (config/dev?)
-                     (-> html-middleware
-                         (update-in [:data :middleware] concat
-                                    (get-in api-middleware [:data :middleware]))
-                         (assoc-in [:data :coercion]
-                                   (get-in api-middleware [:data :coercion])))
-                     html-middleware)]
-    (middleware/wrap-default-middlewares
-     (create-handler routes middleware (config/dev?)))))
+(defn app
+  "Constructs the application's handler function by combining HTML and API routes
+  with their appropriate middleware configurations. The function:
+
+  1. Creates a single router with all routes, but preserves the middleware
+     configurations for each route type using Reitit's route data mechanism
+
+  2. Wraps the router with the default application middlewares
+
+  This approach ensures proper routing while maintaining the distinct middleware
+  needs of HTML and API routes."
+  []
+  (->
+   ;; Create a single router with both HTML and API routes
+   ;; Each route maintains its specific middleware config through route data
+   (ring/router
+    (concat
+     ;; Apply html-middleware to all HTML routes
+     (for [route html-routes]
+       (let [[path data] route]
+         [path (merge-with merge data (:data html-middleware))]))
+
+     ;; Apply api-middleware to all API routes
+     api-routes)
+    ;; Include the api-middleware configuration for API routes
+    api-middleware)
+
+   ;; Create handler with default not-found
+   (ring/ring-handler (ring/create-default-handler))
+
+   ;; Apply application-wide middleware
+   middleware/wrap-default-middlewares))
 
 (defn schedule-token-cleanup
   "Schedule periodic cleanup of expired refresh tokens using core.async"
@@ -140,22 +177,34 @@
     stop-ch))
 
 (defn start-server
-  "Starts the web server"
+  "Starts the web server with the configured application handler.
+   Returns a function that can be called to stop the server."
   [port]
   (mulog/log ::starting-server :port port)
   (server/run-server (app) {:port port}))
 
 (defn -main
-  "Entry point into the application via clojure.main -M"
+  "Entry point into the application via clojure.main -M.
+   Initializes the application, starts the server, and returns a shutdown function.
+
+   Arguments:
+   - Optional first argument: port number (defaults to 3000)"
   [& args]
   (let [port (or (some-> (first args) Integer/parseInt) 3000)]
+    ;; Set up global logging context
     (mulog/set-global-context!
      {:app-name "Parts" :version "0.1.0-SNAPSHOT"})
     (mulog/log ::application-startup :arguments args :port port)
+
+    ;; Initialize database
     (db/init-db)
+
+    ;; Start server and background processes
     (let [stop-fn (start-server port)
           cleanup-stop-ch (schedule-token-cleanup)]
       (println "Parts: Server started on port" port)
+
+      ;; Return shutdown function
       (fn []
         (stop-fn)
         (async/close! cleanup-stop-ch) ; Signal the cleanup process to stop