Caching token introspection (#298)

* implement caching token introspection

* add tests for caching token introspection

* add docs

Co-authored-by: Mateusz Wójcik <[email protected]>

Author: majk-p

build.sbt

@@ -130,7 +130,7 @@ lazy val `oauth2-cache` = crossProject(JSPlatform, JVMPlatform)
   .jsSettings(jsSettings)
   .dependsOn(oauth2)
 
-// oauth2-cache-cats doesn't have JS support because cats effect does not provide realTimeInstant on JS 
+// oauth2-cache-cats doesn't have JS support because cats effect does not provide realTimeInstant on JS
 lazy val `oauth2-cache-cats` = project
   .settings(
     name := "sttp-oauth2-cache-cats",
@@ -146,7 +146,7 @@ lazy val `oauth2-cache-cats` = project
   )
   .dependsOn(`oauth2-cache`.jvm)
 
-// oauth2-cache-ce2 doesn't have JS support because cats effect does not provide realTimeInstant on JS 
+// oauth2-cache-ce2 doesn't have JS support because cats effect does not provide realTimeInstant on JS
 lazy val `oauth2-cache-ce2` = project
   .settings(
     name := "sttp-oauth2-cache-ce2",

docs/token-introspection.md

@@ -0,0 +1,22 @@
+---
+sidebar_position: 5
+description: Token introspection
+---
+
+Token introspection interface provides one method, that helps you ask the OAuth2 provider details about the token. The response is described in [rfc7662 section 2.2](https://datatracker.ietf.org/doc/html/rfc7662#section-2.2). The only guaranteed field is `active` that determines if the token is still valid.
+
+```scala
+trait TokenIntrospection[F[_]] {
+
+  /** Introspects passed token in OAuth2 provider.
+    *
+    * Successful introspections returns `F[TokenIntrospectionResponse.IntrospectionResponse]`.
+    */
+  def introspect(token: Secret[String]): F[Introspection.TokenIntrospectionResponse]
+
+}
+```
+
+The `oauth2-cache-cats` module provides the cached version of this interface `CachingTokenIntrospection` that allows you to limit the calls to the OAuth2 provider. To use it you need to provide regular `TokenIntrospection`, the cache implementation and the default expiration time, since the introspection response doesn't necessarily provide such information.
+
+The cache implementation can be anything that implements `ExpiringCache` trait, for the out of the box solution use `CatsRefExpiringCache`, but keep in mind the memory consumption - that instance doesn't limit the list of tokens kept.

oauth2-cache-cats/src/main/scala/com/ocadotechnology/sttp/oauth2/cache/cats/CachingTokenIntrospection.scala

@@ -0,0 +1,68 @@
+package com.ocadotechnology.sttp.oauth2.cache.cats
+
+import cats.data.OptionT
+import cats.effect.kernel.Clock
+import cats.effect.kernel.MonadCancelThrow
+import cats.implicits._
+import com.ocadotechnology.sttp.oauth2.Introspection.TokenIntrospectionResponse
+import com.ocadotechnology.sttp.oauth2.Secret
+import com.ocadotechnology.sttp.oauth2.TokenIntrospection
+import com.ocadotechnology.sttp.oauth2.cache.ExpiringCache
+
+import java.time.Instant
+import scala.concurrent.duration._
+
+final class CachingTokenIntrospection[F[_]: Clock: MonadCancelThrow](
+  delegate: TokenIntrospection[F],
+  cache: ExpiringCache[F, Secret[String], TokenIntrospectionResponse],
+  defaultTimeToLive: FiniteDuration
+) extends TokenIntrospection[F] {
+
+  override def introspect(token: Secret[String]): F[TokenIntrospectionResponse] =
+    getFromCache(token).flatMap {
+      case Some(value) => value.pure[F]
+      case None        => fetchAndCache(token)
+    }
+
+  private def getFromCache(token: Secret[String]): F[Option[TokenIntrospectionResponse]] = {
+    for {
+      now      <- OptionT.liftF(Clock[F].realTime) // Using realTime since it's available cross platform
+      response <- OptionT(cache.get(token))
+      result   <- OptionT.when[F, TokenIntrospectionResponse](responseIsUpToDate(now, response))(response)
+    } yield result
+  }.value
+
+  private def fetchAndCache(token: Secret[String]): F[TokenIntrospectionResponse] =
+    for {
+      now    <- Clock[F].realTime
+      nowInstant = Instant.ofEpochMilli(now.toMillis)
+      result <- delegate
+                  .introspect(token)
+                  .flatTap { response =>
+                    cache.put(token, response, responseExpirationOrDefault(nowInstant, response))
+                  }
+    } yield result
+
+  private def responseIsUpToDate(now: FiniteDuration, response: TokenIntrospectionResponse): Boolean =
+    response.exp.map(_.toEpochMilli > now.toMillis).getOrElse(true)
+
+  private def responseExpirationOrDefault(now: Instant, response: TokenIntrospectionResponse): Instant = {
+    val defaultExpirationTime = now.plusNanos(defaultTimeToLive.toNanos)
+    response
+      .exp
+      .filter(_.isBefore(defaultExpirationTime))
+      .getOrElse(defaultExpirationTime)
+  }
+
+}
+
+object CachingTokenIntrospection {
+
+  def apply[F[_]: Clock: MonadCancelThrow](
+    delegate: TokenIntrospection[F],
+    cache: ExpiringCache[F, Secret[String], TokenIntrospectionResponse],
+    defaultTimeToLive: FiniteDuration
+  ): CachingTokenIntrospection[F] =
+    new CachingTokenIntrospection[F](delegate, cache, defaultTimeToLive)
+
+}

oauth2-cache-cats/src/test/scala/com/ocadotechnology/sttp/oauth2/cache/cats/CachingTokenIntrospectionSpec.scala

@@ -0,0 +1,121 @@
+package com.ocadotechnology.sttp.oauth2.cache.cats
+
+import cats.Functor
+import cats.effect.IO
+import cats.effect.Ref
+import cats.effect.kernel.Clock
+import cats.effect.kernel.Outcome.Succeeded
+import cats.effect.testkit.TestContext
+import cats.effect.testkit.TestInstances
+import cats.implicits._
+import com.ocadotechnology.sttp.oauth2.Introspection.TokenIntrospectionResponse
+import com.ocadotechnology.sttp.oauth2.Secret
+import com.ocadotechnology.sttp.oauth2.TokenIntrospection
+import org.scalatest.Assertion
+import org.scalatest.matchers.should.Matchers
+import org.scalatest.wordspec.AnyWordSpec
+
+import java.time.Instant
+import scala.concurrent.duration._
+
+class CachingTokenIntrospectionSpec extends AnyWordSpec with Matchers with TestInstances {
+  private implicit val ticker: Ticker = Ticker(TestContext())
+
+  private val testToken: Secret[String] = Secret("secret")
+
+  private def testToken60Seconds(now: Instant): TokenIntrospectionResponse = TokenIntrospectionResponse(
+    active = true,
+    exp = Some(now.plusSeconds(60))
+  )
+
+  private def testToken5Seconds(now: Instant): TokenIntrospectionResponse = TokenIntrospectionResponse(
+    active = true,
+    exp = Some(now.plusSeconds(5))
+  )
+
+  private def testToken2Seconds(now: Instant): TokenIntrospectionResponse = TokenIntrospectionResponse(
+    active = true,
+    exp = Some(now.plusSeconds(2))
+  )
+
+  private val inactiveToken: TokenIntrospectionResponse = TokenIntrospectionResponse(active = false)
+
+  private val testFailedResponse: TokenIntrospectionResponse = TokenIntrospectionResponse(active = false)
+
+  "CachingTokenIntrospection" should {
+    "delegate token retrieval on first call" in runTest { case (delegate, cachingIntrospection) =>
+      for {
+        now    <- Clock[IO].realTimeInstant
+        _      <- delegate.updateTokenResponse(testToken, testToken60Seconds(now))
+        result <- cachingIntrospection.introspect(testToken)
+      } yield result shouldBe testToken60Seconds(now)
+    }
+
+    "return cached response if it's not yet expired" in runTest { case (delegate, cachingIntrospection) =>
+      for {
+        now    <- Clock[IO].realTimeInstant
+        _      <- delegate.updateTokenResponse(testToken, testToken60Seconds(now))
+        _      <- cachingIntrospection.introspect(testToken)
+        _      <- Clock[IO].sleep(3.seconds)
+        _      <- delegate.updateTokenResponse(testToken, testToken5Seconds(now))
+        result <- cachingIntrospection.introspect(testToken)
+      } yield result shouldBe testToken60Seconds(now)
+    }
+
+    "fetch the new introspection result if the cache has expired" in runTest { case (delegate, cachingIntrospection) =>
+      for {
+        now    <- Clock[IO].realTimeInstant
+        _      <- delegate.updateTokenResponse(testToken, testToken60Seconds(now))
+        _      <- cachingIntrospection.introspect(testToken)
+        _      <- Clock[IO].sleep(61.seconds)
+        _      <- delegate.updateTokenResponse(testToken, inactiveToken)
+        result <- cachingIntrospection.introspect(testToken)
+      } yield result shouldBe inactiveToken
+    }
+
+    "fetch the new introspection result if the cache has reached the default ttl" in runTest { case (delegate, cachingIntrospection) =>
+      for {
+        now    <- Clock[IO].realTimeInstant
+        _      <- delegate.updateTokenResponse(testToken, testToken60Seconds(now))
+        _      <- cachingIntrospection.introspect(testToken)
+        _      <- Clock[IO].sleep(58.seconds)
+        _      <- delegate.updateTokenResponse(testToken, testToken2Seconds(now))
+        result <- cachingIntrospection.introspect(testToken)
+      } yield result shouldBe testToken2Seconds(now)
+    }
+
+  }
+
+  def runTest(test: ((TestTokenIntrospection[IO], CachingTokenIntrospection[IO])) => IO[Assertion]): Assertion =
+    unsafeRun(prepareTest.flatMap(test)) match {
+      case Succeeded(Some(assertion)) => assertion
+      case wrongResult                => fail(s"Test should finish successfully. Instead ended with $wrongResult")
+    }
+
+  private def prepareTest: IO[(TestTokenIntrospection[IO], CachingTokenIntrospection[IO])] =
+    for {
+      state <- Ref.of[IO, Map[Secret[String], TokenIntrospectionResponse]](Map.empty)
+      cache <- CatsRefExpiringCache[IO, Secret[String], TokenIntrospectionResponse]
+      delegate = TestTokenIntrospection(state)
+      cachingIntrospection = CachingTokenIntrospection[IO](delegate, cache, 5.seconds)
+    } yield (delegate, cachingIntrospection)
+
+  trait TestTokenIntrospection[F[_]] extends TokenIntrospection[F] {
+    def introspect(token: Secret[String]): F[TokenIntrospectionResponse]
+    def updateTokenResponse(token: Secret[String], response: TokenIntrospectionResponse): F[Unit]
+  }
+
+  object TestTokenIntrospection {
+
+    def apply[F[_]: Functor](ref: Ref[F, Map[Secret[String], TokenIntrospectionResponse]]): TestTokenIntrospection[F] =
+      new TestTokenIntrospection[F] {
+        def introspect(token: Secret[String]): F[TokenIntrospectionResponse] =
+          ref.get.map(_.get(token).getOrElse(testFailedResponse))
+
+        def updateTokenResponse(token: Secret[String], response: TokenIntrospectionResponse): F[Unit] =
+          ref.update(state => state + (token -> response))
+      }
+
+  }
+
+}