DEV Community: Igor Wojda

Refactoring Multi-Module Kotlin Project With Konsist

Igor Wojda — Mon, 04 Sep 2023 15:22:56 +0000

Refactoring Multi-Module Kotlin Project With Konsist

Refactoring is not just about altering code; it’s about enhancing its structure, improving readability, optimizing performance, and keeping things consistent. In this article, we’ll focus on the consistency aspect and refactor a simple imaginary project to unify its codebase.

We will also implement a set of guards to keep things Konsistent in the future. To achieve this we will utilise the Konsist, the Kotlin architectural linter.

Read Introduction to Konsist.

Base Project

Typical projects are complex, they contain many types of classes/interfaces heaving various responsibilities (views, controllers, models, use cases, repositories, etc.). These classes/interfaces are usually spread across different modules and placed in various packages. Refactoring such a project would be too much for a single article, so we will refactor with a starter project heaving 3 modules and 4 use cases — the imaginary MyDiet application.

If you prefer learning by doing you can follow the article steps. Just check out the repository, Open the starter project in the InteliJ IDEA (idea-mydiet-starter) or Android Studio (android-studio-mydiet-starter). To keep things simple this project contains a set of classes to be verified and refactored, not the full-fledge app.

The MyDiet application has feature 3 modules:

featureCaloryCalculator
featureGroceryListGenerator
featureMealPlanner

Each feature module has one or more use cases. Let’s look at the familiar project view from IntelliJ IDEA to get the full project structure:

Let’s look at the content of each use case classes across all feature modules:

    // featureCaloryCalculator module
    class AdjustCaloricGoalUseCase {
        fun run() {
            // business logic
        }

        fun calculateCalories() {
            // business logic
        }
    }

    class CalculateDailyIntakeUseCase {
        fun execute() {
            // business logic
        }
    }

    // featureGroceryListGenerator module
    class CategorizeGroceryItemsUseCase {
        fun categorizeGroceryItemsUseCase() {
            // business logic
        }
    }

    // featureMealPlanner module
    class PlanWeeklyMealsUseCase {
        fun invoke() {
            // business logic
        }
    }

Use case holds the business logic (for simplicity represented here as a comment in the code). At first glance, these use cases look similar but after closer examination, you will notice that the use case class declarations are inconsistent when it comes to method names, number of public methods, and packages. Most likely because these use cases were written by different developers prioritizing developer personal opinions rather than project-specific standards.

Exact rules will vary from project to project, but Konsist API can still be used to define checks tailored for a specific project.

Let’s write a few Konsist tests to unify the codebase.

Guard 1: Unify The UseCase Method Names

Let’s imagine that this is a large-scale project containing many classes in each module and because each module is large we want to refactor each module in isolation. Per module, refactoring will limit the scope of changes and will help with keeping Pull Request smaller. We will focus only on unifying use cases.

The first step of using Konsist is creation of the scope (containing a list of Kotlin files) present in a given module:

    Konsist
        .scopeFromModule("featureCaloryCalculator") // Kotlin files in featureCaloryCalculator module

Now we need to select all classes representing use cases. In this project use case is a class with UseCase name suffix ( .withNameEndingWith(“UseCase”)).

    Konsist
        .scopeFromModule("featureCaloryCalculator")
        .classes()
        .withNameEndingWith("UseCase")

In other projects use case could be represented by the class extending BaseUseCase class (.withAllParentsOf*(BaseUseCase::class)) or every class annotated with the @UseCase annotation (.withAllAnnotationsOf(BaseUseCase::class)).

Now define the assert containing desired checks (the last line of the assert block always has to return a boolean). We will make sure that every use case has a public method with a unified name. We will choose the invoke as a desired method name:

    Konsist
        .scopeFromModule("featureCaloryCalculator")
        .classes()
        .withNameEndingWith("UseCase")
        .assert {
            it.containsFunction { function ->
                function.name == "invoke" && function.hasPublicOrDefaultModifier
            }
        }

Notice that our guard treats the absence of visibility modifier as public, because it is a default Kotlin visibility.

If you would like always heave an explicit public visibility modifier you could use hasPublicModifier property instead.

To make the above check work we need to wrap it in JUnit test:

    @Test
    fun `featureCaloryCalculator classes with 'UseCase' suffix should have a public method named 'invoke'`() {
        Konsist
            .scopeFromModule("featureCaloryCalculator")
            .classes()
            .withNameEndingWith("UseCase")
            .assert {
                it.containsFunction { function ->
                    function.name == "invoke" && function.hasPublicOrDefaultModifier
                }
            }
    }

If you are following with the project add this test to app/src/test/kotlin/UseCaseKonsistTest.kt file. To run Konsist test click on the green arrow (left to the test method name).

After running Konsist test it will complain about lack of the method named invoke in the AdjustCaloricGoalUseCase and CalculateDailyIntakeUseCase classes (featureCaloryCalculator module). Let’s update method names in these classes to make the test pass:

    // featureCaloryCalculator module
    // BEFORE
    class AdjustCaloricGoalUseCase {
        fun run() {
            // business logic
        }

        fun calculateCalories() {
            // business logic
        }
    }

    class CalculateDailyIntakeUseCase {
        fun execute() {
            // business logic
        }
    }

    // AFTER
    class AdjustCaloricGoalUseCase {
        fun invoke() { // CHANGE: Name updated
            // business logic
        }

        fun calculateCalories() {
            // business logic
        }
    }

    class CalculateDailyIntakeUseCase {
        fun invoke() { // CHANGE: Name updated
            // business logic
        }
    }

