Skip to content

A Future-free Fs2 native pure FP Redis client

License

Notifications You must be signed in to change notification settings

laserdisc-io/laserdisc

Repository files navigation

LaserDisc

CI Release Known Vulnerabilities Join the chat at https://gitter.im/laserdisc-io/laserdisc License: MIT Scala Steward badge
Maven Central Maven Central Maven Central Maven Central Maven Central Maven Central
Scala.js

LaserDisc is a(nother) Scala driver for Redis, written in Scala from the ground up.

It differentiates itself from the others for having a core layer, which is made up of all the supported Redis commands and the Redis Serialization Protocol (RESP), that is strongly typed and which makes heavy use of shapeless and refined to achieve this. It also provides an implementation of RESP built using scodec.

On top of this, one or more clients can be implemented. The only one currently available out of the box is built using fs2/cats effect but more competing implementations can be added with limited effort. This implementation has found great inspiration from the excellent fs2-kafka library.

What's there:

  • Codecs for Redis' RESP wire format
  • Fully-fledged protocol encapsulating request/response pairs for (almost) all Redis commands
  • Initial version of single-node Redis client. Lots of improvements needed
  • Minimal CLI

What's missing:

  • Everything else :)

Note: the library is still evolving and more features will be added in the future. Even if the binary compatibility will not be guaranteed until version 1.0.0, the semantic versioning strategy will be observed in the process.

Why the name

Two reasons:

  1. "A LaserDisc" is an anagram for "Scala Redis"
  2. LaserDiscs were invented in 1978 (same year I was born) and were so cool (and foundational, more on Wikipedia)

Getting Started

LaserDisc is currently available for Scala 2.12 and 2.13 on the JVM.

Its core (protocol commands and RESP wire format) is also available for Scala.JS.

To add LaserDisc as a dependency to your project just add the following to your build.sbt:

libraryDependencies += "io.laserdisc" %% "laserdisc-fs2" % latestVersion

If you only need protocols (i.e. Redis commands and RESP wire format), you may simply add:

libraryDependencies += "io.laserdisc" %% "laserdisc-core" % latestVersion

Interoperability modules

Support for existing libraries is available via dedicated dependencies.

When an io.circe.Decoder[A] and a io.circe.Encoder[A] are implicilty available, instances of Show[A] and Read[Bulk, A] can be derived for free, just add the following in your build.sbt:

libraryDependecies += "io.laserdisc" %% "laserdisc-circe" % latestVersion 

then, to make use of them, at call site it should be sufficient to just:

import laserdisc.interop.circe._

Note: the derived Show[A] instance uses the most compact string representation of the JSON data structure, i.e. no spacing is used

Example usage

With a running Redis instance on localhost:6379 try running the following:

import cats.effect.{IO, IOApp}
import log.effect.LogWriter
import log.effect.fs2.SyncLogWriter
import cats.syntax.flatMap._

object Main extends IOApp.Simple {

  import laserdisc._
  import laserdisc.all._
  import laserdisc.auto._
  import laserdisc.fs2._

  def redisTest(implicit log: LogWriter[IO]): IO[Unit] =
    RedisClient[IO].to("localhost", 6379).use { client =>
      client.send(
        set("a", 23),
        set("b", 55),
        get[PosInt]("b"),
        get[PosInt]("a")
      ) >>= {
        case (Right(OK), Right(OK), Right(Some(getOfb)), Right(Some(getOfa))) if getOfb.value == 55 && getOfa.value == 23 =>
          log info "yay!"
        case other =>
          log.error(s"something went terribly wrong $other") >>
            IO.raiseError(new RuntimeException("boom"))
      }
    }

  override final def run: IO[Unit] =
    redisTest(SyncLogWriter.consoleLog[IO])
}

This should produce an output similar to the following one:

[debug] - [io-compute-3] Starting connection
[info] - [io-compute-4] Connected to server localhost:6379
[trace] - [io-compute-4] sending Arr(Bulk(SET),Bulk(a),Bulk(23))
[trace] - [io-compute-3] receiving Str(OK)
[trace] - [io-compute-1] sending Arr(Bulk(SET),Bulk(b),Bulk(55))
[trace] - [io-compute-4] receiving Str(OK)
[trace] - [io-compute-0] sending Arr(Bulk(GET),Bulk(b))
[trace] - [io-compute-5] receiving Bulk(55)
[trace] - [io-compute-0] sending Arr(Bulk(GET),Bulk(a))
[trace] - [io-compute-0] receiving Bulk(23)
[info] - [io-compute-5] yay!
[debug] - [io-compute-5] Shutting down connection
[debug] - [io-compute-5] Shutdown complete
[info] - [io-compute-0] Connection terminated: No issues

Dependencies

Shapeless
Maven Central 2.3.10

Fs2 Log Effect Laserdisc Core
Maven Central 3.4.0 0.16.3 Maven Central

Circe Laserdisc Core
Maven Central 0.14.3 Maven Central

Support

YourKit Image

This project is supported by YourKit with monitoring and profiling Tools. YourKit supports open source with innovative and intelligent tools for monitoring and profiling Java and .NET applications. YourKit is the creator of YourKit Java Profiler, YourKit .NET Profiler, and YourKit YouMonitor.

License

LaserDisc is licensed under the MIT License (the "License"); you may not use this software except in compliance with the License.

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.