Tsoobame

software, japanese, kyudo and more

User Registration - Layered Architecture (OOP)

This post can be read independently but is part of a series of posts about Ports and Adapters and Functional programming. If you want to read it, you can access through this link.


User Registration

We need to implement a service that will manage the user registration for a web application. The system needs to allow users to get registered and to confirm their registration and email address through a link that will be sent in an automatic email. 

The emails are sent by a different service that contains this functionality. The User Service will need to publish events to the event bus in order to communicate with the rest of the system and will need to store the information about the user in its own database.

Note: we are going to simulate the database and the messaging system because it goes beyond the goal of this post.


Architecture

We are going to follow a simple Layered Architecture, from HTTP API to Database / Event Bus:


We are going to focus on the elements within the dotted box:

  • HTTP Facade: offers the HTTP interface for the clients to connect and access the functionality of the service.
  • Service: contains the business of the service. Executes the behaviour defined by the domain rules.
  • Repository: offers the methods required for storing and retrieving the data from the database. 
  • Events adapter: offers the methods required for publish and subscribe to events in the event bus. In this case, the user service will only publish them.

Coding

You can find the code related to this post in GitHub

I am going to start the development from top to bottom since it is easier to reason about the layers in Layered Architecture.

HTTP Facade

The HTTP Facade will contain the entry point to the User Service. As we said we will need two different methods: registerUser and confirmUser.

Note: since I want to discuss about the concepts I am not using REST or OData or GraphQL APIs, since they require a whole (big) post on their own.

Our initial version of the Http Facade will be as simple as:

const express = require('express');
const app = express();
app.post('registerUser', (req, res) => {
});
app.post('confirmUser', (req, res) => {
});
app.listen(3000, () => {
    console.log('Listening to port 3000');
});

As you can see with express it is very easy to implement the facade. We just need to choose the endpoints of the api (both path and verbs).

Of course now the HTTP Facade is doing nothing, but we still do not have a service to call. We are going to include the User Service to see how the final picture of this layer will look like. 

As shown in the diagram, the User Service will have some dependencies on the repository and the events adapter. We are going to inject those dependencies in the class constructor, so we can abstract the service from the implementation of these dependencies so we can test it better by mocking them in the tests. ç

We could have a factory taking care of injecting the dependencies to the service, or a bootstrapper configuring some of the dependencies map through a IOC library (like infusejs for example) but for simplicity we are going to initialise and inject the dependencies in the HttpFacade.

The registerUser method would look like:

app.post('registerUser'async (req, res) => {
    const userService = new UserService(new UserRepository(), new EventAdapter());
    const userData = req.body;  // Using bordy-parser
    const result = await userService.registerUser(userData);

    res.send(result);
});

The code consists in simply :

  1. Initialise a new UserService passing its dependencies in the constructor.
  2. Retrieve the data sent to the api endpoint.
  3. Call the right method in the UserService.
  4. Return the result to the caller (we are ignoring potential errors to make the code simpler).
The confirmUser endpoint will do something similar, just calling a different method in the service. The UserService initialisation will be the same, and it could be that UserRepository or EventAdapter had dependencies, so it would be nice to have a factory or use an IOC library as mentioned before.

We are going to create the User Service next.

User Service

The user service will contain all the domain or business logic. It needs to apply the rules, validations, etc to ensure that the actions we are trying to perform are correct before persisting the result or new state in the chosen storage system and notifying the rest of the system about this operation.
module.exports = class UserService {
    constructor(repository, eventAdapter) {
        this.repository = repository;
        this.eventAdapter = eventAdapter;
    }

    async registerUser(userData) {
        if(!userData) {
            throw new Error('The user cannot be null.');
        }

        validateUserName(userData.userName);
        validatePassword(userData.password);

        const user = {
            userName: userData.userName,
            password: userData.password,
            state: 'PENDING'
        };

        const newUser = await this.repository.save(user);
        this.eventAdapter.publish('user.registered', newUser);
        return newUser;
    }

    async confirmUser(userData) {
        if(!userData) {
            throw new Error('The user cannot be null.');
        }

        let user = await this.repository.getByNameAndPassword(userData.userName, userData.password);
        user.state = 'CONFIRMED';

        await this.repository.save(user);
        this.eventAdapter.publish('user.confirmed', user);
        return user;
    }
}