The next module to refactor is the featureGroceryListGenerator module. Again we will assume that this is a very large module containing many classes and interferes. We can simply copy the test and update the module names:

    @Test
    fun `featureCaloryCalculator classes with 'UseCase' suffix should have a public method named 'invoke'`() {
        Konsist
            .scopeFromModule("featureCaloryCalculator")
            .classes()
            .withNameEndingWith("UseCase")
            .assert {
                it.containsFunction { function ->
                    function.name == "invoke" && function.hasPublicOrDefaultModifier
                }
            }
    }

    @Test
    fun `featureGroceryListGenerator classes with 'UseCase' suffix should have a public method named 'invoke'`() {
        Konsist
            .scopeFromModule("featureGroceryListGenerator")
            .classes()
            .withNameEndingWith("UseCase")
            .assert {
                it.containsFunction { function ->
                    function.name == "invoke" && function.hasPublicOrDefaultModifier
                }
            }
    }

The above approach works, however it leads to unnecessary code duplication. We can do better by creating two scopes for each module and add them:

    @Test
    fun `classes with 'UseCase' suffix should have a public method named 'invoke'`() {
        val featureCaloryCalculatorScope = Konsist.scopeFromModule("featureCaloryCalculator")
        val featureGroceryListGeneratorScope = Konsist.scopeFromModule("featureGroceryListGenerator")

        val refactoredModules = featureCaloryCalculatorScope + featureGroceryListGeneratorScope

        refactoredModules
            .classes()
            .withNameEndingWith("UseCase")
            .assert {
                it.containsFunction { function ->
                    function.name == "invoke" && function.hasPublicOrDefaultModifier
                }
            }
    }

Addition of scopes is possible because KoScope overrides Kotlin plus and plusAssign operators. See Create The Scope for more information.

This time the Konsist test will fail because the CategorizeGroceryItemsUseCase class present in the featureGroceryListGenerator module has an incorrect name. Let’s fix that:

    // featureGroceryListGenerator module
    // BEFORE
    class CategorizeGroceryItemsUseCase {
        fun categorizeGroceryItemsUseCase() {
            // business logic
        }
    }

    // AFTER
    class CategorizeGroceryItemsUseCase {
        fun invoke() { // CHANGE: Name updated
            // business logic
        }
    }

The test is passing. Now we have the last module to refactor. We can add another scope representing Kotlin files in the featureMealPlanner module:

    @Test
    fun `classes with 'UseCase' suffix should have a public method named 'invoke'`() {
        val featureCaloryCalculatorScope = Konsist.scopeFromModule("featureCaloryCalculator")
        val featureGroceryListGeneratorScope = Konsist.scopeFromModule("featureGroceryListGenerator")
        val featureMealPlannerScope = Konsist.scopeFromModule("featureMealPlanner")

        val refactoredModules = 
                 featureCaloryCalculatorScope + 
                 featureGroceryListGeneratorScope +
                 featureMealPlannerScope

        refactoredModules
            .classes()
            .withNameEndingWith("UseCase")
            .assert {
                it.containsFunction { function ->
                    function.name == "invoke" && function.hasPublicOrDefaultModifier
                }
            }
    }

Notice that the featureMealPlanner module is the last module for this particular refactoring, so we can simplify the above code. Rather than creating 3 separate scopes (for each module) and adding them ,we can verify all classes present in the production source set (main) by using Konsist.scopeFromProject():

    @Test
    fun `classes with 'UseCase' suffix should have a public method named 'invoke'`() {
        Konsist
            .scopeFromProject()
            .classes()
            .withNameEndingWith("UseCase")
            .assert {
                it.containsFunction { function ->
                    function.name == "invoke" && function.hasPublicOrDefaultModifier
                }
            }
    }

This time the test will succeed, because the PlanWeeklyMealsUseCase class present in the featureMealPlanner module already has a method named invoke:

    class PlanWeeklyMealsUseCase {
        fun invoke() { // INFO: Already had correct method name
            // business logic
        }
    }

Let’s improve our rule.

Guard 2: Use Case Has Only One Public Method

To verify if every use case present in the project has a single public method we can check the number of public (or default) declarations in the class by using it.numPublicOrDefaultDeclarations() == 1. Instead of writing a new test we can just improve the existing one:

    @Test
    fun `classes with 'UseCase' suffix should have single public method named 'invoke'`() {
      Konsist.scopeFromProject()
          .classes()
          .withNameEndingWith("UseCase")
          .assert {
              val hasSingleInvokeMethod = it.containsFunction { function ->
                  function.name == "invoke" && function.hasPublicOrDefaultModifier
              }

              val hasSinglePublicDeclaration = it.numPublicOrDefaultDeclarations() == 1

              hasSingleInvokeMethod && hasSinglePublicDeclaration
          }
    }

After running this konsist test we will realise that the AdjustCaloricGoalUseCase class has two public methods. To fix we will change visibility of the calculateCalories method to private (we assume it was accidentally exposed):

    // featureCaloryCalculator module
    // BEFORE
    class AdjustCaloricGoalUseCase {
        fun run() {
            // business logic
        }

        fun calculateCalories() {
            // business logic
        }
    }

    // AFTER
    class AdjustCaloricGoalUseCase {
        fun invoke() {
            // business logic
        }

        private fun calculateCalories() { // CHANGE: Visibility updated
            // business logic
        }
    }

Guard 3: Every Use Case Resides in “domain.usecase” package

You may not have noticed yet, but use case package structure is a bit off. Two use cases AdjustCaloricGoalUseCase and CalculateDailyIntakeUseCase classes resides in the com.mydiet package, CategorizeGroceryItemsUseCase class resides in the com.mydiet.usecase package(no s at the end) and PlanWeeklyMealsUseCase class resides in the com.mydiet.usecases package (s at the end):

