Composición de FreeMonad

En la entrada anterior, FreeMonad en Cats, realicé una descripción de cómo definir un DSL utilizando una FreeMonad pero, en ciertas situaciones, necesitamos utilizar un segundo DSL conjuntamente con el primero. En la entrada de hoy, Composición de FreeMonad, realizaré un ejemplo de una aplicación que utiliza conjuntamente dos DSL para la definición de un programa.

Presentación del problema

Continuando con las entidades de dominio de la entrada anterior, supongamos que necesitamos realizar la creación de un esquema de base de datos, realizar unas inserciones, eliminar y consultar; es decir, necesitamos un programa que realice unas operaciones básicas de tipo CRUD; pero además, necesitamos que las operaciones sean trazadas en un log en la salida estándar; pudiendo ser de dos tipos: mensajes informativos, tipo info; y, mensajes de depuración, tipo debug.
Para definir un programa que cumpla con estos requisitos necesitamos lo siguiente: definir un DSL para las operaciones en base de datos, definir un DSL para las operaciones de log y un intérprete que entienda el lenguaje de los DSL`s.

Definición de los ADT`s

Definiré dos ADT’s para los dos tipos de operaciones: DBOperations, para el ADT’s de las operaciones en base de datos; y, LogOperation. Antes de definir los ADT’s, definiremos el alias a utilizar. Definimos un alias con nombre Response con un tipo genérico, define un contenedor binario de tipo Either de un tipo Exception y un tipo genérico. La definición del alias es el siguiente:

type Response[A] = Either[Exception, A]

El ADT que define las operaciones de base de datos es el mismo que se utiliza en la entrada anterior, mediante la siguiente estructura de clases:

sealed trait DBOperation[A]
case class Configure(xa: Aux[IO, Unit]) extends DBOperation[Response[Unit]]
case class CreateSchema() extends DBOperation[Response[Boolean]]
case class Insert(author: Author) extends DBOperation[Response[Int]]
case class Select(key: Int) extends DBOperation[Response[Option[String]]]
case class Delete(key: Int) extends DBOperation[Response[Int]]

Las clases definidas definen las siguientes operaciones: clase Configure, define la operación de configuración de Transactor de la base de datos; CreateSchema, creación del esquema de base de datos: Insert, inserción de una entidad Author; Select, seleccionar un autor por clave; Delete, eliminación de un autor por clave.

El ADT que define las operaciones de escritura de log se define mediante la siguiente estructura de clases:

sealed trait LogOperation[A]
case class Info(msg: String) extends LogOperation[Response[Unit]]
case class Debug(msg: String) extends LogOperation[Response[Unit]]

Las clases definidas definen las siguientes operaciones: Info, define la escritura de un mensaje de tipo informativo; Debug, define la escritura de un mensaje de tipo depuración.

En los dos ADT’s, se define como respuesta de la operación el tipo Response.

Definición de los DSL’s

Una FreeMonad permite a un Functor tener la funcionalidad de una mónada; añadir esta funcionalidad, la proporciona el tipo Free[_]. Además, para poder trabajar con otros DSL, es necesario añadir elementos que permitan la unión de los DSL; para ello se utilizan las siguientes herramientas:

  • InjectK[DBOperation, F].- Type class que permite inyectar el tipo DBOperation en el tipo F del contexto de ejecución.
  • Free.inject[DBOperation, F].- Función que permite enlazar el tipo DBOperation al tipo F del contexto de ejecución.

La definición de los DSL`s DBOperations y LogOperations se realiza definiendo una clase y su companion object el cual define una referencia implícita a la instancia de la clase. El código de los DSL`s se definen en el siguiente snippet:

class DBOperations[F[_]](implicit I: InjectK[DBOperation, F]){
  def configure(xa: Aux[IO, Unit]): Free[F, Response[Unit]] = Free.inject[DBOperation, F](Configure(xa))
  def createSchema(): Free[F, Response[Boolean]] = Free.inject[DBOperation, F](CreateSchema())
  def insert(elem: Author): Free[F, Response[Int]] = Free.inject[DBOperation, F](Insert(elem))
  def delete(key: Int): Free[F, Response[Int]] = Free.inject[DBOperation, F](Delete(key))
  def select(key: Int): Free[F, Response[Option[String]]] = Free.inject[DBOperation, F](Select(key))
}
object DBOperations{
  implicit def dboperations[F[_]](implicit I: InjectK[DBOperation, F]) = new DBOperations[F]()
}
class LogOperations[F[_]](implicit I: InjectK[LogOperation, F]){
  def infoLog(msg: String): Free[F, Response[Unit]] = Free.inject[LogOperation, F](Info(msg))
  def debugLog(msg: String): Free[F, Response[Unit]] = Free.inject[LogOperation, F](Debug(msg))
}
object LogOperations{
  implicit def logopearations[F[_]](implicit I: InjectK[LogOperation, F]) = new LogOperations[F]()
}

Definición de los intérpretes

Los intérpretes son los functores de transformación. Realizan la interpretación del DSL, interpretando el lenguaje para el que está definido, ejecuta la funcionalidad requerida y retorna el valor transformado.

El intérprete del DSL DBOperations se define en el objeto DBOperationInterprete el cual es un functor de transformación de un tipo DBOperation a OperationResponse. El tipo OperationResponse es un alias del tipo identidad definido en Cats. El alias se define de la siguiente forma:

type OperationResponse[A] = Id[A]

DBOperationsInterprete define una referencia a un transactor de la librería Doobie con una configuración por defecto, esta configuración es un valor mutable ya que puede ser configurada de forma dinámica. Para todo elemento del ADT, se utiliza el repositorio de Author y se trata el resultado como un tipo OperationResponse[A]. El snippet del código con el intérprete es el siguiente:

object DBOperationsInterpreter extends (DBOperation ~> OperationResponse){
  implicit val cs = IO.contextShift(ExecutionContexts.synchronous)
  // TODO var -> val?
  private var xa = Transactor.fromDriverManager[IO](
    s"com.mysql.jdbc.Driver", s"jdbc:mysql://host:port/doobie", s"user", s"pwd",
    Blocker.liftExecutionContext(ExecutionContexts.synchronous) // just for testing
  )
  override def apply[A](fa: DBOperation[A]) = fa match {
    case Configure(xaTransactor) => {
      this.xa = xaTransactor
      val result: OperationResponse[Response[Unit]] = Right(Unit)
      result
    }
    case CreateSchema() => {
      val resultCreateSchema: Response[Boolean] = AuthorRepository.createSchemaIntoMySqlB(xa)
      val result: OperationResponse[ Response[Boolean]] = resultCreateSchema
      result
    }
    case Insert(author) =>{
      val resultTask: Response[Int] = AuthorRepository.insertAuthorIntoMySql(xa, author)
      val result: OperationResponse[Response[Int]] = resultTask
      result
    }
    case Delete(key) => {
      val resultTask: Response[Int] = AuthorRepository.deleteAuthorById(xa, key)
      val result: OperationResponse[Response[Int]] = resultTask
      result
    }
    case Select(key) => {
      val resultTask: Response[Option[String]] = AuthorRepository.selectAuthorById(xa, key)
      val result: OperationResponse[Response[Option[String]]] = resultTask
      result
    }
  }
}

Para el lector interesado en el código de ejemplo del repositorio Author puede acceder a través del siguiente enlace.