function validatePassword(password) {
    // Validate length, strength, etc
}

function validateUserName(userName) {
    // validate length, format, etc.
}

The code is simple but here is what this class is doing:
constructor
  • Stores the dependencies so they can be used whenever needed.
registerUser:
  • Validates that the user data is correct.
  • Sets some fields based on the domain rules: a user starts as PENDING until the email is confirmed.
  • Persists the information in the database.
  • If everything above is correct it will publish a new event to notify the rest of the system about the new user.
confirmUser: (see registerUser)

Although is beyond this topic, I wanted to write a short comment about events:
In this example we are using events to communicate through different services. In this specific case, we might need to sent an Email to the user that just registered so he can confirm its email address. Since one application can send emails due to different reasons or from different actions that might be implemented in different services, it makes sense to have a separated service for the Emails. It is very important to understand that an event represent something that happened. I should take special care on not sending the event before knowing that the action was performed and persisted, otherwise we could provoke a lot of inconsistencies in the system (for example sending an email to the user that was not persisted in the DB or even that had some error in a field and the validation did not success). 

In our example EventAdapter and Repository are doing nothing, so we will not show the code in this post. But again you can download the full code from GitHub

Unit Tests

We are going to test the service to ensure that the functionality does what we expect and follows the requirements. We are going to install chai and mocha for its execution ( npm install chai mocha --dev ).

In order to test the UserService in isolation we will need to mock (create predictable versions) of the dependencies. We can use tools like sinon for this task, but in this case, I am going to create very basic mocks.

We are going to test the registerUser method only as an example.

In the code bellow you will see that we need chai and chai-as-promised to create our tests.

The first test will just ensure that a registering a user sending null will throw an exception. We need to use the "rejectedWith" method because the userService returns Promises when running the registerUser method. 

const chai = require('chai');
const UserService = require('./user-service');
const chaiAsPromised = require('chai-as-promised')

chai.use(chaiAsPromised);
const expect = chai.expect;


describe('user-service', () => {
    describe('registerUser', () => {
        it('If user data is null, registerUser should throw an exception', () => {
            const userService = new UserService();
            expect(userService.registerUser(null)).to.be.rejectedWith(Error);
        });

        it('If user data is null, registerUser should throw an exception', () => {
            const userService = new UserService();
            expect(userService.registerUser(null)).to.be.rejectedWith(Error);
        });
    })
})

A more interesting test would be a happy case. We will assume that the user is correct and the repository and the eventAdapter work properly. For that we will need to create mocks of the dependencies used by UserService.

Creating two methods we will use for testing the happy case:

const doNothing = () => {};
const returnArgument = (arg) => arg;

Testing that saving the user data returns the same data plus the new state. We do not check about the new Id generated since it is responsibility of the repository to create it.

it('If user data is correct and the user can be saved and the event published the service will return the new user'async () => {
    const userData = {
        userName: 'user-name',
        password: 'some-password'
    }
            
    const userService = new UserService({ save: returnArgument }, { publish: doNothing });
    const newUser = await userService.registerUser(userData);

    expect(newUser.userName).to.equal(userData.userName);
    expect(newUser.password).to.equal(userData.password);
    expect(newUser.state).to.equal('PENDING');
 });


We can create more tests by thinking on what could occur when using the registerUser method and deciding what should be the right reaction on each case. For example, what if the user could not be saved? what if the user could be saved but the event could not be published? etc.

Final questions

We did not add any log to our service. If we wanted to use a logger module, should we inject it through the constructor? Should we just import it form the node_modules?
What about other dependencies like lodash or uuid, etc. Should we inject all the utility libraries through the constructor? Should we allow modules to import other modules directly?

Sometimes deciding what should be injected and what should be just imported is not easy. 
One possible criteria is injecting all modules that produce non deterministic behaviours and just import all the ones that produce deterministic responses. It would mean that all modules executing I/O operations, generating uuid or random values, etc. should be injected.

The logger for example, is we assume that it writes only to console.log, we could assume it as deterministic (almost) but if it can write to files or send events, then it would be clearly non deterministic and therefore it should be injected to all modules using it.