We will start by verifying if the desired package for each use case is domain.usecase package (prefixed and followed by an number of packages). Updating package names is quite straight forward task so this time we will define guard for all modules and fix all violations in one go. Let’s write a new Konsist test to guard this standard:

    @Test
    fun `classes with 'UseCase' suffix should reside in 'domain', 'usecase' packages`() {
        Konsist.scopeFromProduction()
            .classes()
            .withNameEndingWith("UseCase")
            .assert { it.resideInPackage("..domain.usecase..") }
    }

Two dots .. means zero or more packages.

The test highlighted above will now fail for all use cases because none of them reside in the correct package (none of them reside in the domain package). To fix this we have to simply update the packages (class content is omitted for clarity):

    // BEFORE
    // featureCaloryCalculator module
    package com.mydiet
    class AdjustCaloricGoalUseCase { /* .. */ }

    package com.mydiet
    class CalculateDailyIntakeUseCase{ /* .. */ }

    // featureGroceryListGenerator module
    package com.mydiet.usecase
    class CategorizeGroceryItemsUseCase { /* .. */ }

    // featureMealPlanner module
    package com.mydiet.usecases
    class PlanWeeklyMealsUseCase { /* .. */ }

    // AFTER
    // featureCaloryCalculator module
    package com.mydiet.domain.usecase // CHANGE: Package updated
    class AdjustCaloricGoalUseCase { /* .. */ }

    package com.mydiet.domain.usecase // CHANGE: Package updated
    class CalculateDailyIntakeUseCase{ /* .. */ }

    // featureGroceryListGenerator module
    package com.mydiet.domain.usecase // CHANGE: Package updated
    class CategorizeGroceryItemsUseCase { /* .. */ }

    // featureMealPlanner module
    package com.mydiet.domain.usecase // CHANGE: Package updated
    class PlanWeeklyMealsUseCase { /* .. */ }

Now Konsist tests will succeed. We can improve package naming even more. In a typical project every class present in a feature module would have a package prefixed with the feature name to avoid class redeclaration across different modules. We can retrieve module name (moduleName), and remove feature prefix to get the name of the package. Let’s improve existing test:

    @Test
    fun `classes with 'UseCase' suffix should reside in feature, domain and usecase packages`() {
        Konsist.scopeFromProduction()
            .classes()
            .withNameEndingWith("UseCase")
            .assert {
                /*
                module -> package name:
                featureMealPlanner -> mealplanner
                featureGroceryListGenerator -> grocerylistgenerator
                featureCaloryCalculator -> calorycalculator
                */
                val featurePackageName = it
                  .containingFile
                  .moduleName
                  .lowercase()
                  .removePrefix("feature")

                it.resideInPackage("..${featurePackageName}.domain.usecase..")
            }
    }

And the final fix to update these packages once again:

    // BEFORE
    // featureCaloryCalculator module
    package com.mydiet.domain.usecase
    class AdjustCaloricGoalUseCase { /* .. */ }

    package com.mydiet.domain.usecase
    class CalculateDailyIntakeUseCase{ /* .. */ }

    // featureGroceryListGenerator module
    package com.mydiet.domain.usecase
    class CategorizeGroceryItemsUseCase { /* .. */ }

    // featureMealPlanner module
    package com.mydiet.domain.usecase
    class PlanWeeklyMealsUseCase { /* .. */ }

    // AFTER
    // featureCaloryCalculator module
    package com.mydiet.calorycalculator.domain.usecase // CHANGE: Package updated
    class AdjustCaloricGoalUseCase { /* .. */ }

    package com.mydiet.calorycalculator.domain.usecase // CHANGE: Package updated
    class CalculateDailyIntakeUseCase{ /* .. */ }

    // featureGroceryListGenerator module
    package com.mydiet.grocerylistgenerator.domain.usecase // CHANGE: Package updated
    class CategorizeGroceryItemsUseCase { /* .. */ }

    // featureMealPlanner module
    package com.mydiet.mealplanner.domain.usecase // CHANGE: Package updated
    class PlanWeeklyMealsUseCase { /* .. */ }

All of the uses cases are guarded by set of Konsist tests meaning that project coding standards are enforced.

See mydiet-complete project containing all tests and updated code in the GitHub repository .

The Konsist tests are verifying all classes present in the project at scope creation time meaning that every use case added in the future will be verified by the above guards.

Konsist can help you with guarding even more aspects of the use case. Perhaps you are migrating from RxJava to Kotlin Flow and you would like to verify the type returned by invoke method or verify that every invoke method has an operator modifier. It is also possible to make sure that every use case constructor parameter has a name derived from the type or make sure that there parameters are ordered in desired order (e.g. alphabetically).

Konists tests are intended to run as part of Pull Request code verification, similar to classic unit tests.

Summary

This was a very simple yet comprehensive example demonstrating how Konsist can help with code base unification and enforcement of project-specific rules. Upon inspection, we found inconsistencies in method names and declarations, likely due to multiple developers inputs. To address this, we employ Konsist, a Kotlin architectural linter.

In the real world, projects will be more complex, heaving more classes, interfaces, more modules, and will require more Konsist tests. These guards will slightly differ for every project, but fortunately, they can be captured by Konsist flexible API. With Konsist tests in place, we ensure future additions maintain code consistency, making the codebase more navigable and understandable. The code will be Konsistant.

👉 Follow me on Twitter.

Introducing Konsist: A Cutting-Edge Kotlin Linter

Igor Wojda — Wed, 23 Aug 2023 09:30:00 +0000

Linters are vital tools in software development, helping to enforce code standards and best practices across the code base. By analysing code for errors and inconsistencies, linters improve collaboration, code quality, and adherence to coding standards, especially in complex projects.

