client-ip

A 0-dependency ring middleware for determining a request’s real client IP address from HTTP headers

doc status: stable Build Status Clojars Project

X-Forwarded-For and other client IP headers are often used incorrectly, resulting in bugs and security vulnerabilities. This library provides strategies for extracting the correct client IP based on your network configuration.

It is based on the golang reference implementation realclientip/realclientip-go.

Quick feature list:

  • ring middleware determining the client’s IP address

  • 0 dependency IP address string parsing with guaranteed no trips to the hosts' DNS services, which can block and timeout (unlike Java’s InetAddress/getByName)

  • rightmost-ish strategies support the X-Forwarded-For and Forwarded (RFC 7239) headers

  • IPv6 zone identifiers support

Note that there is no dependency on ring, the public API could also be used for pedestal or sieppari-style interceptors.

Project status: Stable.

Installation

;; deps.edn
{:deps {com.outskirtslabs/client-ip {:mvn/version "0.1.1"}}}

;; Leiningen
[com.outskirtslabs/client-ip "0.1.1"]

Quick Start

(ns myapp.core
  (:require [ol.client-ip.core :as client-ip]
            [ol.client-ip.strategy :as strategy]))

;; Simple case: behind a trusted proxy that sets X-Real-IP
(def app
  (-> handler
      (client-ip/wrap-client-ip
        {:strategy (strategy/single-ip-header-strategy "x-real-ip")})))

;; The client IP is now available in the request
(defn handler [request]
  (let [client-ip (:ol/client-ip request)]
    {:status 200
     :body (str "Your IP is: " client-ip)}))

For detailed guidance on choosing strategies, see Usage Guide.

Choosing the wrong strategy can result in IP address spoofing security vulnerabilities.

Documentation

You think it is an easy question:

I have an HTTP application, I just want to know the IP address of my client.

But who is the client?

The computer on the other end of the network connection?

But which network connection? The one connected to your HTTP application is probably a reverse proxy or load balancer.

Well I mean the "user’s IP address"

It ain’t so easy kid.

There are many good articles on the internet that discuss the perils and pitfalls of trying to answer this deceptively simple question.

You should read one or two of them to get an idea of the complexity in this space. Libraries, like this one, cannot hide the complexity from you, there is no abstraction nor encapsulation nor "default best practice".

Below are some of those good articles:

Security

See here for security advisories or to report a security vulnerability.

License

Copyright © 2025 Casey Link <casey@outskirtslabs.com>

Distributed under the MIT License.