Ports and adapters architecture and functional programming (part 1)

Last week I was seeing a video about functional architecture and how it could help projects to be more maintainable:

Functional architecture - The pits of success - Mark Seemann


Although I did not agree on some of the statements and some of the examples on C#, I got curious (even more) about the topic. 

In my project we are starting to use RabbitMQ as message broker for our business events, both for services communication and for analytics.  For example, we want to make our logger to publish events in case of a message that is above some configured threshold (error by default).

When explaining these ideas to my team, one of my team members was worried about it, since the logger that was already performing side effects (but more or less safe) would start emitting events. He proposed to detach the functionality from the side effects. So again, functional programming was knocking to my door. 

Functional Programming

I started reading about functional programming and found some posts very interesting about applying functional programming in javascript. I am not an expert on functional programming but there are some basic concepts that are key to make software that is testable and less prone to errors. Before learning more about the complex concepts (monads, functors, etc) I want to understand the basic ones and try to apply them to a vanilla javascript project. 

Side Effects

A side effect is any change or any action performed out of the boundaries of a given function. By definition modifying a global variable, writing to the database, sending an event through an event bus, writing to a log file, changing the DOM, etc. is a side effect. Any of those things could produce a failure or an unexpected change and therefore any function performing any of those actions becomes non-deterministic and more difficult to test (more on this to come). 


Pure vs Impure functions

A pure function is a deterministic function that will always return the same value when getting the same input and that does not perform any side effects. So basically the pure function gets some values, performs some calculations and return a result: always the same one given the same parameters.

As you might suppose then, an impure function is any function that has performs side effects, so it is not deterministic. Its output, success or failure, etc would depend on external factors.

As a result, testing a pure function is easy and testing an impure function not so much; depending on the number or nature of the side effects they can become very complex to test.



Ports and adapters architecture

Ports and adapters or Hexagonal architecture tries so separate the core of the application from all the external elements it needs to connect to. An application will need to access to the Database, send emails, send events through a message broker, receive http requests, write log messages to files, etc.



It proposes four different types of elements:

- Application: the core, the functionality that models the domain behaviours and data. 

- Ports: entry (or exit) points to the application. The public interface to the application. What methods it provides for inputting information and what methods it needs to send resulting data to external services.

- Adapters: they are the elements responsible for getting or sending data to specific external elements. For example a module to access to the Database, a module to send events to an event bus, a logger to write the messages to disk, etc.

 - External elements: these are elements that are not part of out system but we need to interact with them to be able to perform the complete functionality. These are UI, Database, message brokers, etc.


Combining everything

Adding all together, it is easy to map the concepts from functional programming and from ports and adapters to have an idea on how nicely they fit and how natural it should be to create a functional application with ports and adapters architecture.

- Application shall be composed by only pure functions. It will provide the predictability and testability we need for the most important part of the system and we can reason about it more easily due to its deterministic nature.

- Adapters shall contain all the functions that will access the external systems, i.e. that will perform side effects. So the impure (non-deterministic) functions will be enclosed in the boundaries of the application.


Conclusion

The idea of joining functional programming with ports and adapters seems very reasonable and logic, but still without a clear/real example the concepts cannot be tested.

In my next posts I will create an application in three different flavours so we can materialise these ideas and find out if they really make sense. The application will be a service based on nodejs performing accesses to a database, writing log messages and sending business events to an event broker (all the external systems will be simulated). The flavours will be:

- Layered architecture: HTTP layer will call service layer that will call the repository and the event bus.

- Ports and adapters - Object Oriented: the core application will contain the domain logic and will get the adapters by dependency injections.

- Ports and adapters - Functional: the core application will contain only pure functions, the side effects will be performed by the adapters.

All will contain Unit Tests since I can foresee that in this regard we will see a lot of differences.


Do you  have any experience on working with functional programming? What are your thoughts about it?


How to become a good developer

Some days ago, someone in my company asked me a fair-but-not-easy-to-answer question: 

How do you think I can become a good software developer ?

Without much time to prepare to this question my first answer was about trying to build a real project. You can read and follow a lot of tutorials (of course they are important) but you will not really learn until you put them into practise in a real project. 

If your company does not use a given technology you want to learn, just start your own project using it. It does not need to be successful in terms of business, but needs to be real. 