Several linters are already available for Kotlin programming language. Rules for some linters may overlap e.g. both ktlint and detekt have a "Formatting Rule Set", however, each linter was created with a different focus in mind:

Ktlint - enforces Kotlin coding conventions. Its rules are mostly focused on code naming and code formatting (spacing, braces, empty blocks, line length, etc) .
Detekt -aimed at finding various code smells. Its rules are mostly focused on code smells, complexity, performance, and potential bugs.

Now you probably wonder why do we need another linter? Why do we need Konsist?

Well, let me tell you a short story…

Meet Jill, The Kotlin Developer

Jill had always been passionate about coding, and the opportunity to work as a Kotlin developer was a dream come true. She had just joined a thriving tech company, eager to contribute her skills and learn from her talented colleagues.

A few days into her role, Jill was assigned her first significant task: adding a new use case to the project. Excitement bubbled within her. This was a chance to prove herself, to make a meaningful impact. The task seemed straightforward enough, but she wanted to make sure she aligned her work with the established patterns of the codebase.

So, Jill began exploring the existing use cases, opening file after file, and digging into the structures and logic. She expected to find a consistent pattern, something that would guide her in crafting the new use case. But what she found was a bit overwhelming - every use case was different…

We all have been here - we join a new project and we need some time to figure out what is going on. Projects are often complex, and often this complexity is a direct result of an inconsistent, tangled and messy code base.

In the lifecycle of a project, as it scales and matures, and as developers come and go, integrating new features, addressing bugs, and applying patches usually compromise the code consistency.

The team can agree on codebase standards, but enforcing them is another story. Developers are not perfect, so it is quite easy to miss a thing or two while reviewing a PR.

Some standards are hard or impossible to guard using existing linters and thus many guards are usually not automated. Without automated guards, the codebase quality tends to degrade over time.

Both ktlint and detekt work on the file level - they are verifying files one by one, checking each file in isolation.

Meet Konsist

Konsist is a new cutting edge linter. Konsist focuses on capturing project-specific coding standards across similar types of code declarations. Let's explore a few high-level usages:

Every child class extending ViewModel must have "ViewModel" suffix
Classes with the @Repository annotation should reside in repository package
The presentation layer (defined by the presentation package) can only access classes from the domain layer (defined by the domain package)
Every use case constructor has alphabetically ordered parameters
Every repository constructor parameter has a name derived from the class name

Konsist provides two types of guards to protect the codebase - declaration guards and architectural guards.

Konsist Declaration Guards

Let's look at some practical applications. Let's review some code examples that demonstrate Konsist API and how it can be used to improve the quality of Kotlin code.

Consider this code snippet containing three declarations - com.myapp.logger package, logLevel property and FileLogger class:
package com.myapp.logger

internal const val logLevel = "debug"

@LoggerEntity
internal class FileLogger(val level: String) : BaseLogger {
   fun log(message: String) {

   } 
}

There are a few things we can check in the above snippet. Let's start with getting the declaration names. The entry point of the Konsist linter is the Konsist class. For start lets query available declarations (of all types) and simply map their names:

Konsist
    .scopeFromProject() // create scope from all project files
    .declarations() // get declarations
    .map { it.name } // "com.myapp.logger", "loglevel", "FileLogger"
    ...

The Konsist API can be mixed with known Kotlin collection processing API (the above map function) providing additional processing and filtering capabilities.

Mapping names will help us to understand how to retrieve various declarations and debug existing guards, however to define actual guards we must also verify whatever or not these declarations meet a certain criteria using assert function.

On a high-level Konsist declaration check contains 3 steps:

Deciding what you want to check - e.g. classes…
Querying the desired declarations - e.g. …extending BaseUseCase class…
Defining an assertion to perform a check - e.g. …must have an internal modifier.

Let's start with checking if all classes extending a BaseLogger class (like above FileLogger) have a name ending withLogger:

Konsist
    .scopeFromProject()
    .classes()
    .withParentClassOf(BaseLogger::class)
    .assert { it.name.endsWith("Logger") }

We can also verify if all classes present in logger package are annotated withLoggerEntity annotation:

Konsist
    .scopeFromProject()
    .classes()
    .resideInPackage("..logger..")
    .assert { it.hasAnnotations("LoggerEntity") }

To make Konsist guard work we need to wrap above code in unit test - we will call such guard a Konstst test:

@Test
fun `classes present in logger package are annotated withLoggerEntity`() {
  Konsist
      .scopeFromProject()
      .classes()
      .resideInPackage("..logger..")
      .assert { it.hasAnnotations("LoggerEntity") }
}

The @Test annotation is part of JUnit framework.

The test name provides description for the given guard, while self explanatory Konsist API allows to easily determine scope of the particular check.

Konsist Architecture Guards

The above examples demonstrate usage of the declaration guards. Konsist also provides a dedicated API for dependency verification that can assist you in guarding application layers. These guards ensure that a given class (which is part of a conceptual layer) can only use classes defined in a different package (another conceptual layer). Consider the following test, which guards the Clean Architecture layers of application residing in com.myapp package:

fun `clean architecture layers have correct dependencies`() {
      Konsist
          .scopeFromProduction()
          .assertArchitecture {
              // Define layers
              val domain = Layer("Domain", "com.myapp.domain..")
              val presentation = Layer("Presentation", "com.myapp.presentation..")
              val data = Layer("Data", "com.myapp.data..")

              // Define architecture assertions
              domain.dependsOnNothing()
              presentation.dependsOn(domain)
              data.dependsOn(domain)
          }
  }

This guard is helpful when architectural layers are stored in packages rather than modules.

Take a read of extensive Konsist documentation and review snippets section for more examples.

