Merge pull request #987 from profunktor/lua-script-extensions

Introduce lua scripting extensions for convenience

Author: mmienko

modules/effects/src/main/scala/dev/profunktor/redis4cats/extensions/luaScripting.scala

@@ -0,0 +1,93 @@
+/*
+ * Copyright 2018-2021 ProfunKtor
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package dev.profunktor.redis4cats.extensions
+
+import cats.effect.kernel.{ Resource, Sync }
+import cats.syntax.all._
+import cats.{ ApplicativeThrow, Functor }
+import dev.profunktor.redis4cats.algebra.Scripting
+import dev.profunktor.redis4cats.effects.ScriptOutputType
+import io.lettuce.core.RedisNoScriptException
+
+object luaScripting {
+
+  final case class LuaScript(contents: String, sha: String)
+
+  object LuaScript {
+
+    def make[F[_]: Functor](redis: Scripting[F, _, _])(contents: String): F[LuaScript] =
+      redis.digest(contents).map(sha => LuaScript(contents, sha))
+
+    /** Helper to load a lua script from resources/lua/{resourceName}. The path to the lua scripts can be configured.
+      * @param redis
+      *   redis commands
+      * @param resourceName
+      *   filename of the lua script
+      * @param pathToScripts
+      *   path to the lua scripts
+      * @return
+      *   [[LuaScript]]
+      */
+    def loadFromResources[F[_]: Sync](redis: Scripting[F, _, _])(
+        resourceName: String,
+        pathToScripts: String = "lua"
+    ): F[LuaScript] =
+      Resource
+        .fromAutoCloseable(
+          Sync[F].blocking(
+            scala.io.Source.fromResource(resource = s"$pathToScripts/$resourceName")
+          )
+        )
+        .evalMap(fileSrc => Sync[F].blocking(fileSrc.mkString))
+        .use(make(redis))
+
+  }
+
+  implicit class LuaScriptingExtensions[F[_]: ApplicativeThrow, K, V](redis: Scripting[F, K, V]) {
+
+    /** Evaluate the cached lua script via it's sha. If the script is not cached, fallback to evaluating the script
+      * directly.
+      * @param luaScript
+      *   the lua script with its content and sha
+      * @param output
+      *   output of script
+      * @param keys
+      *   keys to script
+      * @param values
+      *   values to script
+      * @return
+      *   ScriptOutputType
+      */
+    def evalLua(
+        luaScript: LuaScript,
+        output: ScriptOutputType[V],
+        keys: List[K],
+        values: List[V]
+    ): F[output.R] =
+      redis
+        .evalSha(
+          luaScript.sha,
+          output,
+          keys,
+          values
+        )
+        .recoverWith { case _: RedisNoScriptException =>
+          redis.eval(luaScript.contents, output, keys, values)
+        }
+
+  }
+}

modules/tests/src/test/resources/lua/hsetAndExpire.lua

@@ -0,0 +1,8 @@
+local key = KEYS[1]
+local field = ARGV[1]
+local value = ARGV[2]
+local ttl = tonumber(ARGV[3])
+
+local numFieldsSet = redis.call('hset', key, field, value)
+redis.call('expire', key, ttl)
+return numFieldsSet

modules/tests/src/test/scala/dev/profunktor/redis4cats/RedisClusterSpec.scala