El intérprete del DSL`s de operaciones de Log se define en el objeto LogOperationsInterprete el cual define un functor transformador de un tipo LogOperation a un tipo OperationResponse. El intérprete define las operaciones para los mensajes de tipo info y debug escribiendo mensajes en la salida estándar. El snippet de código con el intérprete es el siguiente:

object LogOperationsInterpreter extends (LogOperation ~> OperationResponse){
  override def apply[A](fa: LogOperation[A]) = fa match {
    case Info(msg) =>
      println(s"[*** INFO] ${msg}")
      val result: OperationResponse[Response[Unit]] = Right(Unit)
      result
    case Debug(msg) =>
      println(s"[*** DEBUG] ${msg}")
      val result: OperationResponse[Response[Unit]] = Right(Unit)
      result
  }
}

Un aspecto importante a destacar es que en los dos funtores de transformación, es decir, los intérpretes, tienen el mismo tipo de salida definido en el alias OperationResponse[A].

Llegado a este punto, tenemos definidos los dos intérpretes de forma individual pero, nos falta la definición del intérprete que comprenda los dos lenguajes; para ello, tenemos que definir un tipo que englobe a los dos ADT de los DSL definidos y, posteriormente, define un functor que transforma del tipo anterior al resultado final.

El tipo DoobiePureComposingApp es un alias que define un tipo EitherK con los tipos DBOperation, LogOperation (ADT de los DSL definidos) y el tipo A. Este tipo comprende los tipos de las gramáticas de los DSL.

type DoobiePureComposingApp[A] = EitherK[DBOperation, LogOperation, A]

El tipo que define el resultado es el tipo identidad de los DSL definidos.

type OperationResponse[A] = Id[A]

Así, la definición del intérprete que engloba a los dos DSL se define de la siguiente forma:

val interpreter: DoobiePureComposingApp ~> OperationResponse = DBOperationsInterpreter or LogOperationsInterpreter

Definición del programa de uso de los DSL

Llegado a este punto, estamos en disposición de declarar un programa que realice operaciones en base de datos de la entidad Author y con capacidad de escribir en un log. Como comentamos al inicio de la entrada, el programa declara un conjunto de operaciones representativas con un objetivo pedagógico. El snippet del código es el siguiente:

implicit val cs = IO.contextShift(ExecutionContexts.synchronous)
final case class DatabaseConfig( host: String, port: String, user: String, password: Secret[String])
def loadEnvironmentVariables(): DatabaseConfig = {
  val host: ConfigValue[String] = env("DDBB_HOST").or(prop("ddbb.host")).as[String]
  val port: ConfigValue[String] = env("DDBB_PORT").or(prop("ddbb.port")).as[String]
  val user: ConfigValue[String] = env("DDBB_USER").or(prop("ddbb.user")).as[String]
  val password: ConfigValue[Secret[String]] = env("DDBB_PWD").secret
  val configureEnv: ConfigValue[DatabaseConfig] = (host, port, user, password).parMapN(DatabaseConfig)
  configureEnv.load[IO].unsafeRunSync()
}
val dataConfigure: DatabaseConfig = loadEnvironmentVariables()
private val xa = Transactor.fromDriverManager[IO](
  "com.mysql.jdbc.Driver",
  s"jdbc:mysql://${dataConfigure.host}:${dataConfigure.port}/doobie",
  s"${dataConfigure.user}",
  s"${dataConfigure.password.value}",
  Blocker.liftExecutionContext(ExecutionContexts.synchronous) // just for testing
)
def programBusiness(xa: Aux[IO, Unit])(implicit DB: DBOperations[DoobiePureComposingApp],
L: LogOperations[DoobiePureComposingApp]): Free[DoobiePureComposingApp, Response[Option[String]]] = {
  import DB._
  import L._
  for {
    _ <- debugLog("Configuring database...")
    _ <- configure(xa)
    _ <- debugLog("Creating database...")
    result <- createSchema()
    numInsert1 <- insert(Author(0, "AuthorTest1"))
    numInsert2 <- insert(Author(0, "AuthorTest2"))
    numDelete1 <- delete(key = 1)
    nameAuthor <- select(key = 2)
    _ <- infoLog("Created Database.")
  } yield {
    nameAuthor
  }
}
val result = programBusiness(xa).foldMap(interpreter)
println(s"Result=${result}")

El código presentado, realiza la carga de la configuración de base de datos desde variables de entorno utilizando la librería Ciris; esta funcionalidad, queda definida en la función loadEnvironmentVariables la cual retorna una clase DatabaseConfig con la configuración; se define el Transactor de la librería Doobie con la configuración la cual es utilizada posteriormente en la declaración del programa; y, por último, se declara el programa en la función programBusiness el cual define como implícitos las referencias a las instancias de los DSL con el tipo DoobiePureComposingApp y, como retorno, un tipo Free con el tipo DoobiePureComposingApp y el tipo de retorno del programa Response[Option[String]].

La salida por consola es la siguiente:

[*** DEBUG] Configuring database…
[*** DEBUG] Creating database…
[*** INFO] Created Database.
Result=Right(Some(AuthorTest2))

Para el lector interesado en el código puede acceder a través del siguiente enlace y, para la entrada en donde explico el uso de la librería Ciris, puede acceder mediante el siguiente enlace

FreeMonad en Cats

Definimos FreeMonad como aquella construcción que permite construir una mónada desde un functor. En la presente entrada, FreeMonad en Cats, describiré cómo definir y utilizar una FreeMonad mediante un ejemplo.

Según Wikipedia, definimos funtor como sigue:

“En teoría de categorías un funtor o functor es una función de una categoría a otra que lleva objetos a objetos y morfismos a morfismos de manera que la composición de morfismos y las identidades se preserven”.

Un functor cumple la propiedad de identidad y de composición.

Según Wikipedia, definimos mónada como sigue:

“En la programación funcional , una mónada (monad en inglés), es una estructura que representa cálculos definidos como una secuencia de pasos”

Una mónada cumple la propiedad de identidad y asociativa.

La FreeMonad permite lo siguiente:

  • Representar cálculos con estado como datos y ejecutarlos.
  • Ejecutar cálculos recursivos.
  • Definir un DSL.
  • Reorientar un cálculo a otro intérprete utilizando transformaciones naturales.

La implementación de FreeMonad que utilizaremos en el ejercicio es aquella que se ha definido en la librería Cats y, el módulo de cats empleado, es el paquete que se define en cats-free. Una FreeMonad se define como Free[_]

La definición de dependencias del módulo sbt en el fichero build.sbt es la siguiente:

lazy val catsEffect = (project in file("cats-effect"))
  .settings(
    name := "example-cats-effect",
    assemblySettings,
    scalacOptions ++= basicScalacOptions,
    libraryDependencies ++=
      catsEffectDependencies ++ Seq(
        scalaTest
      )
  )
lazy val catsEffectDependencies = Seq(
  cats_effect,
  cats_effect_laws
)

La definición de las coordenadas de los paquetes a utilizar en el módulo para la librería cats-free son las siguientes:

lazy val cats_effect_laws = "org.typelevel" %% "cats-effect-laws" % "2.2.0" % "test"
lazy val cats_free = "org.typelevel" %% "cats-free" % "2.2.0"

Presentación del problema

Supongamos que tenemos un aplicativo el cual maneja una entidad Autor y necesitamos persistir los datos de la entidad Autor en base de datos. Para ello, necesitamos realizar operaciones sobre base de datos como son: creación del esquema, insertar, borrar y buscar elementos. La definición de la entidad de dominio del problema se define en la siguiente case class:

case class Author(id:Long, name: String)

Para dar solución a este problema, definiremos un DSL que soporte las funcionalidades requeridas. Evidentemente, es un problema teórico con el objetivo describir la definición de una FreeMonad.

Definición de la gramática

La gramática del DSL queda definida en un ADT (Tipo de dato Algebraico) el cual define las operaciones a realizar. El ADT con las operaciones de base de datos OperationDB[A] queda definido en la siguiente estructura de clases:

sealed trait OperationDB[A]
case class CreateSchema() extends OperationDB[OperationDBResponse[Boolean]]
case class Insert(author: Author) extends OperationDB[OperationDBResponse[Int]]
case class Select(key: Int) extends OperationDB[OperationDBResponseOption[String]]
case class Delete(key: Int) extends OperationDB[OperationDBResponse[Int]]

Las operaciones de base de datos son: CreateSchema, operación para la creación del esquema de la entidad Autor; Insert, operación de inserción de un Autor; Select, búsqueda de un Autor en función de una clave; y, Delete, eliminación de un Autor por clave. El tipo parametrizado es el tipo de retorno de cada operación cuyos tipos son los representados en los siguiente alias:

type OperationDBResponse[A] = Either[Exception, A]
type OperationDBResponseOption[A] = Either[Exception, Option[A]]

Los alias descritos anteriormente define contenedores binarios de Tipo Either cuyo valor Left representa una excepción y, su valor Right, representa el resultado de la operación de tipo A u Option[A]

Definición del DSL

El DSL se define mediante una FreeMonad la cual, utilizando Cats, queda definida con el tipo Free[_]. Así, el alias del tipo de operación del DSL se define utilizando el siguiente alias:

type Operation[A] = Free[OperationDB, A]

El alias Operation[A] define una FreeMonad cuyo valor de entrada es una operación de tipo OperationDB y cuyo resultado es un tipo genérico A.

El DSL debe de definir funciones para las siguientes operaciones: creación de un esquema, inserción, borrado y consulta. Las funciones del DSL son las siguientes:

import cats.free.Free
import cats.free.Free.liftF
[...]
def createSchema(): Operation[OperationDBResponse[Boolean]] =
    liftF[OperationDB, OperationDBResponse[Boolean]](CreateSchema())
def insert(elem: Author): Operation[OperationDBResponse[Int]] =
    liftF[OperationDB, OperationDBResponse[Int]](Insert(elem))
def delete(key: Int): Operation[OperationDBResponse[Int]] =
    liftF[OperationDB, OperationDBResponse[Int]](Delete(key))
def select(key: Int): Operation[OperationDBResponseOption[String]] =
    liftF[OperationDB, OperationDBResponseOption[String]](Select(key))

Las funciones del DSL utilizan la función liftF que permite subir de contexto de una operación OperationDB con un tipo de respuesta a una FreeMonad, Free[_].

Definición del intérprete del DSL

Una vez definido el lenguaje de dominio es necesario definir aquel intérprete que sea capaz de traducir el lenguaje en operaciones de base de datos. En nuestro caso, utilizaremos una entidad repositorio el cual sea capaz de realizar las operaciones de base de datos, consiguiendo desacoplar las operaciones de interpretación del lenguaje con las operaciones directas de base de datos.

El repositorio es un objeto llamado AuthorRepository el cual utiliza la librería funcional Doobie para realizar las operaciones.

Para cada operación del lenguaje, el intérprete gestiona un estado. Los estados son los siguientes: Init, estado inicial que representa el estado previo a la creación del esquema; Created, estado que indica que el esquema ha sido creado; Deleted, estado que representa la eliminación del esquema, en la práctica no se utiliza.

Los estados quedan representados en la siguiente estructura:

sealed trait StateDatabase
case object Init extends StateDatabase
case object Created extends StateDatabase
case object Deleted extends StateDatabase

Dada la existencia de estados, el intérprete utilizará la mónada estado para gestionar el retorno de estado de cada operación.

El intérprete define un functor de transformación, representado por el símbolo ~> el cual transforma entidades de tipo OpearetionDB en OperationState. El functor intérprete recibe como parámetro un Transactor de Doobie de la base de datos con la que se opera. El snippet de código del intérprete es el siguiente:

import cats.~>
[...]
def pureInterpreter(xa: Aux[IO, Unit]): OperationDB ~> OperationState = new(OperationDB ~> OperationState){
override def apply[A](fa: OperationDB[A]): OperationState[A] = fa match {
  case CreateSchema() => {
    val resultCreateSchema: Either[Exception, Boolean] = AuthorRepository.createSchemaIntoMySqlB(xa)
    resultCreateSchema
      .fold( ex => State[StateDatabase, OperationDBResponse[Boolean]]{ state => (Init,  resultCreateSchema) },
        value => State[StateDatabase, OperationDBResponse[Boolean]]{ state => (Created,  resultCreateSchema) } )
  }
  case Insert(author) =>{
    State[StateDatabase, OperationDBResponse[Int]]{ state =>
      (Created,  AuthorRepository.insertAuthorIntoMySql(xa, author))
    }
  }
  case Delete(key) => {
    State[StateDatabase, OperationDBResponse[Int]]{ state =>
      (Created,  AuthorRepository.deleteAuthorById(xa, key))
    }
  }
  case Select(key) => {
    State[StateDatabase, OperationDBResponseOption[String]]{ state =>
      (Created,  AuthorRepository.selectAuthorById(xa, key))
    }
  }
 }
}

Definición del repositorio de la entidad Autor.

El repositorio con las operaciones de base de datos está definiado en un objeto AuthorRepository que utiliza la librería Doobie. El objeto define un conjunto de funciones con las operaciones que utiliza el intérprete del DSL; como ejemplo, la operación de creación del esquema es la siguiente:

val dropAuthor: ConnectionIO[Int] = sql"""DROP TABLE IF EXISTS Author""".update.run
val createAuthor: ConnectionIO[Int] = sql"""CREATE TABLE Author (id SERIAL, name text)""".update.run
def createSchemaIntoMySqlA[A](xa: Aux[IO, Unit]): Either[Exception, Unit] = {
  val creator: ConnectionIO[Unit] = for {
    _ <- dropAuthor
    _ <- createAuthor
  } yield ()
  try{
    val resultDatabase: Unit = creator.transact(xa).unsafeRunSync
    Right(resultDatabase)
  } catch {
    case e: java.sql.SQLException =>{
      println(s"Error create schema: ${e}")
      Left(e)
    }
  }
}

Para el lector interesado en el código del repositorio puede acceder en el siguiente enlace.

Definición de los programas

Una vez definida en un objeto AuthorDSL las funciones del DSL, alias e intérpretes, estamos en disposición de definir las declaraciones de los programas que pueden utilizar dicho lenguaje; para ello, necesitamos importar el DSL y definir el Transactor de base de datos, estas operaciones, se realizan de la siguiente forma:

import doobie.Transactor
import doobie.util.ExecutionContexts
import es.ams.freemonaddoobie.AuthorDSL._
[...]
implicit val cs = IO.contextShift(ExecutionContexts.synchronous)
val xa = Transactor.fromDriverManager[IO](
  "com.mysql.jdbc.Driver",
  "jdbc:mysql://localhost:3306/doobie",
  "root",
  "root",
  Blocker.liftExecutionContext(ExecutionContexts.synchronous) // just for testing
)

Para la correcta ejecución del programa es necesario tener una base de datos levantada en la configuración que se especifica en el Transactor; en mi caso, he utilizado un contenedor Docker con una base de datos MySQL.

La definición de un programa está compuesta por la secuencia de funciones del DSL definidas en un for comprehension y, para su ejecución, se utiliza  la función foldMap con el intérprete definido. Al utilizar la mónada estado, es necesario arrancar la ejecución con un estado.

En los siguientes apartados, se describen ejemplos de las declaraciones de programas del DSL definido

1.- Ejemplo de programa de creación de un esquema.

def createDatabase(): Operation[Either[Exception, Boolean]] = for {
  result <- createSchema()
} yield (result)
val resultCreate = createDatabase().foldMap(pureInterpreter(xa)).run(Init).value
println(s"Create database=${resultCreate}")
println

La salida por consola es la siguiente:

Create database=(Created,Right(true))

2.- Ejemplo de programa de inserción de un Autor en base de datos.

def insertAuthor(): Operation[Either[Exception, Int]] = for {
  num <- insert(Author(0, "Author1"))
} yield (num)
val resultInsertAuthor = insertAuthor().foldMap(pureInterpreter(xa)).run(Created).value
println(s"Insert Author=${resultInsertAuthor}")
Println

La salida por consola es la siguiente:

Insert Author=(Created,Right(1))

3.- Ejemplo de programa de eliminación de un Autor en base de datos.

def deleteAuthor(): Operation[Either[Exception, Int]] = for {
  numInsert10 <- insert(Author(0, "Author10"))
  numInsert11 <- insert(Author(0, "Author11"))
  numInsert12 <- insert(Author(0, "Author12"))
  numDeleted <- delete(2)
} yield (numDeleted)
val resultDeleteAuthor = deleteAuthor().foldMap(pureInterpreter(xa)).run(Created).value
println(s"Delete Author=${resultDeleteAuthor}")
println

La salida por consola es la siguiente:

Delete Author=(Created,Right(1))

4.- Ejemplo de programa de consulta de un autor por clave.

def selectAuthorOK(): Operation[Either[Exception, Option[String]]] = for {
  author <- select(1)
} yield (author)
val resultSelectAuthorOK = selectAuthorOK.foldMap(pureInterpreter(xa)).run(Created).value
println(s"Select Author=${resultSelectAuthorOK}")
println

La salida por consola es la siguiente:

Select Author=(Created,Right(Some(Author1)))

Para el lector interesado puede acceder al código de la entrada en el siguiente enlace.

Ciris

En toda aplicación, es común realizar la carga de configuración desde variables de entorno.En el ecosistema de Scala, la tarea de carga de estos valores los podemos realizar con la solución Ciris. Ciris es una librería funcional que realiza esta funcionalidad. En la presente entrada, Ciris, realizaré una breve descripción de esta librería sencilla.

Definición de dependencias

Ciris está compuesta por un conjunta de paquetes que utilizan otros módulos, como pueden ser: Circe, Refined o Squants; pero, para poder trabajar correctamente, es necesario añadir el paquete refined-cats el cuál no se referencia en la documentación.

La definición de las dependencias necesarias para trabajar con Ciris son las siguientes:

lazy val ciris_ciris = "is.cir" %% "ciris" % "1.2.1"
lazy val ciris_circe = "is.cir" %% "ciris-circe" % "1.2.1"
lazy val ciris_enumeratum = "is.cir" %% "ciris-enumeratum" % "1.2.1"
lazy val ciris_refined = "is.cir" %% "ciris-refined" % "1.2.1"
lazy val ciris_squants = "is.cir" %% "ciris-squants" % "1.2.1"
lazy val ciris_refined_cats = "eu.timepit" %% "refined-cats" % "0.9.18"

Para cargar las dependencias definidas anteriormente en el proyecto, modificamos el fichero build.sbt para realizar la carga del módulo y realizar los ejemplos básicos. El código resultante del fichero de configuración sbt es el siguiente:

import Dependencies._
[...]
lazy val ciris = (project in file("ciris"))
  .settings(
    name := "example-ciris",
    assemblySettings,
    scalacOptions ++= basicScalacOptions,
    libraryDependencies ++=
    cirisDependencies ++ Seq(
      scalaTest
    )
  )
lazy val cirisDependencies = Seq(
  ciris_ciris
  ,ciris_circe
  ,ciris_enumeratum
  ,ciris_refined
  ,ciris_squants
  ,ciris_refined_cats
)

Casos de uso de ejemplo

En el presente apartado, realizaré la presentación de unos ejemplos de prueba de la librería Ciris.

  • Carga de una variable de entorno de tipo entera

Sea la variable de entorno API_PORT=8080 y el siguiente snippet de código el cual realiza lo siguiente: lectura de la varibla API_PORT como entero creando un objeto port de tipo ConfigValue[Int]; el objeto port, es cargado como un tipo IO de cats-effect y la función unsafeRunSync resuelve el valor del tipo IO obteniendo el valor resultado.

def exampleLoadIntENV(): Unit = {
  val port: ConfigValue[Int] = env("API_PORT").or( prop("api.port") ).as[Int]
  val portResult: Int = port.load[IO].unsafeRunSync()
  println(s"Port=${portResult}")
  println()
}

El resultado por pantalla es el siguiente:

Port=8080
  • Carga de variables de entorno en una clase.

Sean las variables de entorno API_PORT=8080 y API_TIMEOUT=100 millis y el siguiente snippet de código el cual realiza lo siguiente: lectura de la varibla API_PORT como entero creando un objeto de tipo ConfigValue[Int]; lectura de la variable API_TIMEOUT de tipo Duration de tipo ConfigValue[Duration]; definición de la clase Config con un campo de tipo entero y otro de tipo Duration; parseo de los dos objetos anteiores para carga los valores de tipo ConfigValue[A] a la clase Config; y, para finalizar, carga del objeto de tipo ConfigValue[Config] como un tipo IO de cats-effect y la función unsafeRunSync resuelve el valor del tipo IO obteniendo el valor resultado.

def exampleLoadPairEnvVar(): Unit = {
  val port: ConfigValue[Int] = env("API_PORT").or( prop("api.port") ).as[Int]
  val timeout: ConfigValue[Option[Duration]] = env("API_TIMEOUT").as[Duration].option
  final case class Config(port: Int, tiemout: Option[Duration])
  val config: ConfigValue[Config] = (port, timeout).parMapN(Config)
  val resultConfig: Config = config.load[IO].unsafeRunSync()
  println(s"Result Config->${resultConfig}")
  println()
}

El siguiente snippet de código es idéntico al anterior pero se utiliza for comprehension.

def exampleLoadWithForCom(): Unit = {
  final case class Config(port: Int, tiemout: Option[Duration])
  val config = for{
    eport <- env("API_PORT").or( prop("api.port") ).as[Int]
    etimeout <- env("API_TIMEOUT").as[Duration].option
  } yield{
    Config(eport, etimeout)
  }
  val result: Config = config.load[IO].unsafeRunSync()
  println(s"Result Config->${result}")
  println()
}

La salida por consola es la siguiente:

Result Config->Config(8080,Some(100 milliseconds))
  • Carga de variable de entorno y valor por defecto

Sean las variables de entorno API_PORT=8080 y API_TIMEOUT=100 millis. Los siguientes snippet de código son idénticos a los anteriores salvo que se utiliza la función default para determinar el valor por defecto: en el primer caso, con un valor de tipo Duration; y, en el segundo, con una clase Config.

def exampleDefaultValue1(): Unit = {
  val timeDefault: ConfigValue[Duration] = env("API_TIME_DEEFAULT").as[Duration].default(10.seconds)
  val result: Duration = timeDefault.load[IO].unsafeRunSync()
  println(s"Result default 1=${result}")
  println()
}
def exampleDefaultValue2(): Unit = {
  final case class Config(port: Int, tiemout: Option[Duration])
  val config = (
    env("API_PORT").or( prop("api.port") ).as[Int],
    env("API_TIMEOUT").as[Duration].option
  ).parMapN(Config).default{
    Config(8082, 20.seconds.some)
  }
  val result: Config = config.load[IO].unsafeRunSync()
  println(s"Result default 2=${result}")
  println()
}

La salida por consola es la siguiente:

Result default 1=10 seconds
Result default 2=Config(8080,Some(100 milliseconds))
  • Carga de variables de entorno con un secreto

Sea la variable de entorno API_KEY=keyRR01234567890123456789. El siguiente snippet realiza la carga de una variable de entorno que representa un secreto; en este caso, se emplea la función secret la cual retorno un objeto de tipo Secret[String]

def exampleSecrets(): Unit = {
  val apiKey: ConfigValue[Secret[String]] = env("API_KEY").secret
  val resultSecret: Secret[String] = apiKey.load[IO].unsafeRunSync()
  println(s"secret=${resultSecret.value}")
  println()
}

La salida por consola es la siguiente:

secret=keyRR01234567890123456789

Para el lector interesado puede acceder al código a través del siguiente enlace.

Scala 3. Dotty II: tipo unión

En la presente entrada, Scala 3. Dotty II: tipo unión, describiré el tipo Unión. El tipo Unión es parecido al tipo intersección descrito en la entrada anterior. El tipo Unión permite que una determinada instancia sea de un tipo determinado o bien de otro. El tipo unión se representa por el símbolo | y cumple la propiedad conmutativa.

En el siguiente ejemplo, se muestra una función con un argumento de tipo unión.

trait TypeA{
  val elemA: String
}
trait TypeB{
  val elemB: String
}
case class ClassTypeA(elemA: String) extends TypeA
case class ClassTypeB(elemB: String) extends TypeB

def printPretty(arg: ClassTypeA | ClassTypeB): Unit = {
  val value = arg match{
    case ClassTypeA(eA) => eA
    case ClassTypeB(eB) => eB
  }
  println(s" Value argument=$value")
}
object Main{
  def main(args: Array[String]): Unit = {
    val a = ClassTypeA("aa")
    val b = ClassTypeB("bb")
    printPretty(a)
    printPretty(b)
  }
}

El código define lo siguiente: se define dos case class de tipo TypeA y TypeB implementadas en las clases ClassTypeA y ClassTypeB; se define una función printPretty cuyo parámetro puede ser del tipo ClassTypeA o bien ClassTypeB; y, para finalizar, se define un objeto Main cuya función main realiza dos llamadas a la función printPretty con dos parámetros con los posibles tipos definidos.

La salida por consola del código es la siguiente:

Value argument=aa
Value argument=bb

Lo más destacado del código anterior es la función printPretty. La función recibe un argumento cuyo tipo puede ser de los tipos definidos ClassTypeA, o bien, ClassTypeB, en función del tipo de entrada, la función escribirá por consola diferentes valores.

En la siguiente entrada, Dotty III: enumeraciones, describiré el tipo enumeración.

AWS Lambda en Scala. Operaciones con AWS S3

Las tres grandes soluciones utilizadas en el mundo empresarial para definir sistemas cloud son Amazon AWS, Microsoft Azure y Google Cloud. Las tres soluciones permiten la posibilidad de desarrollar arquitecturas serverless la cual se implementan con funciones lambda. En la presente entrada, AWS Lambda en Scala. Operaciones con AWS S3, describiré cómo definir una función lambda en Amazon AWS.

 

 

 

 

 

Definimos arquitectura Serverless como aquella arquitectura que define sistemas con aplicaciones y servicios, con capacidad de ejecución, así como, la posibilidad de crear nuevas aplicaciones y servicios, sin necesidad de administrar infraestructura.

Definimos una función Lambda de AWS como “un un servicio informático que permite ejecutar código sin aprovisionar ni administrar servidores. AWS Lambda ejecuta el código sólo cuando es necesario, y se escala de manera automática, pasando de pocas solicitudes al día a miles por segundo”.

Las funciones Lambda pueden ser definidas en diferentes lenguajes como pueden ser: Java, Python, Node, Scala,… en las diferentes plataformas. Dada la diversidad de plataformas y lenguajes, las soluciones son amplias y diversas. Para unificar funcionalidad ante las plataformas y lenguajes existen frameworks que ofrecen operaciones para simplificar la tarea al desarrollador. Un ejemplo de este tipo de tecnología es el framework Serverless.

El framework Serverless es una herramienta Open Source la cual permite el desarrollo y despliegue de aplicaciones serverless en AWS, Azure, Google y otras más.

Instalación en entorno Linux/Mac

La instalación del framework en un entorno Linux o Mac es muy sencilla, simplemente es necesario ejecutar el siguiente comando desde la línea de comando:

curl -o- -L https://slss.io/install | bash

Para la verificación de la instalación, se ejecuta el siguiente comando:

serverless -h

El resultado del comando anterior deberá de mostrar la información de los comandos del framework.

Descripción funcional de la función de ejemplo

Definiremos una función que opere sobre la solución cloud de Amazon. Desde un punto de vista funcional, la función es sencilla, realizará ciertas operaciones con el servicio S3 de AWS descritas en el siguiente listado:

  • Listado de los bucket existentes.
  • Creación de un bucket en S3.
  • Subida de un fichero a S3.
  • Descarga de un fichero a S3.

Creación de la función con Serverless

Para realizar la creación de una función, utilizaremos el comando create del framework Serverless; para ello, en la consola del sistema, crearemos una carpeta (por ejemplo: serverless-scala-aws-s3) y ejecutaremos el comando create de serverless. El snippet copn los comandos son los siguientes:

cd serverless-scala-aws-s3
serverless create --template aws-scala-sbt --path lambda-s3

El comando create emplea la plantilla para un proyecto en Scala con sbt y define el path a la función. Además de la plantilla del lenguaje Scala, se pueden definir funciones en otros lenguajes como Python, Java, kotlin, Go,…

La vista de la estructura creada desde un IDE es el siguiente:

Los componentes del proyecto son los siguientes:

  • build.sbt Fichero sbt para la gestión del ciclo de vida del código de la función. Al tener que operar con S3 se debe de definir la dependencia de la librería AWScala en la referencia libraryDependencies. Las librerías utilizadas en este proyecto son las siguientes:
libraryDependencies ++= Seq(
  "com.amazonaws" % "aws-lambda-java-events" % "2.2.7",
  "com.amazonaws" % "aws-lambda-java-core" % "1.2.0",
  "com.amazonaws" % "aws-lambda-java-log4j2" % "1.1.0",
  "com.github.seratch" %% "awscala" % "0.8.+"
)
  • Componentes de Scala. La plantilla del framework crea automáticamente cuatro componentes, siendo el más importante el Handler de la función.
    • Handler.- El componente handler define dos clases: Handler, para la función lambda a desarrollar; y, ApiGatewayHandler, para definir la clase para el servicio API Gateway; en nuestro caso, nos centraremos en la clase Handler.La clase Handler define un método handleRequest en el cual desarrollaremos la funcionalidad del ejemplo.
import scala.jdk.CollectionConverters._
class Handler extends RequestHandler[Request, Response] {
  val logger: Logger = LogManager.getLogger(getClass)
  def handleRequest(input: Request, context: Context): Response = {
    implicit val region = Region.US_EAST_1
    implicit val s3 = S3()
    val buckets: Seq[Bucket] = s3.buckets
    logger.info(s"\n1 buckets: $buckets \n")
    val bucket: Bucket = s3.createBucket("prueba2fromlambdafunction")
    logger.info(s"\n2 bucket: $bucket \n")
    // Upload operation of the file example1-file.txt with name example1-uploaded-file.txt
    bucket.put("example1-uploaded-file.txt", new java.io.File("example1-file.txt"))
    val s3obj: Option[S3Object] = bucket.getObject("example1-uploaded-file.txt")
    logger.info(s"\n3 Uploaded: ${s3obj.getOrElse("Empty")} \n")
    logger.info(s"Received a request: $input")
    Response("Go Serverless v1.0!!!!! Your function executed successfully!!", input)
  }
}
    • Request.- Define la clase Request con los parámetros del evento de entrada.
import scala.beans.BeanProperty
class Request(@BeanProperty var key1: String, @BeanProperty var key2: String, @BeanProperty var key3: String) {
  def this() = this("", "", "")
  override def toString: String = s"Request($key1, $key2, $key3)"
}
    • Response.- Define la clase respuesta del tipo de retorno del Handler.
import scala.beans.BeanProperty
case class Response(@BeanProperty message: String, @BeanProperty request: Request)
    • ApiGatewayResponse.- Define la clase de respuesta para el caso de APIGateway.
case class ApiGatewayResponse(@BeanProperty statusCode: Integer, @BeanProperty body: String,
@BeanProperty headers: java.util.Map[String, String], @BeanProperty base64Encoded: Boolean = false)
  • Serverless.yml. El fichero serverless.yml es aquel lugar donde se configura la función para que sea desplegada en AWS. El fichero está compuesto por varias secciones en donde se define las variables, la función, o bien, aquellos recursos necesarios de AWS. Este fichero es el que empleará el framework Serverless para definir la plantilla de CloudFormation para su despliegue en AWS. La secciones son:
    • Service.- Definición del nombre del servicio de la función en AWS.
    • Provider.- definición de las variables internas a AWS.
    • Custom.- Definición de las variables específicas para la función como por ejemplo: nombre del proyecto, región,… proporcionada por los valores definidos en Provider, o bien, desde la línea de comando.
    • Environment.- Definición de las variables de entorno globales.
    • Package.- configuración del paquete a crear para realizar la subida a AWS. Se puede definir qué ficheros incluir o excluir, o bien, el nombre del jar con el que se trabaja.
    • Functions.- definición de la función Scala, definición de la referencia del rol, variables de entorno,…
    • Resources.- definición de los recursos empleados por la función en AWS; en nuestro caso, definición del role y las políticas de seguridad.

El contenido del fichero es el siguiente:

service: lambda-s3
provider:
  name: aws
  project: scalaproject
  runtime: java8
  stage: ${opt:stage, 'dev'}
  region: us-east-1
  timeout: 900
  iamRoleStatements:
    - Effect: Allow
      Action:
        - s3:GetObject
        - s3:PutObject
      Resource:
        - "arn:aws:s3:::prueba2fromlambdafunction/*"
custom:
  currentStage: ${opt:stage, self:provider.stage}
  currentProject: ${self:provider.project}
  currentRegion: ${opt:region, self:provider.region}
environment:

package:
  individually: true
  artifact: target/scala-2.13/lambda-s3.jar

functions:
  lambda-s3:
    handler: app.Handler
    role: LambdaRole
    environment:
      ENV: ${self:custom.currentStage}
resources:
  Resources:
    LambdaRole:
      Type: AWS::IAM::Role
      Properties:
        RoleName: ${self:custom.currentProject}-lambda-s3-${self:custom.currentStage}
          AssumeRolePolicyDocument:
          Statement:
            - Effect: Allow
              Principal:
                Service:
                  - lambda.amazonaws.com
              Action: sts:AssumeRole
        Policies:
          - PolicyName: ${self:custom.currentProject}-lambda-s3-${self:custom.currentStage}
            PolicyDocument:
              Statement:
                - Effect: Allow
                  Action:
                    - logs:CreateLogGroup
                    - logs:CreateLogStream
                    - logs:PutLogEvents
                    - s3:*
                  # - ec2:DescribeNetworkInterfaces
                  # - ec2:CreateNetworkInterface
                  # - ec2:DeleteNetworkInterface
                  # - ec2:DescribeInstances
                  # - ec2:AttachNetworkInterface
                 Resource: "*"

De snippet anterior resaltar las líneas comentadas en la definición de los permisos; éstas líneas, corresponden a los permisos que se deben de añadir si se desea que la función Lambda se ejecute en una subred de una VPC determinada.

Ciclo de vida

Configuración del profile de AWS. Para trabajar con AWS es necesario instalar el cliente de AWS y definir las credenciales del usuario para poder realizar las operaciones de despliegue en la cuenta de Amazon.

  • Creación del artefacto. Para realizar el despliegue, es necesario construir el artefacto con los componentes Scala y su ensamblado con las librerías necesarias. El comando SBT a ejecutar en la carpeta de la función es el siguiente:
sbt assembly
  • Despliegue de la función en Amazon AWS. El proceso de despliegue consiste en crear o modificar los recursos en AWS o el código de la función utilizando el stack de cloudformation asociado al fichero serverless.yml. El comando a ejecutar en la carpeta de la función es el siguiente:
serverless deploy -r us-east-1
  • Eliminación de la función. Si se desea eliminar la función se puede eliminar la función y sus recursos asociados con el siguiente:
serverless remove

Librería AWScala

La librería AWScala es aquella librería que permite realizar las operaciones con S3 u otros servicios de AWS. En nuestro caso, nos centraremos en definir las operaciones en S3.

  • Instancia del cliente S3. La creación de un cliente para realizar operaciones con S3 se realiza creando un componente de tipo S3. Dado que la función tiene asociado un role con los permisos de acceso, no es necesario asignar las credenciales. El snippet de ejemplo es el siguiente:
import awscala._, s3._
import awscala.s3._
import awscala.Region
implicit val region = Region.US_EAST_1
implicit val s3 = S3()
  • Listado de los buckets existentes. Una vez creado el cliente, se realiza la conexión al servicio S3 y, con la función buckets, obtenemos una lista con los bucket existentes. El snippet de ejemplo es el siguiente:
val buckets: Seq[Bucket] = s3.buckets
  • Creación de un bucket. De la misma manera que el caso anterior, el cliente S3 tiene una función de creación de bucket cuyo nombre es createBucket al cual se le pasa un nombre único del bucket a crear. El snippet de ejemplo es el siguiente:
val bucket: Bucket = s3.createBucket("prueba2fromlambdafunction")
  • Subir un fichero a S3. Para subir un fichero a S3, el cliente S3 emplea la función put al cual, como primer parámetro, se le pasa el nombre que tendrá en el bucket; y, como segundo parámetro, se le pasa un objeto File con la referencia del fichero. En nuestro caso, existe un fichero de texto example1-file.txt en el proyecto. El snippet de ejemplo es el siguiente:
bucket.put("example1-uploaded-file.txt", new java.io.File("example1-file.txt"))
  • Descarga de un fichero de S3. Para descargar un fichero de S3, el cliente emplea la función getObject a la cual se le pasa como parámetro el nombre del elemento a descargar. El snippet de ejemplo es el siguiente:

val s3obj: Option[S3Object] = bucket.getObject(“example1-uploaded-file.txt”)

Ejecución

Una vez desplegada la función con el comando de serverless deploy, hay que entrar en la consola de AWS y navegaremos hasta la consola de funciones lambda;y,
una vez en la consola, tendremos la referencia a la función. Para las pruebas, crearemos un evento con unos datos de pruebas como los siguientes:

{
"key1": "value1",
"key2": "value2",
"key3": "value3"
}

Para ejecutar la función, pulsaremos el botón de Test en la parte superior derecha; tras la ejecución, se reportará el resultado de la función y se crearán en el cloudwatch las trazas de la función. El aspecto de la consola de AWS con la información de la función es el siguiente:

El resultado de la función en S3 es la creación de un fichero en el bucket prueba2fromlambdafunction. La vista de la consola S3 tras la ejecución de la función es la siguiente:

 

Si el lector está interesado en el código puede acceder al siguiente repositorio de GitHub.

Conclusiones

La selección del lenguaje con el que se opera con AWS depende del equipo de desarrollo ya que, en función del conocimiento de los posibles lenguajes, se seleccionará uno u otro. Desde mi experiencia en los equipos en lod que he trabajado, siempre se ha elegido el lenguaje Python por su sencillez de uso utilizando la librería boto3. Con el presente ejemplo, quiero poner de manifiesto la sencillez con el lenguaje Scala y, dado que estamos construyendo funciones lambda sin infraestructura, utilizar un lenguaje con paradigma funcional permite construir componentes software orientados a la funcionalidad a desarrollar.

Scala 3. Dotty I: Tipos intersección

Inicio una serie de entradas sobre las nuevas características del compilador Dotty el cual representará la versión 3 de Scala que será lanzado en los próximos meses.

Para la realización de los ejemplo, utilizaré el editor de código Scatie. Si el lector está interesado en la descripción del editor, puede acceder al siguiente enlace.

En la presente entrada, me centraré en el operador de intersección de tipos. El operador se representa con el carácter &. La intersección de tipos permite determinar que una instancia puede ser de dos los tipos determinados, es decir, sean dos tipos definidos A y B y una instancia cuya definición de tipo es del tipo A & B, determina que dicha instancia es del tipo A y del tipo A. El operador & es conmutativo con los cual A & B es igual a B & A. A continuación, se muestra el siguiente ejemplo descriptivo:

trait TypeA{
  val elemA: String
}
trait TypeB{
  val elemB: String
}
case class ClassTypeA(elemA: String) extends TypeA
case class ClassTypeB(elemB: String) extends TypeB
case class IntersectionAB(elemA:String, elemB:String) extends TypeA with TypeB

def printPretty(arg: TypeA & TypeB): Unit = println("printPretty:" + arg.elemA + " & " + arg.elemB)
def printPretty2(arg: IntersectionAB): Unit = println("printPretty2:" + arg.elemA + " & " + arg.elemB)

object Main{
  def main(args: Array[String]): Unit = {
    val x = IntersectionAB("aa", "bb")
    printPretty(x)
    println(x)
    val x2 = new IntersectionAB("aa", "bb")
    printPretty(x2)
    println(x2)
    val x3 = new IntersectionAB("aa", "bb")
    printPretty2(x3)
    println(x3)
  }
}

En el ejemplo anterior, se definen dos tipos definidos en los trait TypeA y TypeB; se definen dos case clases de los tipos anteriores cuyos nombres respectivos son ClassTypeA y ClassTypeB; se define una case class IntersectionAB que implementa los tipos anteriores; se define una función printPretty cuyo parámetro es un tipo intersección de los tipos TypeA y TypeB; se define una función printPretty2 cuyo parámetro es del tipo IntersectionAB; y, para finalizar, se define un objeto Main con la función main en donde se instancia objetos intersección y se pasan a las dos funciones de impresión. La funcionalidad de las funciones pretty son sencillas, solo imprimen por consola los tipos pasados por parámetro.

La salida por consola del código es la siguiente:

printPretty:aa & bb
IntersectionAB(aa,bb)
printPretty:aa & bb
IntersectionAB(aa,bb)
printPretty2:aa & bb
IntersectionAB(aa,bb)

Lo más destacado del ejemplo es la función printPretty la cual define un argumento cuyo tipo debe de ser del tipo TypeA y TypeB. Si a la función no se le pasa un objeto con dicha condición, el código no compila.

En la siguiente entrada, Scala 3. Dotty II: uniones de tipo, describeré el tipo unión.

Scastie

Scastie  es un editor de código para trabajar con Scala. Scastie puede ser configurado  para poder operar con las diferentes versiones de Scala (2.12.12 y 2.13.3); puede ser configurado con el nuevo compilador de Scala Dotty; puede ser configurado para trsabajar con TypeLevel; o bien, puede ser configurado para utilizar Scala.js.

Scastie es una muy buena herramienta para realizar pequeños snippet de código para realizar pruebas sencillas sin necesidad de instalar un entorno de trabajo. Scastie tiene dos funciones:

  • Editor de código.- En la parte izquierda, existe la opción “Editor” el cual permite activar el editor de código. El aspecto del editor es el siguiente:

editor

  • Configuración.- En la parte izquierda, exista la opción “Build Settings” el cual permite activar la configuración del editor. El aspecto de la configuración es el siguiente:

settings

Scastie utiliza sbt para la gestión del ciclo de vida y permite la definición de las librerías necesarias como las opciones de configuración.

Analizando la imagen del editor de código en la parte superior, destacamos los siguientes botones de acciones:

  • Save.- Guarda y ejecuta el código.
  • New.- Abre un nuevo snippet de código.
  • Format.- Verificación del estilo del código.
  • Clear Messages.- Elimina los mensajes de error de compilación y error de formateo.
  • Download.- Descarga del código.

En la parte inferior del editor, se encuentra la salida de la consola. En el lateral izquierdo de Scastie, se dispone del botón “Help” el cual muestra la ayuda del editor; y, el botón “Light” el cual permite cambiar el fondo del editor con una opción de fondo oscura y otra de forma clara.

Scastie es una buena herramienta para desarrollar y probar pequeñas cantidades de código. Por otro lado, al permitir ejecutar código en las diferentes versiones de los compiladores, es una buena herramienta para tener un entorno de trabajo para aprender nuevas características, como por ejemplo Dotty, sin necesidad de instalar un entorno local.

Ejecución de Ansible en un contenedor Docker

Ansible es una herramienta open source, gestor de configuración, despliegue y orquestación. Su objetivo es automatizar tareas de IT para aumentar la productiviidad en tareas de configuración y despliegue. El mecanismos utilizado es la definición de playbooks con la declaración de las tareas.

Docker es un proyecto open source que permite el despliegue de aplicaciones en contenedores software en múltiples sistemas operativos.

Para trabajar con Ansible desplegando en un contenedor Docker es necesario definir un contenedor con un servicio SSH para que Ansible se pueda conectar y ejecutar los playbooks que se definen. Para realiizar esta tarea, necesitamos lo siguiente:

  1. Definir el contendor con el servicio SSH
  2. Configurar y definir el playbook de Ansible.

Docker

Lo primero que debemos de realizar es definir una Dockerfile con la configuración de la imagen del contenedor que contenga un servidor SSH. Para ello, nos basaremos en la documentación existente en la documentación de docker.

La modificación a realizar es insertar el valor de la password del usuario root. El resultado del fichero es el siguiente:

FROM ubuntu:16.04
RUN apt-get update && apt-get install -y openssh-server
RUN mkdir /var/run/sshd
RUN echo 'root:root' | chpasswd
RUN sed -i 's/PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config
# SSH login fix. Otherwise user is kicked off after login
RUN sed 's@session\s*required\s*pam_loginuid.so@session optional pam_loginuid.so@g' -i /etc/pam.d/sshd
ENV NOTVISIBLE "in users profile"
RUN echo "export VISIBLE=now" >> /etc/profile
EXPOSE 22
CMD ["/usr/sbin/sshd", "-D"]

Para realizar la construcción de la imagen, debemos de ejecutar el siguiente comando:

docker image build -t alvaroms/ubuntu-serverssh:v1 .

Para arrancar el contenedor con la imagen creada anteriormente, ejecutamos el siguiente comando:

docker container run -d --name dockerssh -p 50022:22 alvaroms/ubuntu-serverssh:v1

Una vez arrancado el contenedor, debemos de obtener la IP asignada; para ello, debemos de inspeccionar la configuración del contenedor para obtener la IP del Gateway; esta operación, la realizamos con el siguiente comando:

docker container inspect dockerssh | grep Gateway

Suponiendo que la Ip obtenida es la 172.17.0.1, la conexión ssh la realizamos con el siguiente comando:

ssh -p 50022 root@172.17.0.1

Para completar la operación, deberemos de introducir la password definida en el fichero Dockerfile.

Ansible

Para trabajar con Ansible he definido un usuario con nombre Ansible y los permisos adecuados.

En el fichero /home/ansible/inventory inserto las siguiente líneas:

[all:vars]
ansible_connection=ssh
ansible_user=root
ansible_ssh_pass=root
[...]
[dockers]
ubuntu-sshserver ansible_port=50022 ansible_host=172.17.0.1

Con estas modificaciones definimos las credenciales de conexión al contenedor Docker y definimos la configuración del contenedor para utilizarla en los playbook.

Definimos una playbook con el cual nos permite instalar Git. El playbook es el siguiente:

--- # install git on target host
- hosts: ubuntu-sshserver
become: yes
tasks:
- name: install git
yum:
name: git
state: latest

Para la ejecución del playbook ejecutamos el siguiente comando:

ansible-playbook -i /home/ansible/inventory ./git-setup.yml

Para verificar la correcta instalación, nos conectamos al contenedor por SSH y obtenemos la versión de git los comandos son:

ssh -p 50022 root@172.17.0.1
docker>git --version

Kotlin, SpringBoot, Docker y DockerCompose III: docker y docker-compose

Finalizamos la serie de artículos de Kotlin y SpringBoot con el presente artículo con título “Kotlin, SpringBoot, Docker y DockerCompose III: docker y docker-compose”. El objetivo de la entrada es dockerizar la aplicación para hacer funcionar la aplicación desarrollada en un contenedor Docker. Además, definiremos la aplicación para que funcione en una composición de contenedores con un contenedor con MySQL.

La serie está compuesta de tres entradas ordenadas de forma cronológica:

La estructura del artículo está compuesto por los siguientes puntos:

  1. Docker
    • Propuesta 1
    • Propuesta 2
    • Propuesta 3
  2. DockerCompose

1.- Docker

La aplicación la podemos dockerizar de tres formas posibles. Las diferencia reside en el tamaño de la imagen resultante.

Propuesta 1

La estrategia consiste en copiar el contenido de la aplicación en el interior de la imagen y posteriormente realizar la creación del artefacto. El snippet con el contenido del Dockerfile es el siguiente:

FROM openjdk:8-jdk-alpine
VOLUME /tmp
RUN mkdir /app
COPY . /app
WORKDIR /app
RUN /app/gradlew build
RUN mv /app/build/libs/*.jar /app/app.jar
ENTRYPOINT ["java","-Djava.security.egd=file:/dev/./urandom","-jar","/app/app.jar"]

Para crear la imagen ejecutamos el siguiente comando docker:

docker image build -t alvaroms/ejem1kotlindocker:v1 .

Para visualizar las imágenes creadas ejecutamos el siguiente comando:

docker image list

El resultado de la ejecución del comando muestra una imagen con un tamaño aproximado a 686MB.

Propuesta 2

La segunda estrategía consigue reducir el tamaño de la imagen. Para ello, se realiza la creación del artefacto fuera de la imagen y se copia al interior de la imagen. Es decir, respecto a la solución anterior, se elimina el paso de construcción del artefacto. Para realizar la creación del artefacto, es necesario definir una tarea de creación del fichero jar mediante una tarea en Gradle. La tarea Gradle es la siguiente:

tasks.register("buildDocker"){
  dependsOn("build")
  doLast{
    fileList("./build/libs").forEach { file ->
      file.copyTo(File("./ejem1kotlindocker.jar"))
    }
  }
}

Como se observa en el snippet anterior, la tarea “buildDocker” tiene una dependencia con la tarea build; una vez ejecutado build, su resultado, generado en la carpeta “./build/libs” del proyecto, se copia a la carpeta raíz del proyecto. Esta tarea debe de ser ejecutada previamente a la construcción de la imagen.

La definición de la imagen en el Dockerfile es la siguiente:

FROM openjdk:8-jdk-alpine
VOLUME /tmp
RUN mkdir /app
WORKDIR /app
EXPOSE 8080
ADD ./ejem1kotlindocker.jar /app/ejem1kotlindocker.jar
ENTRYPOINT ["java", "-jar", "/app/ejem1kotlindocker.jar"]

Para crear la imagen ejecutamos el siguiente comando docker:

docker image build -t alvaroms/ejem1kotlindocker:v2 .

Para visualizar las imagenes creadas ejecutamos el siguiente comando:

docker image list

El resultado de esta forma implica la creación de una imagen con un tamaño aproximado a 149MB. En relación a la primera forma, la reducción del tamaño es notable.

Propuesta 3

La tercera estrategia consiste en fusionar los objetivos de las anteriores. Para ello, primeramente, realizamos la creación del artefacto en una primera capa; posteriormente,
con el artefacto creado, construimos la imagen. Todo ello en el paso de construcción de la imagen y en elmomento de crear la imagen Docker. El snippet con el contenido del Dockerfile es el siguiente:

FROM openjdk AS build
VOLUME /tmp
RUN mkdir /app
COPY . /app
WORKDIR /app
RUN /app/gradlew build
FROM openjdk:8-jdk-alpine

ARG APP_VERSION=1.0.0-SNAPSHOT
ENV database__client=mysql
ENV database__connection__host=mysql
ENV database__connection__user=root
ENV database__connection__password=password
ENV database__connection__database=prueba
ENV SPRING_PROFILES_ACTIVE=dev
LABEL org.label-schema.version=$APP_VERSION
COPY --from=build /app/build/libs/*.jar /app/app.jar
ENTRYPOINT ["java", "-Djava.security.egd=file:/dev/./urandom", "-jar", "/app/app.jar" ]

Con esta opción, definimos las variables de entorno con la configuración por defecto a la base de datos cuyos valores pueden ser pasados por parámetro en la creación de la imagen. De la misma manera que los argumentos necesarios.

Para crear la imagen ejecutamos el siguiente comando docker:

docker image build -t alvaroms/ejem1kotlindocker:v3 --build-arg APP_VERSION=1.0.3-SNAPSHOT .

Para visualizar las imagenes creadas ejecutamos el siguiente comando:

docker image list

El resultado de esta forma implica la creación de una imagen con un tamaño aproximado a 149MB. En relación a la primera forma, la reducción del tamaño es notable;y, respecto a la segunda, no es necesario realizar ninguna operación intermedia. Así, de las tres definiciones de Dockerfile, esta tercera, es la solución más eficiente.

2.- DockerCompose

DockerCompose permite realizar la composición de contenedores interconectados. La definición de la composición se realiza en el fichero docker-compose.yml, ubicado en la raíz del proyecto. La composición se define en base a dos servicios: el primero, mysql, corresponde con un contenedor de una imagen de MySQL; el segundo, kotlindocker, corresponde con la aplicación desarrollada.

Cada contenedor está definida en dos redes: kotlinnetwork, para el contenedor de la aplicación; y, mysqlnetwork, para el contenedor de la base de datos MySQL. La conexión la realiza el servicio de kotlin al tener conexión a las dos redes. Para los volúmenes, se definen un volumen para cada servicio.

Otro detalle importante, reside en qué imagen de la aplicación seleccionamos, o bien, creamos la imagen a partir del código existente: opción build, creamos la imagen a partir del código; e, image, creamos el contenedor a partir de una imagen definida.

El contenido del fichero docker-compose es el siguiente:

version: '3'
services:
  mysql:
    container_name: mysql
    image: mysql:5.7
    environment:
      - MYSQL_DATABASE=prueba
      - MYSQL_ROOT_PASSWORD=password
    ports:
      - 3306:3306
    volumes:
      - mysqlvolume:/var/lib/mysql
    networks:
      - mysqlnetwork
  kotlindocker:
    depends_on:
      - mysql
    container_name: kotlindocker
      # image: alvaroms/ejem1kotlindocker:v4
      build: ./
    environment:
      - SPRING_PROFILES_ACTIVE=dev
    ports:
      - 8087:8080
    volumes:
      - kotlinvolume:/var/lib/kotlin
    networks:
      - kotlinnetwork
      - mysqlnetwork
    volumes:
      kotlinvolume:
      mysqlvolume:
    networks:
      kotlinnetwork:
        driver_opts:
          com.docker.network.bridge.name: kotlinNetwork
      mysqlnetwork:
        driver_opts:
          com.docker.network.bridge.name: MySQLNetwork

Para el lector interesado en el código del proyecto puede acceder en el siguiente enlace

Finalizamos con una reflexión sobre la serie sobre kotlin, Spring Boot y Docker: un punto a tener en cuenta es que el código Kotlin presentado es muy mejorable al no haber aplicado patrones funcionales como los que se pueden presentar con la librería Arrow; con ella, la mejora del código es notable, por ejemplo, utilizando contenedores binarios.

Kotlin, SpringBoot, Docker y DockerCompose II: test unitarios

Continuando con el segundo artículo de la serie con título Kotlin “SpringBoot, Docker y DockerCompose II: test unitarios” en el cual me centraré en cómo definir pruebas unitarias. En la anterior entrada, “Kotlin, SpringBoot, Docker y DockerCompose I”, realicé una descripción de una aplicación básica de ejemplo.

La serie está compuesta de tres entradas ordenadas de forma cronológica:

La estructura del artículo está compuesto por los siguientes puntos:

  1. Test unitarios de controladores
  2. Test unitarios de servicios
  3. Test unitarios de repositorios

Para la realización de pruebas unitarias es necesario definir un conjunto de dependencias en el fichero de configuración de Gradle build.gradle.kts. Las dependencias necesarias son las siguientes:

testImplementation("org.springframework.boot:spring-boot-starter-test")
testImplementation("org.springframework.security:spring-security-config")
testImplementation("org.springframework.security:spring-security-test")
testImplementation("com.nhaarman.mockitokotlin2:mockito-kotlin:2.1.0")

Para realizar las pruebas unitarias es necesario tener definido el fichero con las propiedades para el entorno de pruebas; en el ejemplo, el contenido necesario del fichero application.properties es el siguiente:

spring.datasource.driver-class-name=org.h2.Driver
spring.datasource.url=jdbc:h2:mem:db;DB_CLOSE_DELAY=-1
spring.datasource.username=sa
spring.datasource.password=
kotlindocker.title=ExampleKotlinDocker
kotlindocker.banner.title=Warning
kotlindocker.banner.content=Kotlin application witth docker.

Las pruebas unitarias consiste en realizar test sobre un componente determinado. Si el componente tiene relaciones de asociación, o bien, usa elementos con una funcionalidad concreta, se puede declarar su resultado para realizar la prueba; estos casos, se emplean objetos mock para dichas pruebas.

1.- Test unitarios de controladores

Para definir una prueba unitaria de un controlador, en nuestro caso AppController, definiremos una clase de Test. La clase se test -AppControllerTest- debe de estar declarada con las siguientes anotaciones: @RunWith, @AutoConfigureMockMvc y @SpringBootTest.

La clase AppControllerTest dede tener definida la inyección de las entidades WebApplicationContext y MockMvc. Además, se definen la declaración de los elementos necesarios para moquear, en nuestro caso, la clase BusinessService mediante la anotación @MockBean.

La definición de un test se realiza definiendo funciones con la anotación @Test. En el cuerpo de la función, se declara el comportamiento del objeto moquedo, se lanza la petición al objeto a probar, en nuestro caso, una petición HTTP al enppoint /business/operation1 con los datos necesarios; y, para finalizar, se realiza el chequeo del resultado con las funciones del objeto MarcherAssert. El snippet del código es el siguiente:

@RunWith(SpringRunner::class)
@AutoConfigureMockMvc
@SpringBootTest
class AppControllerTest {
  @Autowired
  private lateinit var webApplicationContext: WebApplicationContext
  @Autowired
  private lateinit var mockMvc: MockMvc
  @MockBean
  private lateinit var businessService: BusinessService
  @org.junit.Before
  fun setup() {
    mockMvc = MockMvcBuilders
      .webAppContextSetup(webApplicationContext)
      .build()
  }
  @Test
  fun `AppControllerTest operation1`(){
    val responseOperation1 = BusinessServiceResponse(message = "MessageTest")
    whenever(businessService.operationBusiness1( any() )).thenReturn( responseOperation1 )
    val result = mockMvc.perform( MockMvcRequestBuilders.get("/business/operation1").accept(MediaType.APPLICATION_JSON) )
      .andExpect(MockMvcResultMatchers.status().isOk)
      .andExpect(MockMvcResultMatchers.content().contentType(MediaType.APPLICATION_JSON))
      .andReturn()
    MatcherAssert.assertThat(result.response.status, CoreMatchers.`is`(HttpStatus.OK.value()))
    verify(businessService).operationBusiness1( any() )
  }
}

2.- Test unitarios de servicios

La declaración de las pruebas unitarias de un servicio de negocio, sigue la misma línea que el de un controlador. En el ejemplo, definiré una prueba unitaria de la operación definida en el
servicio de negocio.

La diferencia radica en lo siguiente: los elementos que deben de ser moquedos, se declaran con la anotación @Mock; y, para el elemento a probar, se emplea la anotación @InjectMocks. La definición de la clase de test está definida exclusivamente con la anotación @RunWith(MockitoJUnitRunner::class). El snippet de la clase es el siguiente:

@RunWith(MockitoJUnitRunner::class)
class BusinessServiceTest {
  @Mock
  private lateinit var authorRepository: AuthorRepository
  @InjectMocks
  private lateinit var businessService: BusinessService
  @Test
  fun `operation1`(){
    val authorMock = Author(login = "loginTest", firstname = "firstNameTest", lastname = "lastnameTest")
    whenever(authorRepository.findByLogin( any() )).thenReturn(
      authorMock
    )
    val request = BusinessServiceRequest(login = "Param1")
    val result = businessService.operationBusiness1(request)
    MatcherAssert.assertThat(result.message, CoreMatchers.`is`( "Param1-" + authorMock.login ))
    verify(authorRepository).findByLogin( any() )
  }
}

3.- Test unitarios de repositorios

La definición de las clases de test de un repositorio deben de tener la anotación @DataJpaTest y, como atributo, la definición de inyección de dependecia de los repositorios a probar. En nuestro caso, definiremos la referencia al repositorio ArticleRepository y, por otro lado, la referencia al EntityManager de test. La prueba de una operación se define en una función creando los datos de entrada, consulta al repositorio y verificación del resultado. El snippet con el código de ejemplo es el siguiente:

@DataJpaTest
class ArticleRepositoryTest {
  @Autowired
  private lateinit var entityManager: TestEntityManager
  @Autowired
  private lateinit var articleRepository: ArticleRepository
  @Test
  fun `When findByIdOrNull then return Article`() {
    val juergen = Author("loginUserTest", "firstnameTest", "lastnameTest")
    val juergenInserted = entityManager.persist(juergen)
    assertThat(juergenInserted).isNotNull
    val article = Article("titleTest", "headLineTest", "ContentTest", juergen)
    val articleInserted = entityManager.persist(article)
    assertThat(articleInserted).isNotNull
      entityManager.flush()
    val found = articleRepository.findByIdOrNull(article.id!!)
    assertThat(found).isEqualTo(article)
  }
}

Para el lector interesado en el código del proyeceto puede acceder al siguiente enlace

En la siguiente entrada, “Kotlin, SpringBoot, Docker y DockerCompose III: docker y docker-compose”, describiré como realizar test unitarios de los elementos de la aplicación.