Konsist API

Konsist API makes it easy for developers to define custom, concise, and expressive guards to check the correctness of the project code. Konsist can assert every declaration present in code - naming conventions, annotations, order and types of parameters, package structure, inheritance, modifiers, dependencies, architectural layers, and more.

Most linters work fine out of the box providing build-in rules, however, they usually don't scale well - writing a custom rule is often a complex task. It usually requires learning (not so obvious) internal linter extension API and simple conditions may result in quite verbose code. This is where Konsist shines - the Konsist API reflects declarations visible in Kotlin code, so API is much more intuitive for the developers. Konsist API mimics the structure of Kotlin code allowing it to quickly query Kotlin declarations such as files, classes, interfaces, functions, properties etc.

Konsist Project Status

Konsist library has been extensively tested on a variety of Spring and Android projects with both Gradle and Maven build systems. In addition, Konsist has a robust test suite (over 1300 tests and 20 unique CI checks) to prevent regression bugs.
Konsist is safe to use because it is not part of the production code base, but rather only used to verify the code base (similar to JUnit and other testing frameworks).

Konsist API has undergone multiple iterations to make it simpler to use and more versatile. At this stage, Konsist API should allow you to express most of the codebase guards you have in mind.

The Konsist project has reached the 2nd Milestone (Project Status page) and is actively seeking community feedback to help it mature:

Community Engagement

The Konsist project is now at a critical stage where community input is essential to polish it. Currently, the project needs external input and field testing to ensure that it is ready for widespread use. Please play with Konsist, try it out, and let us know what works, what features you would like to see, and what can be improved. Your feedback is crucial at this stage as it will help Konsist to mature.

If you find this project promising, you can show your support by starring it on GitHub, tweeting about it, or writing a blog post. This will help to raise awareness of the project, attract more contributors and mature this project faster.

Thank you for your support! 🙏

Summary

Konsist is a new, flexible linter that allows writing custom, project-specific rules to guard project code consistency. It accomplishes other linters offering a more familiar API that mimics Kotlin code declarations. Konsist fits into continuous integration pipelines and development workflows. For more information please review the Konsist documentation.

Follow me on Twitter(X).

Links: Konsist project repository Konsist documentation Android-Showcase (Android project using Konsist)

Introducing Konsist - cutting-edge Kotlin linter

Igor Wojda — Wed, 23 Aug 2023 08:24:42 +0000

The time has finally come to share the new Kotlin linter with the community. Enjoy!

https://blog.kotlin-academy.com/introducing-konsist-a-cutting-edge-kotlin-linter-d3ab916a5461

I am eager to hear your feedback.

Build A 2FA Server With Kotlin and Ktor

Igor Wojda — Wed, 20 Jan 2021 15:39:22 +0000

In this tutorial, you will write a server that provides an API for Two-factor Authentication (2FA). This API will allow desktop clients, mobile clients, and web clients to utilize two-factor authentication.

To build the application, you will use the Kotlin language and Ktor, an asynchronous framework for creating microservices and web applications.

The complete source code is available on GitHub.

Prerequisites

To follow along with this tutorial, you will need:

IntelliJ IDEA IDE installed (paid or free, community edition).
Ktor plugin for IntelliJ IDEA. This plugin allows you to create a Ktor project using a new project wizard. Open IntelliJ IDEA, go to Preferences, then Plugins, and install a Ktor plugin from the marketplace.

Create A Ktor Project

Open IntelliJ IDEA, then go to File > New > Project.
In the New Project window, select the Ktor project on the left side and press the Next button.
On the next screen, leave the default values and press the Next button.
On the final screen, enter ktor-2fa-server as the application name and press the Finish button.

You have created a Ktor application project.

First endpoint

Open the src/Application.kt file and add a new routing to verify that the application is working:

fun Application.module(testing: Boolean = false) {
    routing {
        get("/") {
            call.respondText("2FA app is working", ContentType.Text.Html)
        }
    }
}

In this tutorial, all the Ktor application code will be stored in the Application.kt file.

Click on the green arrow next to the main function to run the application (this will create a new run configuration in the IDE):

Navigate to http://localhost:8080/ in your browser to test if the application is working correctly—"2FA app is working" should be displayed:

Set Developement Mode

Enabling development mode allows the Ktor application to display more detailed debugging information in the IDE, such as call-stack. It will help with development and diagnosing issues.

Open the resources/application.conf file and add development = true:

