Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

GDGT-2047: Add ability to proxy /api requests to remote server (#71090)

Stas Gavrylov96f8785d1213
diff --git a/dev/src/dev/server/middleware/proxy.clj b/dev/src/dev/server/middleware/proxy.clj
new file mode 100644
index 00000000000..712db498f8d
--- /dev/null
+++ b/dev/src/dev/server/middleware/proxy.clj
@@ -0,0 +1,199 @@
+(ns dev.server.middleware.proxy
+ "Development-only middleware to proxy API requests to a remote backend."
+ (:require
+ [clj-http.client :as http]
+ [clojure.string :as str]
+ [metabase.config.core :as config]
+ [metabase.util :as u]
+ [metabase.util.log :as log]))
+
+(set! *warn-on-reflection* true)
+
+(defn- remote-api-url
+ "Remote backend URL from MB_REMOTE_API_URL env var. Read at runtime, not compile time."
+ []
+ (config/config-str :mb-remote-api-url))
+
+(defn- api-call?
+ "Is this ring request an API call (exact `/api` or path starts with `/api/`)?"
+ [{:keys [^String uri]}]
+ (or (= uri "/api")
+ (str/starts-with? uri "/api/")))
+
+(defn- build-target-url
+ "Build the full URL for the remote backend."
+ [uri query-string]
+ (str (remote-api-url) uri (when query-string (str "?" query-string))))
+
+(defn- request-method->clj-http-fn
+ "Convert Ring request method keyword to clj-http function."
+ [method]
+ (case method
+ :get http/get
+ :post http/post
+ :put http/put
+ :delete http/delete
+ :patch http/patch
+ :head http/head
+ :options http/options
+ http/get))
+
+(def ^:private allowed-proxy-request-headers
+ #{"accept"
+ "accept-language"
+ "authorization"
+ "content-type"
+ "cookie"
+ "user-agent"})
+
+(def ^:private blocked-proxy-request-headers
+ #{"connection"
+ "content-length"
+ "forwarded"
+ "host"
+ "proxy-authenticate"
+ "proxy-authorization"
+ "te"
+ "trailer"
+ "transfer-encoding"
+ "upgrade"
+ "x-real-ip"})
+
+(defn- blocked-proxy-request-header?
+ [header-name]
+ (or (contains? blocked-proxy-request-headers header-name)
+ (str/starts-with? header-name "x-forwarded-")
+ (str/starts-with? header-name "proxy-")))
+
+(defn- proxy-headers
+ "Filter and prepare headers for proxying using an explicit allowlist and origin rewrite."
+ [headers]
+ (let [forwarded-headers
+ (reduce-kv
+ (fn [result header-name value]
+ (let [normalized-name (u/lower-case-en (name header-name))]
+ (if (and (contains? allowed-proxy-request-headers normalized-name)
+ (not (blocked-proxy-request-header? normalized-name)))
+ (assoc result normalized-name value)
+ result)))
+ {}
+ headers)]
+ (assoc forwarded-headers "origin" (remote-api-url))))
+
+(defn- rewrite-set-cookie
+ "Remove domain and secure attributes from Set-Cookie header so cookies work on localhost."
+ [cookie-value]
+ (-> cookie-value
+ (str/replace #";\s*[Dd]omain=[^;]*" "")
+ (str/replace #";\s*[Ss]ecure" "")
+ (str/replace #";\s*[Ss]ame[Ss]ite=[^;]*" "; SameSite=Lax")))
+
+(defn- find-set-cookie-key
+ "Find the Set-Cookie header key (case-insensitive)."
+ [headers]
+ (some (fn [k] (when (= "set-cookie" (u/lower-case-en (name k))) k))
+ (keys headers)))
+
+(defn- rewrite-response-cookies
+ "Rewrite Set-Cookie headers to work with localhost."
+ [headers]
+ (if-let [cookie-key (find-set-cookie-key headers)]
+ (let [cookies (get headers cookie-key)
+ rewritten (if (sequential? cookies)
+ (mapv rewrite-set-cookie cookies)
+ (rewrite-set-cookie cookies))]
+ (-> headers
+ (dissoc cookie-key)
+ (assoc "Set-Cookie" rewritten)))
+ headers))
+
+(defn- clj-http-cookie->set-cookie-header
+ "Convert a clj-http cookie map entry to a Set-Cookie header string."
+ [[cookie-name {:keys [value path expires max-age http-only]}]]
+ (str cookie-name "=" value
+ (when path (str "; Path=" path))
+ (when expires (str "; Expires=" expires))
+ (when max-age (str "; Max-Age=" max-age))
+ (when http-only "; HttpOnly")
+ "; SameSite=Lax"))
+
+(def ^:private localhost-hosts
+ #{"127.0.0.1" "::1" "localhost"})
+
+(defn- strip-port
+ [host]
+ (cond
+ (nil? host)
+ nil
+
+ (str/starts-with? host "[")
+ (or (second (re-find #"^\[([^\]]+)\](?::\d+)?$" host)) host)
+
+ (> (count (re-seq #":" host)) 1)
+ host
+
+ :else
+ (first (str/split host #":" 2))))
+
+(defn- localhost-request?
+ [{:keys [headers server-name]}]
+ (let [host (or (get headers "host") server-name)]
+ (contains? localhost-hosts (some-> host strip-port u/lower-case-en))))
+
+(defn- add-cookies-to-headers
+ "Convert clj-http :cookies map to Set-Cookie headers."
+ [headers cookies]
+ (if (seq cookies)
+ (let [set-cookie-headers (mapv clj-http-cookie->set-cookie-header cookies)]
+ (assoc headers "Set-Cookie" set-cookie-headers))
+ headers))
+
+(defn- rewrite-response-headers
+ [request raw-headers cookies]
+ (let [localhost? (localhost-request? request)]
+ (cond-> (dissoc raw-headers "transfer-encoding" "content-encoding")
+ localhost? rewrite-response-cookies
+ (and localhost? (seq cookies)) (add-cookies-to-headers cookies))))
+
+(defn- proxy-request
+ "Proxy a request to the remote backend and return the response."
+ {:arglists '([request])}
+ [{:keys [request-method uri query-string headers body], :as request}]
+ (let [target-url (build-target-url uri query-string)
+ http-fn (request-method->clj-http-fn request-method)
+ opts (cond-> {:headers (proxy-headers headers)
+ :throw-exceptions false
+ :as :stream
+ :redirect-strategy :none}
+ body (assoc :body body))]
+ (log/debugf "Proxying %s %s to %s" (name request-method) uri target-url)
+ (try
+ (let [response (http-fn target-url opts)
+ raw-headers (:headers response)
+ cookies (:cookies response)
+ rewritten-headers (rewrite-response-headers request raw-headers cookies)]
+ (log/infof "Proxy %s %s -> %s (cookies-returned=%d)"
+ (name request-method) uri (:status response) (count cookies))
+ {:status (:status response)
+ :headers rewritten-headers
+ :body (:body response)})
+ (catch Exception e
+ (log/errorf e "Error proxying request to %s" target-url)
+ {:status 502
+ :body "Proxy error"}))))
+
+(defn wrap-remote-api-proxy
+ "Middleware that proxies API requests to a remote backend when MB_REMOTE_API_URL is set.
+ Only active in dev mode."
+ [handler]
+ (if-let [url (and config/is-dev? (remote-api-url))]
+ (do
+ (log/infof "Remote API proxy enabled, forwarding /api/* to %s" url)
+ (fn [request respond raise]
+ (if (api-call? request)
+ (try
+ (respond (proxy-request request))
+ (catch Exception e
+ (raise e)))
+ (handler request respond raise))))
+ handler))
diff --git a/dev/test/dev/server/middleware/proxy_test.clj b/dev/test/dev/server/middleware/proxy_test.clj
new file mode 100644
index 00000000000..a75e937393a
--- /dev/null
+++ b/dev/test/dev/server/middleware/proxy_test.clj
@@ -0,0 +1,129 @@
+(ns dev.server.middleware.proxy-test
+ (:require
+ [clj-http.client :as http]
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [dev.server.middleware.proxy :as mw.proxy]
+ [metabase.config.core :as config]
+ [metabase.test :as mt]))
+
+(def ^:private remote-url "https://remote.example.com")
+
+(defn- proxy-request
+ [request]
+ (@#'mw.proxy/proxy-request request))
+
+(defn- run-remote-api-proxy
+ [wrapped-handler request]
+ (let [response (atom nil)]
+ (wrapped-handler request
+ (fn [resp] (reset! response resp))
+ (fn [e] (throw e)))
+ @response))
+
+(deftest proxy-headers-allowlist-test
+ (let [captured-opts (atom nil)]
+ (with-redefs [config/config-str (fn [_] remote-url)
+ http/get (fn [_url opts]
+ (reset! captured-opts opts)
+ {:status 200
+ :headers {}
+ :body "ok"})]
+ (proxy-request {:request-method :get
+ :uri "/api/card/1"
+ :headers {"Accept" "application/json"
+ "Accept-Language" "en-US"
+ "Authorization" "Bearer abc"
+ "Content-Type" "application/json"
+ "Cookie" "metabase.SESSION=abc"
+ "User-Agent" "ring-test"
+ "X-Forwarded-For" "1.2.3.4"
+ "Host" "localhost:3000"
+ "X-Real-IP" "5.6.7.8"
+ "X-Custom" "drop-me"}})
+ (is (= {"accept" "application/json"
+ "accept-language" "en-US"
+ "authorization" "Bearer abc"
+ "content-type" "application/json"
+ "cookie" "metabase.SESSION=abc"
+ "user-agent" "ring-test"
+ "origin" remote-url}
+ (get @captured-opts :headers))))))
+
+(deftest api-path-matching-test
+ (let [proxied? (atom false)
+ local-handler (fn [_request respond _raise]
+ (respond {:status 418
+ :headers {}
+ :body "local"}))]
+ (with-redefs [config/is-dev? true
+ config/config-str (fn [_] remote-url)
+ http/get (fn [_url _opts]
+ (reset! proxied? true)
+ {:status 200
+ :headers {}
+ :body "proxied"})]
+ (let [wrapped-handler (mw.proxy/wrap-remote-api-proxy local-handler)]
+ (reset! proxied? false)
+ (is (= 200
+ (:status (run-remote-api-proxy wrapped-handler
+ {:request-method :get
+ :uri "/api"
+ :headers {"host" "localhost:3000"}}))))
+ (is @proxied?)
+
+ (reset! proxied? false)
+ (is (= 418
+ (:status (run-remote-api-proxy wrapped-handler
+ {:request-method :get
+ :uri "/apiary"
+ :headers {"host" "localhost:3000"}}))))
+ (is (not @proxied?))))))
+
+(deftest cookie-rewrite-localhost-only-test
+ (with-redefs [config/config-str (fn [_] remote-url)
+ http/get (fn [_url _opts]
+ {:status 200
+ :headers {"Set-Cookie" "metabase.SESSION=abc; Domain=remote.example.com; Secure; SameSite=None"}
+ :body "ok"})]
+ (let [localhost-response (proxy-request {:request-method :get
+ :uri "/api/session/properties"
+ :headers {"host" "localhost:3000"}})
+ localhost-cookie (get-in localhost-response [:headers "Set-Cookie"])
+ non-localhost-response (proxy-request {:request-method :get
+ :uri "/api/session/properties"
+ :headers {"host" "devbox.example.com:3000"}})
+ non-localhost-cookie (get-in non-localhost-response [:headers "Set-Cookie"])]
+ (is (string? localhost-cookie))
+ (is (str/includes? localhost-cookie "SameSite=Lax"))
+ (is (not (str/includes? localhost-cookie "Domain=")))
+ (is (not (str/includes? localhost-cookie "Secure")))
+
+ (is (= "metabase.SESSION=abc; Domain=remote.example.com; Secure; SameSite=None"
+ non-localhost-cookie)))))
+
+(deftest proxy-error-response-does-not-leak-details-test
+ (with-redefs [config/config-str (fn [_] remote-url)
+ http/get (fn [_url _opts]
+ (throw (ex-info "Proxy error: upstream timeout 10.2.0.4" {})))]
+ (is (= {:status 502
+ :body "Proxy error"}
+ (select-keys (proxy-request {:request-method :get
+ :uri "/api/session/properties"
+ :headers {"host" "localhost:3000"}})
+ [:status :body])))))
+
+(deftest proxy-logging-does-not-expose-cookie-values-test
+ (with-redefs [config/config-str (fn [_] remote-url)
+ http/get (fn [_url _opts]
+ {:status 200
+ :headers {}
+ :cookies {"metabase.SESSION" {:value "super-secret-session-token"}}
+ :body "ok"})]
+ (mt/with-log-messages-for-level [messages :info]
+ (proxy-request {:request-method :get
+ :uri "/api/session/properties"
+ :headers {"host" "localhost:3000"}})
+ (is (empty?
+ (filter #(str/includes? (:message %) "super-secret-session-token")
+ (messages)))))))
diff --git a/docs/developers-guide/devenv.md b/docs/developers-guide/devenv.md
index 681e8fbcbd6..37a612c74d7 100644
--- a/docs/developers-guide/devenv.md
+++ b/docs/developers-guide/devenv.md
@@ -209,6 +209,17 @@ You can also start a REPL another way (e.g., through your editor) and then call:
To start the server (at `localhost:3000`). This will also set up or migrate your application database. To actually
use Metabase, don't forget to start the frontend as well (e.g. with `bun run build-hot`).
+### Proxying API calls to a remote backend (dev only)
+
+If you want to run the frontend locally but send `/api` requests to a different Metabase backend, set
+`MB_REMOTE_API_URL` when starting your local backend.
+
+```sh
+MB_REMOTE_API_URL="https://your-remote-metabase.example.com" clojure -M:run
+```
+
+This proxy is development-only and only applies to `/api` requests.
+
### Multiple Instances
By default Rspack runs the development server on port `8088`. You can run multiple instances of Metabase on the same machine by specifying a different port for each instance.
diff --git a/src/metabase/server/handler.clj b/src/metabase/server/handler.clj
index 55e0691a5ab..09d57bd1f97 100644
--- a/src/metabase/server/handler.clj
+++ b/src/metabase/server/handler.clj
@@ -63,6 +63,15 @@
(wrap-reload handler {:dirs ["src" "enterprise/backend/src"]}))))
(catch Exception _ nil)))
+(def wrap-remote-api-proxy-dev-mw
+ "In dev, optionally proxy `/api` calls to a remote backend. Returns nil in prod."
+ (try
+ (when (and config/dev-available? (not *compile-files*))
+ (requiring-resolve 'dev.server.middleware.proxy/wrap-remote-api-proxy))
+ (catch Exception e
+ (log/warn e "Failed to load dev remote API proxy middleware")
+ nil)))
+
(def ^:private middleware
"Ring async middleware has the form
@@ -101,6 +110,7 @@
#'mw.misc/bind-request ; bind `metabase.middleware.misc/*request*` for the duration of the request
#'mw.ssl/redirect-to-https-middleware
wrap-reload-dev-mw ; reloads outdated clojure code when --hot flag is passed with the :dev-start alias
+ wrap-remote-api-proxy-dev-mw ; proxies /api/* to remote backend if MB_REMOTE_API_URL is set (dev only)
]
(remove nil?)))