@@ -42,6 +42,8 @@ class RedisClusterSpec extends Redis4CatsFunSuite(true) with TestScenarios {
 
   test("cluster: scripts")(withRedis(scriptsScenario))
 
+  test("cluster: scripts lua extensions")(withRedis(scriptingLuaExtensionsScenario))
+
   test("cluster: functions")(withRedis(functionsScenario))
 
   test("cluster: hyperloglog api")(withRedis(hyperloglogScenario))

modules/tests/src/test/scala/dev/profunktor/redis4cats/RedisSpec.scala

@@ -48,6 +48,8 @@ class RedisSpec extends Redis4CatsFunSuite(false) with TestScenarios {
 
   test("scripts")(withRedis(scriptsScenario))
 
+  test("scripts lua extensions")(withRedis(scriptingLuaExtensionsScenario))
+
   test("functions")(withRedis(functionsScenario))
 
   test("hyperloglog api")(withRedis(hyperloglogScenario))

modules/tests/src/test/scala/dev/profunktor/redis4cats/TestScenarios.scala

@@ -664,6 +664,41 @@ trait TestScenarios { self: FunSuite =>
     } yield ()
   }
 
+  def scriptingLuaExtensionsScenario(redis: RedisCommands[IO, String, String]): IO[Unit] = {
+    import dev.profunktor.redis4cats.extensions.luaScripting._
+
+    for {
+      // hsetAndExpire.lua is an example script
+      hsetAndExpire <- LuaScript.loadFromResources[IO](redis)("hsetAndExpire.lua")
+
+      _ <- redis.hGet(key = "luaExt", field = "x").map(assertEquals(_, None))
+      _ <- redis
+             .evalLua(
+               hsetAndExpire,
+               ScriptOutputType.Integer[String],
+               keys = List("luaExt"),
+               values = List("x", "42", "10")
+             )
+             .map(assertEquals(_, 1L, "1 field, 'x', should be set for key=luaExt"))
+      _ <- redis.hGet(key = "luaExt", field = "x").map(assertEquals(_, "42".some))
+      firstTtl <- redis.ttl("luaExt")
+      _ <- IO(assert(firstTtl.map(_.toSeconds).exists(ttl => ttl > 0 && ttl <= 10)))
+
+      _ <- redis
+             .evalLua(
+               hsetAndExpire,
+               ScriptOutputType.Integer[String],
+               keys = List("luaExt"),
+               values = List("y", "84", "20")
+             )
+             .map(assertEquals(_, 1L, "1 field, 'y', should be set for key=luaExt"))
+      _ <- redis.hGet(key = "luaExt", field = "y").map(assertEquals(_, "84".some))
+      secondTtl <- redis.ttl("luaExt")
+      _ <- IO(assert(secondTtl.map(_.toSeconds).exists(ttl => ttl > 0 && ttl <= 20)))
+      _ <- IO(assert(firstTtl < secondTtl))
+    } yield ()
+  }
+
   def functionsScenario(redis: RedisCommands[IO, String, String]): IO[Unit] = {
     val myFunc =
       """#!lua name=mylib

site/docs/effects/scripting.md

@@ -45,3 +45,46 @@ commandsApi.use { redis => // ScriptCommands[IO, String, String]
 ```
 
 The return type depends on the `ScriptOutputType` you pass and needs to suite the result of the Lua script itself. Possible values are `Integer`, `Value` (for decoding the result using the value codec), `Multi` (for many values) and `Status` (maps to `Unit` in Scala). Scripts can be cached for better performance using `scriptLoad` and then executed via `evalSha`, see the [redis docs]((https://redis.io/commands#scripting)) for details.
+
+### Lua Scripting Extensions
+
+Redis4cats provides useful extensions to the Lua scripting; methods for loading scripts and executing them by their SHA1 are provided.
+
+Suppose you have the following Lua script saved under the project's `resources` folder, `mymodule/src/main/resources/lua/hsetAndExpire.lua)`:
+
+```lua
+local key = KEYS[1]
+local field = ARGV[1]
+local value = ARGV[2]
+local ttl = tonumber(ARGV[3])
+
+local numFieldsSet = redis.call('hset', key, field, value)
+redis.call('expire', key, ttl)
+return numFieldsSet
+```
+
+Then you can load it into Redis and execute via:
+
+```scala mdoc:silent
+import dev.profunktor.redis4cats.extensions.luaScripting._
+
+commandsApi.use { redis => // ScriptCommands[IO, String, String]
+  for {
+    hsetAndExpire <- LuaScript.loadFromResources[IO](redis)("hsetAndExpire.lua")
+    value = "42"
+    ttl = "10"
+    _ <- redis.evalLua(
+      hsetAndExpire,
+      ScriptOutputType.Integer[String],
+      keys = List("mySetKey"),
+      values = List("myField", value, ttl)
+    )
+  } yield ()
+}
+```
+
+The extension api provides the following methods:
+- `LuaScript.make` to create a `LuaScript` instance from a string
+- `LuaScript.loadFromResources` to load a Lua script from resources, path is configurable and defaults to `lua/`
+- `evalLua` method as a shortcut for `evalSha` then falling back to `eval` if the script is not loaded yet
+