ktor {
    development = true

    ...

Add Dependencies

Vonage Java SDK

The Kotlin language provides interoperability with Java, which allows you to call Java code from Kotlin code so that you can use Vonage Java SDK for the Kotlin/Ktor project.

Open the build.gradle file and add the following dependency:

dependencies {

    ...

    implementation 'com.vonage:client:6.1.0'
}

Serialization

You will use JSON as a data format to communicate with the clients. You will serialize Kotlin objects using Kotlin serialization.

Open the build.gradle file and add the following dependencies:

dependencies {

    ...

    implementation "io.ktor:ktor-serialization:$ktor_version"
    implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.0.1'
}

The Kotlin serialization library uses preprocessing (at compile time), so you have to add the org.jetbrains.kotlin.plugin.serialization Gradle plugin. At the time of writing this article, Ktor is using using the old way of applying Gradle plugins, so we have to replace it with the new configuration.

Open the build.gradle file and remove plugins:

apply plugin: 'kotlin'
apply plugin: 'application'

Remove the mainClassName:

mainClassName = "io.ktor.server.netty.EngineMain"

Remove the classpath:

dependencies {
    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
}

Add plugins using the new Gradle syntax, just below buildscript block:

buildscript {
    // ...
}

plugins {
    id "java"
    id "org.jetbrains.kotlin.jvm" version "$kotlin_version"
    id "org.jetbrains.kotlin.plugin.serialization" version "$kotlin_version"
}

After all the modifiations, the build.gradle file should look like this:

buildscript {
    repositories {
        jcenter()
    }

    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

plugins {
    id "java"
    id "org.jetbrains.kotlin.jvm" version "$kotlin_version"
    id "org.jetbrains.kotlin.plugin.serialization" version "$kotlin_version"
}

group 'com.example'
version '0.0.1'

sourceSets {
    main.kotlin.srcDirs = main.java.srcDirs = ['src']
    test.kotlin.srcDirs = test.java.srcDirs = ['test']
    main.resources.srcDirs = ['resources']
    test.resources.srcDirs = ['testresources']
}

repositories {
    mavenLocal()
    jcenter()
}

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
    implementation "io.ktor:ktor-server-netty:$ktor_version"
    implementation "ch.qos.logback:logback-classic:$logback_version"
    testImplementation "io.ktor:ktor-server-tests:$ktor_version"

    implementation 'com.vonage:client:6.1.0'
    implementation "io.ktor:ktor-serialization:$ktor_version"
    implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.0.1'
}

The kotlin_version and ktor_version properties are defined inside gradle.properties file.

To enable serializatin, the JSON Converter has to be enabled for the Ktor application. Open the Application.kt file and add an install block inside Application.module function:

fun Application.module(testing: Boolean = false) {

    install(ContentNegotiation) {
        json()
    }

    // ...
}

The IDE will mark all classes and extensions that have import missing with the red color. Rollover on the class or method name, wait for a window to appear, and select import... to add class import and fix the error.

Create a Vonage Application

A Vonage application will provide 2FA capabilities for the API. Create a Vonage application in the dashboard. Click the Create a new application button, enter a name, and click the Generate new application button.

Go to settings and make a note of API key and API secret.

Initialize Vonage Client

Add the client property inside Application.module function to initialize a Vonage client:

fun Application.module(testing: Boolean = false) {

    val client: VonageClient = VonageClient.builder()
        .apiKey("API_KEY")
        .apiSecret("API_SECRET")
        .build()

    install(ContentNegotiation) {
        json()
    }

    // ...
}

Replace API_KEY and API_SECRET using the values from the dashboard.

NOTE: in production API_KEY and API_SECRET shuld be retrieved from environment variables.

API Functionality

You will build two API endpoints:

verifyNumber - the client will first hit this endpoint to start the verification process by processing the phone number to be verified.
verifyCode - after receiving code (via SMS or voice call), the client will send the code, and the application will perform a 2FA check to determine if the client is verified.

Create verifyNumber API Endpoint

Define a new route handler, get("/verifyNumber"), inside the routing block of the Application.module function:

fun Application.module(testing: Boolean = false) {

    // ...

    routing {
        get("/") {
            call.respondText("2FA app is working", ContentType.Text.Html)
        }
        get("/verifyNumber") {
            // ...
        }
    }
}

The code within the get("/verifyNumber") route handler will be executed when the client makes a call to the http://localhost:8080/verifyNumber URL.

The verifyNumber endpoint will contain the following logic:

retrieve phoneNumber parameter from the query string (http://localhost:8080/verifyNumber?phoneNumber=1234)
start 2FA verification using the Vonage SDK
return requestId as a JSON (in a production application, you would typically store ID on the server-side)

Add the following logic to the get("/verifyNumber") route handler:

get("/verifyNumber") {
    val phoneNumber = call.parameters["phoneNumber"]
    require(!phoneNumber.isNullOrBlank()) { "phoneNumber is missing" }

    val ongoingVerify = client.verifyClient.verify(phoneNumber, "VONAGE")

    val response = VerifyNumberResponse(ongoingVerify.requestId)
    call.respond(response)
}

Define a VerifyNumberResponse class that will be serialized to JSON and returned to the API client. Add the following code at the end of Application.kt file:

@Serializable
data class VerifyNumberResponse(val requestId: String)

Kotlin allows defining multiple top-level members (classes, properties, etc.) within a single file.

Due to a bug in the Kotlin plugin, you need to add the import statement for Serializable annotation manually. Add the following code at the top of the file, just below the last import statement:

import kotlinx.serialization.Serializable

Instead of using Vonage build-in verification, you could generate the code by yourself and send an SMS using Vonage Java SDK. However, the Vonage verification mechanism provides an easy way to use more complex workflows, e.g.: default workflow will make a phone call and read the code to the user if the client did not provide SMS code within a specific period.

Create verifyCode API Endpoint

Define a new route handler, get("/verifyCode"), inside the routing block of the Application.module function:

fun Application.module(testing: Boolean = false) {

    // ...

    routing {
        // ...
        get("/verifyCode") {
            // ...
        }
    }
}

The verifyCode endpoint will contain the following logic:

retrieve code parameter from the query string (code will be delivered to the user after hitting the verifyNumber endpoint)
retrieve a verification requestId parameter from the query string (value retrieved from verifyNumber endpoint)
verify code using Vonage SDK
return verification status to the client

Add the following logic to the get("/verifyCode") route handler:

get("/verifyCode") {
    val code = call.parameters["code"]
    val requestId = call.parameters["requestId"]

    val checkResponse = client.verifyClient.check(requestId, code)
    println(checkResponse.status)

    val status = if(checkResponse.status == VerifyStatus.OK) {
        "OK"
    } else {
        "ERROR: ${checkResponse.status}"
    }

    val response = VerifyCodeResponse(status)
    call.respond(response)
}

Define a VerifyCodeResponse class that will be serialized to JSON and returned to the API client. Add the following code at the end of Application.kt file:

@Serializable
data class VerifyCodeResponse(val status: String)

After all the modifications, Application.kt file should look like this:

package com.example

import com.vonage.client.VonageClient
import com.vonage.client.verify.VerifyStatus
import io.ktor.application.*
import io.ktor.features.*
import io.ktor.http.*
import io.ktor.response.*
import io.ktor.routing.*
import io.ktor.serialization.*
import kotlinx.serialization.Serializable

fun main(args: Array<String>): Unit = io.ktor.server.netty.EngineMain.main(args)

@Suppress("unused") // Referenced in application.conf
@kotlin.jvm.JvmOverloads
fun Application.module(testing: Boolean = false) {

    val client: VonageClient = VonageClient.builder()
        .apiKey("API_KEY")
        .apiSecret("API_KEY")
        .build()

    install(ContentNegotiation) {
        json()
    }

    routing {
        get("/") {
            call.respondText("2FA app is working", ContentType.Text.Html)
        }
        get("/verifyNumber") {
            val phoneNumber = call.parameters["phoneNumber"]
            require(!phoneNumber.isNullOrBlank()) { "phoneNumber is missing" }

            val ongoingVerify = client.verifyClient.verify(phoneNumber, "VONAGE")
            val response = VerifyNumberResponse(ongoingVerify.requestId)
            call.respond(response)
        }
        get("/verifyCode") {
            val code = call.parameters["code"]
            val requestId = call.parameters["requestId"]

            val checkResponse = client.verifyClient.check(requestId, code)
            println(checkResponse.status)

            val status = if(checkResponse.status == VerifyStatus.OK) {
                "OK"
            } else {
                "ERROR: ${checkResponse.status}"
            }

            val response = VerifyCodeResponse(status)
            call.respond(response)
        }
    }
}

@Serializable
data class VerifyNumberResponse(val requestId: String)

@Serializable
data class VerifyCodeResponse(val status: String)

Use the API

The API implementation is complete, so let's test it.

Any client can use the API, including desktop and mobile clients, but you will perform simple testing by using a web browser.

Launch the Ktor application.

Replace PHONE_NUMBER with an actual phone number and open the following URL in the browser:

http://localhost:8080/verifyNumber?phoneNumber=PHONE_NUMBER

Vonage phone numbers are in E.164 format, '+' and '-' are not valid. Make sure you specify your country code when entering your number, for example, US: 14155550100 and UK: 447700900001

As a trial user, you will only be able to send SMS and make voice calls to the number you registered with and up to 4 other test numbers of your choice (you can top up your Vonage account to remove this restriction).

You should receive an SMS with a code and see a similar response:

{"requestId":"9ac76db7971b4ea4a49f2e061432c6fe"}

Compose a second request. Replace REQUEST_ID with the value returned from server (in the above example, it's 9ac76db7971b4ea4a49f2e061432c6fe) and replace CODE with the received verification code:

http://localhost:8080/verifyCode?requestId=REQUEST_ID&code=CODE

If the client phone number is verified, you should see the following response:

{"status":"OK"}

You are using a default Vonage verification workflow (https://developer.nexmo.com/verify/guides/workflows-and-events), so if you do not enter the code within 125 seconds, you will receive the voice call reading the code.

The Right Way of Using Gradle Dynamic Dependencies

Igor Wojda — Wed, 04 Nov 2020 15:14:31 +0000

Gradle is quite a popular and flexible build system. Among other things, it allows us to deal with dependency management. We can define all dependencies (external frameworks and libraries) that our application will use, e.g.

dependencies {
    implementation 'com.nexmo.android:client-sdk:2.7.0'
}

The above code will download a fixed 2.7.0 version of the Nexmo Client SDK. Before moving to dynamic dependencies, let’s take a quick look at semantic versioning.

Semantic Versioning

Most libraries nowadays follow Semantic versioning specification, also known as semver. It promotes major.minor.patch (2.7.0) format for dependency versioning. Each number is incremented when particular criteria are met:

– major part is incremented when backward-incompatible API changes are made. Pulling a new version will most likely break your build, e.g. method signature change or method removal.

– minor part is incremented when functionality is added in a backward-compatible manner or improvements are introduced within the private code, e.g. new method is added to the API.

– patch part is incremented when backward-compatible bug fixes are made. This is the most common type of release, and usually, we want to have the newest path version due to various bug fixes.

Dynamic Dependencies

Gradle also allows you to define a dynamic version of the dependency (library) using the + character in the dependency definition.

dependencies {
    implementation 'com.nexmo.android:client-sdk:2.7.+'
}

In the above example, Gradle will download client-sdk with the newest path version, eg. 2.7.1, 2.7.2, 2.7.3, and so on. Gradle allows us to define dynamic versions retrieval in multiple ways. Let’s look at a few examples:

– implementation ‘com.nexmo.android:client-sdk:2.7.+’ – download new library version when path version has changed

– implementation ‘com.nexmo.android:client-sdk:2.+’ – download new library version when minor or path versions has changed

– implementation ‘com.nexmo.android:client-sdk:+’ – always download newest version of the library

This mechanism is a good way to ensure that we are using a library version with most up to date with all the performance improvements, patches, and bug fixes. However, in practice, the usage of dynamic dependencies may lead to multiple problems. Let’s consider a few real-life scenarios where the uses of dynamic dependencies have serious downsides.

Problematic Scenario 1

Let’s start with the simplest scenario. Our application is using dynamic dependency for a 3rd party library. We discovered a bug in our application, and we know that it was working fine 1 month ago. We want to use one or more builds from the past to determine when bugs were introduced in our code base. We checked out code from the repository from one month ago, the moment in time when the application was working fine, and then we built the app, but the application still does not work as expected – the problem is still there. What happened? It turns out that the bug was in the external library. Our src code was from 30 days ago, but the Gradle dynamic dependency mechanism downloaded the newest version of dependency (with the bug) that was not present 1 month ago when the initial build was created (the one without a bug).

Lesson 1: It is hard to make the same build of the application when dynamic dependencies are used because the build depends on external library versions that most likely change over time.

Problematic Scenario 2

We are the creators of the library. We asked our users of our library explicitly to use this dynamic dependency:

dependencies {
    implementation 'com.nexmo.android:client-sdk:2.7.+’
}

They have added this dependency to their project by merely copying the above code. At some point in time, we released a new version of the library that introduces a bug. Now users are reporting that “a few days ago, their application stopped working as expected.” Developers used a dynamic dependency version, unaware that the library’s new version causes the bug. Instead of quickly fixing the problem by reverting the library version, they send bug reports and wait for the fix.

Lesson 2: Do not advise your library users to use dynamic dependency versions because when you break the library, they will most likely not know the exact cause of the problem.

Solutions

Modern IDEs like IntelliJ IDEA will warn us about dynamic dependency usage by usage:

To avoid unpredictability, we can specify dependency versions explicitly and update them manually when a need occurs. This will allow you to have full control over version updates and take a closer look at the dependency changelog and review the changes. IDE will also display a warning about outdated dependency and provides intention to change the version it:

This strategy works fine for small projects, but manual updates can be time-consuming when your project contains a large number of dependencies. We can use gradle-versions-plugin to determine how many dependencies need to be updated:

./gradlew dependencyUpdates.

The above command will produce a report listing all the outdated dependencies.

We can also take it one step further to balance deterministic builds and dynamic dependency versioning. Gradle Dependency Lock Plugin allows us to use dynamic dependency syntax in the Gradle build config and at the same time lock these dependencies to specific versions (overrides Gradle dynamic dependency behavior). This gives us full control of when dependencies should be updated. To update dependencies, we have to run a single command:

./gradlew --refresh-dependencies generateLock saveLock

The above command will generate a dependencies.lock file containing versions of dependencies. This file should be included in version control to ensure every developer in the team uses the same versions of dependencies. As a team, you can decide when to update dependencies, e.g. beginning of every development cycle.

Summary

Using Gradle dynamic dependencies may lead to new bugs in the application. If you are lucky, these bugs may be caught by tests, but this is not guaranteed. On top of that, the cause of the bug is often not obvious, leading to even more confusion. When building our application, we should decrease the number of moving parts. Ideally, builds should be deterministic and building the same source code should produce exactly the same application. If you plan to use the dynamic dependencies version, you should also use Gradle Dependency Lock Plugin; otherwise, you should specify your dependency versions explicitly.

The post The Right Way of Using Gradle Dynamic Dependencies appeared first on Vonage Developer Blog.

Igor Wojda Joins the Vonage Developer Relations Team

Igor Wojda — Wed, 11 Mar 2020 17:00:36 +0000

My name is Igor and I am very excited to join Vonage as Android Developer Advocate.

As a kid, I was always fascinated by computers. The mystery and infinite capacities always spiked my levels of curiosity. Now, many years later I am a Software Engineer with over 12 years of experience.

I have been involved in many IT projects, building various applications across industries, organizations types, team sizes, methodologies, and technologies. Every project is unique having its own set of constraints, but one common characteristic is a neverending stream of emerging challenges—this is what I love about IT.

At some point, I decided to share my knowledge and experience with the community, so I became a technical reviewer of the second Kotlin book ever published – Kotlin In Action and a co-author of Android Development with Kotlin.

On top of this, I am inspiring developers by writing articles, speaking at conferences and contributing to open-source projects.

Nowadays I am specializing in mobile development. Android is my platform and Kotlin is my language of choice. However, my personal favorite topic is the application architecture. With so many moving parts designing high quality modular, scalable, testable architecture that will support an application’s growth can be quite challenging.

At Vonage, I will be working closely with external developers using our SDK. My goal is to improve the developer experience by writing high-quality documentation, building sample projects, writing tutorials and polishing the Client SDK API.

I want to make the SDK not only more intuitive, easier to use but also more flexible and convenient to integrate into modern Android applications.

Follow me on twitter to stay in touch @igorwojda.

The post Igor Wojda Joins the Vonage Developer Relations Team appeared first on Vonage Developer Blog.

DEV Community: Igor Wojda

Refactoring Multi-Module Kotlin Project With Konsist

Refactoring Multi-Module Kotlin Project With Konsist

Base Project

Guard 1: Unify The UseCase Method Names

Guard 2: Use Case Has Only One Public Method

Guard 3: Every Use Case Resides in “domain.usecase” package

Summary

Links

Introducing Konsist: A Cutting-Edge Kotlin Linter

Meet Jill, The Kotlin Developer

Meet Konsist

Konsist Declaration Guards

Konsist Architecture Guards

Konsist API

Konsist Project Status

Community Engagement

Summary

Introducing Konsist - cutting-edge Kotlin linter

Build A 2FA Server With Kotlin and Ktor

Prerequisites

Create A Ktor Project

First endpoint

Set Developement Mode

Add Dependencies

Vonage Java SDK

Serialization

Create a Vonage Application

Initialize Vonage Client

API Functionality

Create verifyNumber API Endpoint

Create verifyCode API Endpoint

Use the API

Further Reading

The Right Way of Using Gradle Dynamic Dependencies

Semantic Versioning

Dynamic Dependencies

Problematic Scenario 1

Problematic Scenario 2

Solutions

Summary

Igor Wojda Joins the Vonage Developer Relations Team