After this quick answer, I started to think on when I started to feel like I was becoming a mature software developer. This is the outcome of my thoughts:


Understand that the code you write is for others to be read

 This is something very basic, but sometimes we forget. The code we are writing today, will be read and maintained by others or by ourselves in the future. Also the effort a company (or a group of developers) takes for developing an application is very small compared to the effort they will invest in maintaining it (solving issues, adding features, improving some areas, etc.).

Some basic rules for accomplishing this are:

  • Do not relay on comments to explain the code. Code needs to be self explanatory, so by reading the code everyone needs to understand WHAT is being done. Comments should be used only when the WHY of what we are doing is not clear, or to explain lines of code that might look like potential bugs to others.
  • We all like to write perfect algorithms and super-optimal code, but it usually makes code difficult to read. Do not write too much magic in your code, and if you need it, enclose it in methods with a clear naming.
  • Perform code reviews frequently (during every push for example). The reviewer should understand the code without many explanations from the developer that wrote the code, so make sure that variables and method names are clear.
  • Use an external tool for validating the code style. There are plenty of them, and they ensure that the code is uniform throughout the project.

Decide clear naming for methods and classes

This is related to the previous aspect, but it has special importance. If you think of how to name a method or a class you are deciding its responsibility and its boundaries, so it will help to design a modular system. 

The name of the class, method etc. need to make clear to everyone what it holds. For this to be true, we need to ensure that the contents of the class or the behaviour of the method, its inputs and its outputs match the name you choose. If they not, or if they change overtime, no not be afraid of changing the name to be accurate.

Examples of bad names include the typical *Helper. This name states who is helping to, but it does not helps to understand what this class holds. For example StringHelper can hold validation methods, formatting methods, constants, localisation, etc.

Learn about Unit Testing and keep it in mind when developing

When unit testing classes and methods, you need to think about the boundaries of those classes and the responsibilities and of method. 

This includes what output needs to deliver to the caller, how to react to a given input and will arise lots of “what if” questions that will make the code very robust.

It will also help you thinking on the responsibilities this class needs to have and what responsibilities should be delegated to a different one, creating the dependency map in an evolutionary way and making the dependency injection something natural.

Conclusions

As you can see my main concerns about good developers are not about technical skills but about clarity in the code and structured projects.

If all this is accomplished a team can maintain the code easily, the can look for better algorithms for complex calculations areas in the code, or look for third party libraries that can fulfil some of the dependencies we might encounter. 

Of course we can become experts on some technologies or some tactics, or infrastructures, but first we need to change or mindset and work for others. Not only for our customers, but also for other developers (providing easy-to-read code) and projects in our company (offering ways of reusing our code through libraries) or even 3rd party companies (by offering APIs).


What would you recommend so that junior developers can become good software engineers? 



Self-Hosted OWIN - Hello World!

We are going to create a new self-hosted website using owin.

0) Requirements;

  • Visual Studio 201x (I am using the VS 2015) in "Run as Administrator" mode (required to open ports).
  • Internet connection (assumed that you have it since you are reading this post).

1) Create a new Console application:



2) Install the Owin packages:

Open the Package Manager Console by clicking the Tools menu and going to Tools/Nuget Package Manager/Package Manager Console

Execute the following command:
Install-Package Microsoft.Owin.SelfHost

It will install the Owin libraries to reference them in your project.

3) Configure the application to host the web:

Add the following content to the Program.cs class:
On top  of usings:
using Microsoft.Owin;
using Microsoft.Owin.Hosting;

Above the namespace declaration:
[assembly: OwinStartup(typeof(Owin.HelloWorld.Startup))]

Add the Startup class :
    public class Startup
    {
        public void Configuration(IAppBuilder app)
        {
            app.Run(context =>
            {
                context.Response.ContentType = "text/plain";
                return context.Response.WriteAsync("Hello, world.");
            });
        }
    }

Add the content to the body of the Main method:
        static void Main(string[] args)
        {
            using (WebApp.Start("http://localhost:9000"))
            {
                Console.WriteLine("Press [enter] to quit...");
                Console.ReadLine();
            }
        }

4) Check it!

Press F5 to execute the Console Application in Debug mode.

5) Further information: