feat: client info 정보 추출 interceptor 추가 (#372)

* feat: create client info interceptor

* feat: add client info interceptor to webconfig

* refactor: userId -> clientId

* feat: seperate client info dto from interceptor

* refactor: setter as internal

* feat: seperate client info holder to context package

* refactor: remove redundant let

* feat: seperate info context inteface

* comment: add kdoc comments

* fix: fix getter override issue

* test: add test for client info interceptor

Author: huGgW

src/main/kotlin/com/wafflestudio/csereal/common/config/WebConfig.kt

@@ -1,15 +1,18 @@
 package com.wafflestudio.csereal.common.config
 
+import com.wafflestudio.csereal.common.interceptor.ClientInfoInterceptor
 import com.wafflestudio.csereal.common.properties.EndpointProperties
 import org.springframework.boot.context.properties.EnableConfigurationProperties
 import org.springframework.context.annotation.Configuration
 import org.springframework.web.servlet.config.annotation.CorsRegistry
+import org.springframework.web.servlet.config.annotation.InterceptorRegistry
 import org.springframework.web.servlet.config.annotation.WebMvcConfigurer
 
 @Configuration
 @EnableConfigurationProperties(EndpointProperties::class)
 class WebConfig(
-    private val endpointProperties: EndpointProperties
+    private val endpointProperties: EndpointProperties,
+    private val clientInfoInterceptor: ClientInfoInterceptor
 ) : WebMvcConfigurer {
 
     override fun addCorsMappings(registry: CorsRegistry) {
@@ -20,4 +23,8 @@ class WebConfig(
             .allowCredentials(true)
             .maxAge(3000)
     }
+
+    override fun addInterceptors(registry: InterceptorRegistry) {
+        registry.addInterceptor(clientInfoInterceptor)
+    }
 }

src/main/kotlin/com/wafflestudio/csereal/common/context/ClientInfoHolder.kt

@@ -0,0 +1,34 @@
+package com.wafflestudio.csereal.common.context
+
+import com.wafflestudio.csereal.common.dto.ClientInfo
+import org.springframework.stereotype.Component
+import org.springframework.web.context.annotation.RequestScope
+
+/**
+ * Provides access to client information within the lifetime of a single HTTP request.
+ *
+ * Implementations are expected to be request-scoped so that each request receives
+ * its own instance and associated [ClientInfo].
+ */
+interface ClientInfoContext {
+    val clientInfo: ClientInfo
+}
+
+/**
+ * Request-scoped holder that stores client information for the current request.
+ *
+ * This concrete implementation is intended to be populated by an interceptor
+ * (e.g., [com.wafflestudio.csereal.common.interceptor.ClientInfoInterceptor])
+ * before controller logic executes.
+ */
+@Component
+@RequestScope
+class ClientInfoHolder : ClientInfoContext {
+    /**
+     * Client information captured for the current request.
+     *
+     * This property is initialized by the request processing pipeline, typically
+     * in [com.wafflestudio.csereal.common.interceptor.ClientInfoInterceptor].
+     */
+    override lateinit var clientInfo: ClientInfo
+}

src/main/kotlin/com/wafflestudio/csereal/common/dto/ClientInfo.kt

@@ -0,0 +1,37 @@
+package com.wafflestudio.csereal.common.dto
+
+import java.net.InetAddress
+import java.util.*
+
+/**
+ * Client identification details captured from an HTTP request.
+ *
+ * @property ipAddress IP address of the client, resolved to [InetAddress].
+ * @property clientId Optional client identifier as a [UUID]. If absent or invalid,
+ * it remains `null`.
+ */
+data class ClientInfo(
+    val ipAddress: InetAddress,
+    val clientId: UUID? = null
+) {
+    /**
+     * Creates a [ClientInfo] from string representations.
+     *
+     * - [ipAddress]: IPv4/IPv6 string, resolved via [InetAddress.getByName].
+     * - [clientId]: Optional UUID string; invalid values are ignored and treated as `null`.
+     */
+    constructor(ipAddress: String, clientId: String?) : this(
+        ipAddress = ipAddressOf(ipAddress),
+        clientId = clientId?.let { clientIdOfOrNull(it) }
+    )
+
+    /**
+     * Indicates whether this object contains a usable client identifier.
+     *
+     * @return `true` if [clientId] is not `null`, otherwise `false`.
+     */
+    fun isValid() = clientId != null
+}
+
+private fun ipAddressOf(ipAddress: String) = InetAddress.getByName(ipAddress)
+private fun clientIdOfOrNull(clientId: String) = runCatching { UUID.fromString(clientId) }.getOrNull()

src/main/kotlin/com/wafflestudio/csereal/common/interceptor/ClientInfoInterceptor.kt

@@ -0,0 +1,48 @@
+package com.wafflestudio.csereal.common.interceptor
+
+import com.wafflestudio.csereal.common.context.ClientInfoHolder
+import com.wafflestudio.csereal.common.dto.ClientInfo
+import jakarta.servlet.http.HttpServletRequest
+import jakarta.servlet.http.HttpServletResponse
+import org.slf4j.LoggerFactory
+import org.springframework.context.annotation.Configuration
+import org.springframework.web.servlet.HandlerInterceptor
+
+private const val CLIENT_INFO_HEADER = "X-Client-Id"
+private const val FORWARDED_FOR_HEADER = "X-Forwarded-For"
+
+/**
+ * Intercepts incoming HTTP requests to extract client information.
+ *
+ * The interceptor resolves the client's IP address using the `X-Forwarded-For` header
+ * when available, falling back to the remote address. It also reads an optional
+ * `X-Client-Id` header and attempts to parse it as a UUID. The captured data is stored
+ * in a request-scoped [ClientInfoHolder] for downstream usage.
+ */
+@Configuration
+class ClientInfoInterceptor(
+    private val clientInfoHolder: ClientInfoHolder
+) : HandlerInterceptor {
+    private val logger = LoggerFactory.getLogger(this::class.java)
+
+    override fun preHandle(
+        request: HttpServletRequest,
+        response: HttpServletResponse,
+        handler: Any
+    ): Boolean {
+        val ipAddress: String = request.getHeader(FORWARDED_FOR_HEADER)
+            ?.split(",")
+            ?.map { it.trim() }
+            ?.firstOrNull()
+            ?: request.remoteAddr
+        val clientId: String? = request.getHeader(CLIENT_INFO_HEADER)
+
+        val clientInfo = ClientInfo(ipAddress, clientId)
+        logger.info("client info: {}", clientInfo)
+
+        // since only ip address can be used, we set the clientInfo even if it is invalid (no clientId)
+        clientInfoHolder.clientInfo = clientInfo
+
+        return true
+    }
+}

src/test/kotlin/com/wafflestudio/csereal/common/interceptor/ClientInfoInterceptorTest.kt

@@ -0,0 +1,75 @@
+package com.wafflestudio.csereal.common.interceptor
+
+import com.wafflestudio.csereal.common.context.ClientInfoHolder
+import io.kotest.core.spec.style.BehaviorSpec
+import io.kotest.matchers.booleans.shouldBeFalse
+import io.kotest.matchers.booleans.shouldBeTrue
+import io.kotest.matchers.nulls.shouldBeNull
+import io.kotest.matchers.shouldBe
+import io.mockk.every
+import io.mockk.mockk
+import jakarta.servlet.http.HttpServletRequest
+import jakarta.servlet.http.HttpServletResponse
+import java.util.UUID
+
+class ClientInfoInterceptorTest : BehaviorSpec({
+
+    Given("ClientInfoInterceptor with a fresh request-scoped holder") {
+        val clientInfoHolder = ClientInfoHolder()
+        val interceptor = ClientInfoInterceptor(clientInfoHolder)
+
+        When("X-Forwarded-For contains multiple IPs and X-Client-Id is a valid UUID") {
+            val request = mockk<HttpServletRequest>()
+            val response = mockk<HttpServletResponse>(relaxed = true)
+            val validUuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000")
+
+            every { request.getHeader("X-Forwarded-For") } returns "203.0.113.7, 70.41.3.18, 150.172.238.178"
+            every { request.getHeader("X-Client-Id") } returns validUuid.toString()
+            every { request.remoteAddr } returns "198.51.100.23" // should be ignored due to XFF
+
+            interceptor.preHandle(request, response, Any()) shouldBe true
+
+            Then("it should pick the first X-Forwarded-For IP and parse the UUID") {
+                clientInfoHolder.clientInfo.ipAddress.hostAddress shouldBe "203.0.113.7"
+                clientInfoHolder.clientInfo.clientId shouldBe validUuid
+                clientInfoHolder.clientInfo.isValid().shouldBeTrue()
+            }
+        }
+
+        When("X-Forwarded-For is missing and X-Client-Id header is missing") {
+            val request = mockk<HttpServletRequest>()
+            val response = mockk<HttpServletResponse>(relaxed = true)
+
+            every { request.getHeader("X-Forwarded-For") } returns null
+            every { request.getHeader("X-Client-Id") } returns null
+            every { request.remoteAddr } returns "192.0.2.1"
+
+            interceptor.preHandle(request, response, Any()) shouldBe true
+
+            Then("it should fallback to remoteAddr and have no clientId") {
+                clientInfoHolder.clientInfo.ipAddress.hostAddress shouldBe "192.0.2.1"
+                clientInfoHolder.clientInfo.clientId.shouldBeNull()
+                clientInfoHolder.clientInfo.isValid().shouldBeFalse()
+            }
+        }
+
+        When("X-Client-Id is present but invalid UUID") {
+            val request = mockk<HttpServletRequest>()
+            val response = mockk<HttpServletResponse>(relaxed = true)
+
+            every { request.getHeader("X-Forwarded-For") } returns "2001:db8::1, 203.0.113.9"
+            every { request.getHeader("X-Client-Id") } returns "not-a-uuid"
+            every { request.remoteAddr } returns "192.0.2.55"
+
+            interceptor.preHandle(request, response, Any()) shouldBe true
+
+            Then("it should ignore invalid UUID and still capture IP from XFF") {
+                // normalize IPv6 representation because InetAddress may compress zeros
+                val captured = clientInfoHolder.clientInfo.ipAddress.hostAddress
+                (captured == "2001:db8:0:0:0:0:0:1" || captured == "2001:db8::1") shouldBe true
+                clientInfoHolder.clientInfo.clientId.shouldBeNull()
+                clientInfoHolder.clientInfo.isValid().shouldBeFalse()
+            }
+        }
+    }
+})