Forem: Valerii Udodov

Git Hygiene

Valerii Udodov — Tue, 02 May 2023 00:00:40 +0000

Not by coincidence Git has become a default version control system for many of us. Git has proven itself to be predictable and reliable. Especially when it comes to conflict management, history traversal, and other daily developer routines.

I have collected some recommendations that will enhance your day-to-day experience of working with Git. And hopefully, reveal some hidden features that have been laying around all this time.

This article is not an ultimate Git guide by any means. Rather it is a set of common sense practices for using Git effectively.

Branching

Strategy

There are ultimately two main branching strategies feature branches and trunk-based development. Everything else is just a variation of one or another. The biggest distinguishable difference between them is a scope of change that gets merged into the trunk branch (aka master, main, core, mainline).

Feature Branching is a poor man's modular architecture, instead of building systems with the ability to easily swap in and out features at runtime/deploytime they couple themselves to the source control providing this mechanism through manual merging.
— Dan Bodart

Use trunk-based development when possible. I won’t argue about the advantages of CI/CD, at least not in this article. I’ll just say that as the name suggest you can’t have CI/CD without Continuous Integration (CI). And by definition of the CI, you can’t have it without trunk-based development. Hence you can’t have CI/CD without trunk-based development.

ℹ️ Trunk-based development is a version control management practice where developers merge small, frequent updates to a core “trunk” or main branch…
— Atlassian Trunk-based development definition

ℹ️ Continuous integration is a DevOps software development practice where developers regularly merge their code changes into a central repository, after which automated builds and tests are run. Continuous integration most often refers to the build or integration stage of the software release process…
— AWS CI definition

The most reasonable alternative to trunk-based development is Gitflow. Given all the modern tooling for automation of testing, deployment, and releases Gitflow happens to be useful, but rarely. Deployment Hell that will unavoidably follow using Gitflow will likely cross any benefit you may think of.

Trunk-based development

The diagram above was inspired by LeRoy's illustration

Unfortunately trunk-based development is not always available right away. As the name suggests it is a process. Development process. And it has certain entrance criteria.

It should be possible to develop in small batches. It may be not only the developer’s prerogative as the work scope depends on planning. If the work is sliced in small chunks during the team planning then developing in small batches is a no brainer
The code review process should be balanced.
- Avoid overly heavy code-review process. Otherwise, developers will attempt to squeeze in as much work as possible to minimise the number of code reviews they have to go through.
- Somewhat opposed to the previous point, don’t make it a box-ticking exercise
- Code review is work and has to be recognised as such. It should be assigned and executed consciously.
- Code review should be a priority. Active branch lifetime should be minimised. Hence merged asap. So if the code is ready it should be reviewed asap.
The trunk branch should always stay healthy. Trunk branch health is an integral aspect of team performance. Thus there should be no way to break trunk branch.
Reviews, automated tests, and builds should be exhaustive and efficient.

Naming

The most common use case for branch names is when we are looking for a specific branch to checkout. Consequently, the more discoverable branch is, the better.

Usually, we know either the ticket number or the gist of work that has been (or will be) done there. However, we rarely know the exact name. It is often a good idea to incorporate a ticket number together with a distilled summary of the work. E.g. 123654-form-buttons-styling-uplift or fixing-query-parameters-encoding-bug-344400

Clean up

Another pretty obvious one, but often overseen. Once the branch is no longer needed, it must be removed. The lower the number of obsolete branches, the better discoverability of active branches. Nowadays it is very easily automated task

Commits

Message

I like to think about a branch as a story that the developer tells about the work that has been done. Where the branch name is the name of the story. And every commit message is a sentence that builds the story. The frequency of commits and the content of commit messages should make sense in the context of the story you are trying to tell and should somewhat follow one another. Writing a commit message should be an intentional process, not a side-effect of using Git.

📌 Commit process must be seamless. Try to eliminate all possible obstacles.
Make sure you can commit from your IDE, and memorise the shortcut. Remove all unnecessary commit hooks, especially long-running ones.
Commit should not feel like a burden, it should feel like saving a file.

Size

You should commit often, therefore the size of each commit must be reasonably small. Base your commits around logical units of change. As long as you do that, the commit message will be accurate and obvious. Make sure you don’t get carried away as commit messages must stay concise, remember it is just a sentence in the story, not the story on its own.

Commit History

We have slightly touched base on the commit history before. Depending on the scope and the context we will be perceiving and using commit history differently.

ℹ️ To avoid any confusion I will call main branch that all the work is based on trunk branch. And any branch that is based from the trunk branch but not yet merged back in: Work in Progress branch or WIP branch.

In the context of the WIP branch (e.g. if you are reviewing someone's work) we are interested in work that has been done in the scope of a given ticket/task/story, hence the more details provided the better.

However, when we are looking at the trunk branch we are looking at the history in the scope of the project as a whole. And hardly there will be much value in a very granular view.

WIP Branch History

Generally ambiguous commit history on this level is a side-effect of poorly planned work. You must know at least in broad strokes how you are planning to tackle the task. As long as the work is reasonably planned using commits to craft a well-written story will be a natural and effortless act.

Take a look at 12332-uplifting-checkout-form branch history

12332-uplifting-checkout-form
- introduced a theme provider
- updated buttons to use the theme provider
- updated text fields to use theme provider
- removed redundant info banner
- fixed confirmation text typo
- addressed review comments

It tells a story, isn’t it? By looking at the branch and commit messages you can see what has happened, if you require more details you can get down to the code level. Try to avoid any code specifics in the commit message, variable names, classes, etc., anything that will be anyway visible on the code level.

Ideally, you should be able to review what has been done by only looking at the commit history, although I would not recommend doing so.

Trunk Branch History

The most often use case for commit history on this level is during the process of figuring out wtf have happened with this code…

🙃 git blame ruining friendships since 2005

I think this will sound familiar to you... You are working on a ticket and you stumble across a piece of code that you need to use/change/refactor. It works somehow but looks rather confusing and illogical. The code has been there for months or perhaps years. It has been written by someone who left the company ages ago... And yet there you are one on one with it…

💡 What is worse than no documentation? Wrong documentation.
Comments explaining how code works are no better than documentation. Both get stale very fast. However, comments not only are rarely updated but often get copied all over the code base, completely losing even remote value.

The biggest advantage of having fluent and articulative history is the ability to time travel and answer the very important question of why? something has been done in a certain way. You can go to “day 1” and see how this whole space ended up where you found it. If you are lucky enough you will find ticket numbers attached to merge commits, so you’ll be able to get even more context.

💡 Mark important events (such as releases and versions) in the history with tags. You can use annotated tags to store some extra metadata.

Merge Strategy

In most cases, I’d suggest using Squash Merge as a trunk branch default merge strategy. Squash Merges will clean the trunk branch history from unnecessary noise that otherwise will leak from WIP branches history. Squash Merges will protect trunk branch integrity and concision. It will keep the history linear, which is much easier to read and rebase on.

When all the work has been done and changes have been reviewed. You are one click away from the merge, it is hard to find a good reason to preserve the WIP branch history anyway.

Merge Conflicts

While you are working on your WIP branch you shouldn’t be overwhelmed with conflicts. If you are, it is typically a consequence of sloppy work planning and mediocre orchestration. The WIP branch lifetime should be short.

However, if you encountered merge conflicts… Rebase. As said before linear history is much easier to read and comprehend. Hence much easier to traverse while traversing the history through the git blame

💡 Before rebasing make sure you know what has changed since you started your work or bring someone who knows. Otherwise, there’s a high chance you will end up with a broken WIP branch.

Bottom line ___

I have tried to distill recommendations and keep them as generic as possible, avoiding any specifics related to the Git VCS provider, automation tools, or company processes. Said that given any specific tool, any of these practices or recommendations can be (and should be) improved significantly.

Hence the final advice: don’t keep your process agnostic to tools, rely on them and use them to the maximum extent.

Domain-Driven Design: building the Right thing Right

Valerii Udodov — Wed, 12 Apr 2023 22:27:31 +0000

The success of any given software project can be distilled to a rather simple definition or rule: we need to build the right thing, and we need to build this thing right.

It is a very abstract and simple if not primitive definition. Nevertheless, it is the one that is hard to argue with.

Building the right thing

Building the right thing… I don’t think it is necessary to emphasise the importance of this claim. But who knows what does the right thing look like?

Domain experts. The domain expert is not a real position, it is rather a title that derives from a solid background in the industry. It might come from the direct experience, gained by actually working in the field (e.g. doctors, pilots, accountants). Or indirect, gained by working with other domain experts for an extensive period (designers, developers, business analysts).

Domain experts might or even will have unrelated roles and responsibilities, but one thing they all have in common… Domain knowledge.

💡 If you are not a geologist, oceanologist, or marine biologist there’s a low chance you know what good ocean bed surface exploration software must do…

In high-complexity domains, we can discover another layer of people with the sole purpose of helping in interfacing with domain experts' experience and expectations. Unavoidably these people will become domain experts on their own, gaining a lot of indirect experience.

You can distinguish domain experts by the language they use. It might sound rather confusing at first. Overflown with terminology, rich in acronyms and double-meaning words.

💡 Domain experts will use domain language (professional slang). Be careful, it will often camouflage the true meaning and mislead you into a false perception of understanding it. Don’t hesitate to clarify any obscure detail as it might open a whole new level of meaning and understanding.

Building the thing right

Building the thing right… Speaks to itself. No one appreciates broken software…

There are always numerous ways to solve a problem, hence to build an application. It is a well-known problem among developers, the attention gets easily carried away from the end goal of the project to the end tech.

💡 The choice of technology must be driven by the architecture. And architecture must be driven and enhanced by the composition of the company and project tactical and strategic goals.

When starting a greenfield project every developer feels like a kid in a candy shop.

Balanced, constantly refined architecture that focuses on the project goals is a key to building the thing right.

💡 The architecture should be constantly revisited throughout the entire lifetime of the project. However, the early stages are especially critical.

Depending on the scale of the project, there might be a mixture of different roles and positions that will keep an eye on the architecture and tech-stack integrity and alignment. Solution architects, tech leads, CTOs, you name them. No doubt, you will find domain experts among them, usually they will have a long history with a company or in the given industry. And of course they will use distinguishable (domain) language.

Building the right thing right

Appears, most of the time we know how to build the right thing and we have domain experts who can provide all the necessary support for it. And we know how to build the thing right and we have the software engineering forces to facilitate it. So why it is so hard to build the right thing right?

I think no surprises will be here, communication is hard…

Any organization that designs a system will produce a design whose structure is a copy of the organization's communication structure.
— Melvin E. Conway

A so-called Conway’s law states that communication significantly impacts the architecture, design, and code base. In the complex domain where a lot of convoluted logic resides around every corner, even initial unintentional miscommunication can derail the project. Any misinterpretation, if not addressed in time, starts a mismatch snowball effect. It grows fast, creates confusion and frustration, and degrades code-base quality which quickly becomes unmaintainable and error-prone. Even if the original miscommunication is fixed, usually it happens too late and the project is doomed.

Communication gap

Original miscommunication often appears from both the domain expert’s bias and the developer’s unwillingness to clarify details.

Because of the domain expert's vast experience in a certain area a lot of the important details are obvious, certain aspects are given and don’t require clarification, if not mentioning. The language is overflown with opaque acronyms and words that convey an indelicate meaning. This is expected and unavoidable. The domain language is a habit that domain experts develop with years of experience. It is a framework they use for efficient communication. Medicine, mathematics, accounting, industrial design any professional area will be rich in terminology. Academical or specialised books, can’t guarantee the definition of the domain language, although they are likely to embody its essence; what you will hear from domain experts is what domain language is…

Communication in general and clarification specifically is a very laborious process that requires decent self-effort. Cognitive work reduction and mental-resource preservation are part of human nature. Unmotivated developers don’t try to clarify the terminology or suspicious words, or address ambiguity in definitions. Instead, we subconsciously try to self-explain any logical flaw or uncertainty, ignore unclear acronyms, and don’t question obscure logic or abrupt conclusions.

🙅 It is typically a red flag if the conversation with the domain expert goes one way rather than actively involving all parties. Everyone must make evident their level of domain expertise. It will signal to the domain expert how carefully the domain language must be used.

💡 Often a visual artifact, such as a diagram of a domain model becomes extremely helpful during domain expert conversation. It gives a clear visual representation and helps align everyone’s understanding. It can start simple, but it will grow and improve over time.
We’ll talk about the domain model a bit later…

Unfortunately, experienced and reliable domain experts together with talented software engineers don’t guarantee the success of the project.

Domain-Driven Design

DDD can be perceived differently from different perspectives. It is a philosophy, a framework, a set of architectural patterns, and many more things with the ultimate purpose of building the right thing right.

Domain-Driven Design is an approach to software development that centers the development on programming a domain model that has a rich understanding of the processes and rules of a domain.
-- Martin Fowler article Domain-Driven Design

Domain-Driven Design (DDD) suppose to bridge the gap between the domain, its model, and implementation. It supposes to tide over misapprehension between those who can build the right thing and those who can build the thing right by making the Domain Model a centerpiece of the communication and implementation process.

Holistic Domain Model

The Domain Model is a root element of the Domain-Driven Design, everything spins around it. However, it is often confused to be one big diagram that encapsulates everything. Although nothing is wrong with having a big diagram, we all like big diagrams; except maybe we don’t like to keep them up to date, but that is a different story I suppose.

The truth is the diagram is a vital piece of the Domain Model, but so are the ubiquitous language, the code base, and even your and your colleagues' mental model. Which ideally should all match and represent Holistic Domain Model.

Model-Driven Design discards the dichotomy of analysis model and design to search out a single model that serves both purposes. Setting aside purely technical issues, each object in the design plays a conceptual role described in the model. This requires us to be more demanding of the chosen model since it must fulfill two quite different objectives.
— Domain Driven Design: Tackling Complexity in the Heart of Software by Eric Evans

Having a Holistic Domain Model can lead to rather unexpected outcomes. With a minimum support domain experts should be able to read the code and understand it. Because variable names, classes, and abstractions are part of the Domain Model, therefore meaningful to everyone involved.

Consider this example where we are committing a backlog item to the sprint

backlogItem.setSprintId(sprintId);
backlogItem.setStatus(BacklogItemStatusType.COMMITTED);

Versus this example, where we are doing the same thing, but we match the ubiquitous language and preserve our Holistic Domain Model integrity.

backlogItem.commitTo(sprint);

Few words about the code…

Since we touched on this topic, I’d like to add a few short words about the code and architecture. I won’t go into the depth of it, as quite a few books doing it better than I would. And I might share my thoughts about it in further articles. Anyhow…

DDD is heavily relying on object-oriented concepts, it builds enriched object abstraction on top of the classical object model. DDD introduces a certain object classification, such as Entities and Value Objects. Provides isolation tools and interaction interfaces such as Aggregates and Aggregate Roots.

Unlike many modern approaches, DDD does not appreciate Anemic Model and defines it as an anti-pattern. It emphasises the importance of keeping domain objects together with domain logic. So classes know what they are and what they can do instead of being data transfer objects.

DDD recognises the complexity of every domain and hence does not attempt to fit everything in one bowl. It emphasises the importance of segregation and boundaries between different contexts and introduces a set of patterns to construct anti-corruption layers.

DDD works very well with Event Sourcing and Event-Driven Architecture in general.

Bottom Line

The idea of importance mature and well-developed domain and its model was around for a while. And intuitively recognised by almost anyone involved in the implementation process, yet somehow it fades and gets lost in the daily development routine.

The DDD is something anyone can start applying and practicing today on any project. The more sophisticated the project, the more beneficial it will be, nevertheless even lighter projects can benefit from it

I would highly recommend familiarising yourself with it, as it will guarantee a change in your approach to design and development.

References

HTTP/3. All you need to know

Valerii Udodov — Wed, 22 Jun 2022 11:39:53 +0000

HTTP/3 is a long overdue change in the way the Internet works. Surprisingly, though, it does not impact us as protocol consumers much... Moreover, the transition will be barely noticeable. Eventually, we will notice that port 443 is gone. And we won't need to type https:// anymore. We will be getting back to http://...
We'll talk more about it later.

ℹ️ Port 443 is the one that is used for secure HTTP (aka HTTPS connection).

So hmmm... What is it all about?
It is all about TCP, really. Or should I say it's retirement? TCP has been around for astonishing 😲 30+ years. It is obsolete by any, even most conservative IT standards. So it was decided to replace it with a more modern transport layer protocol- QUIC.

ℹ️ HTTP is an application layer protocol that sits on top of the transport layer protocol, like TCP.

HTTP/3 uses QUIC instead of TCP. QUIC is the main driver for the new version of HTTP. And that's pretty much everything that changes from an HTTP perspective. Semantics stays the same. Hence all we know about HTTP as consumers stay the same. It will only be riding new wheels.

Why to change it? Why now? It seems like internet is working fine, isn't it?

Speed

Connection reliability is a given, thanks to TCP. Thus, the ultimate connection measurement is its speed. And obviously, there's no way to sell a new protocol without improving it.

Three factors dramatically improve QUIC data transition speed compared to TCP

Real Streams: is actual direct data transition speed improvement;
Improved handshake: is an improvement in connection establishment speed;
Connection Migration: reduces the number of necessary re-connections, hence fewer connection establishments and data losses between sessions, hence even more speed;

Real Streams

Because in the TCP all packets are transitioned in a "line", if one packet is slow or lost, the whole "line" has to wait for the slow/lost packet to get back to its place and move on. Even though TCP has a concept of streams, those are not real streams but rather an abstraction to simulate them. Multiple files are broken down into packets, and packets are grouped in small frames, but anyway go through a single stream in "line".

QUIC implements streams, I mean real streams, so the data will flow truly simultaneously via a single connection but through multiple streams. E.g. the JS bundle file might be a stream and markup another stream.

Apart from speed gain by truly parallelizing the packet transition, there's an annoying problem that has been solved. The Head Of Line Blocking.

You know, when you are in a rush and get in the line at your grocery store. And there's this super slow person in front that just slows the whole line down. Well, that's the HoL Blocking.

When a single (slow) object prevents other/following objects from making progress

All versions of HTTP, in one way or another suffered from the Head Of Line Blocking (HoL) on different levels. In HTTP/2, it was TCP HoL blocking because of a single-stream nature.

QUIC doesn't really solve the HoL blocking problem, it rather moves it to a different place. Although it does not completely solve the problem, nevertheless this shift significantly improves the performance.

The HoL Blocking can occur at the stream level. Because stream order is still important, you can't reorder or lose packets. Hence, if there's a slow fellow in the stream, the stream can't proceed and have to wait... But in this case it won't block other streams. And once the issue with the annoying packet is solved, the stream will resume.

Handshake

Handshake is a procedure of establishing a connection between client and server. It ensures that both parties ready and know how to communicate.

TCP handshake is a necessary procedure occurring before any data can be sent over TCP. It requires a client to send a request and receive a response/acknowledgment from the server. Time spent waiting is called round trip time (RTT).

ℹ️ Nowadays, we use HTTPS most of the time. HTTPS is an HTTP over TLS. Older versions of TLS (1.2 and lower) will require an extra handshake. So in the worst-case scenario, there's another RTT on top of all other handshakes.

QUIC will require at least one handshake less. It will require exactly one handshake for a new connection and no handshake for resumed connection. Which makes QUIC 1RTT for a new connection and 0RTT for resumed.

Image is borrowed from SMB over QUIC: Without the VPN by Ned Pyle

Image (a) shows required handshakes for a new connection. As you could expect TCP with old TLS version will have 3RTT, TCP with modern TLS 2RTT, while QUIC only 1RTT.
Image (b) shows required handshakes for existing connection. Once again, TCP with old TLS will require 2RTT, TCP with modern TLS 1RTT, while QUIC 0RTT

I vacuum (completely identical circumstances): the lesser handshakes the faster connection.

Connection Migration

The way we use the Internet has significantly changed over the past decade. Nowadays, a large portion of the internet traffic is consumed while we are on the go. Walking, commuting on public transport, or driving a car.
Imagine you live within 30 mins walking distance from your work. And you decide to enjoy a walk to work today. There'll be at least 3 guaranteed network changes on your way, home wifi -> cell network (4G/5G) -> work wifi. However, in reality, during your walk (while you are connected to a cell network), you will be changing a network every 5-10 minutes, depending on the nearby cell tower range and how urban is the area you live/work in.

On every new connection, unavoidably, at least one new handshake will be happening. Any active data downloading/uploading will be lost. Your endpoints will think that connection just has been lost or terminated unexpectedly.
Have you ever experienced troubles with downloads/uploads while you were on the go? Well, there you have it.

ℹ️ All large files nowadays downloaded and uploaded in segments, so if the large file will be uploading or downloading, you won't loose the whole file, but rather a last segment.

TCP was not built, nor was it optimized for such a usage...

ℹ️ The way TCP identifies a connection is pretty straightforward. Each connection between two endpoints (client and server) is identified by 4 parameters (4-tuple). Client IP address, client port number, server IP address, and server port number. If any one of the 4-tuple changes, TCP thinks it is a new connection. And the old one will be lost, it won't be even closed properly.
Every time the network changes, the client will receive a new IP, hence the whole connection 4-tuple will be changed.

The Connection Identifier (CID) allows the QUIC server and client to identify that what they see is not a new connection, but rather an existing connection migrated from another network. Therefore no need for a handshake and the download/upload process can keep on going.

ℹ️ It is a bit more involved process. However, there's one more aspect to it. CID won't be encrypted. However, after every successful migration CID will be updated, so the connection (and your route) won't be traceable by CID.

Security

HTTP is a plain-text protocol. It simply sends a text over the wire (or radio waves). S in the HTTPS stands for Secure. By using HTTPS, we instruct a browser on a TLS protocol involvement in the communication. TLS protocol will encrypt our data using advanced mathematical algorithms. This ensures that even though the data might be intercepted by a third-party, it is useless. Nowadays, most web resources on the Internet use HTTPS.
Even though modern browsers insist on HTTPS usage, we can still avoid it.

With QUIC, it is unavoidable. Because TLS is built in the QUIC. Hence with HTTP/3, there won't be a need for https:// and port 433. Everything will be encrypted out of the box. And there's no way to turn encryption off.

There's one small thing... 🫠

How do you go about upgrading the whole Internet? All devices, all routers, everything that uses TCP? 🤔

And to give you a scale of the problem, have you ever tried to trace any random request? If not, try with something like this online tracer, and you will see how many nodes are involved in your request delivery. These are middle-boxes. My google.com trace shows 11 middle-boxes between me and the server 😮... And all of them use TCP 😳... And all of them probably don't run the latest version of Network Firmware...

When was the last time you updated your router firmware? Exactly 🙃...

And this was the exact reason why a new protocol was required. Because there's no way to update all devices in the world.

As you can tell, simply adding a new protocol wouldn't work for the same reasons as updating TCP. So what do you do?
The answer is User Datagram Protocol aka UDP. It can provide a platform for the QUIC protocol. It is broadly available and has been used as a base for many other protocols, such as DHCP, SMTP and RIP. QUIC is built on top of UDP, which makes it possible to deploy QUIC on the Internet scale.
Over 73% of browsers support HTTP/3 as I'm writing this article. It is only a matter of time before all browsers and the majority of modern app servers will switch to it.

Caveats

There are a few things worth calling out.

QUIC protocol requires more processing power. It has significantly improved since its first iterations. Nevertheless, compared to TCP, QUIC will consume more resources.

And the other thing, even though it is relatively easily deployable because it is built on top of UDP. For the same reason, initially companies will block it as it will open a backdoor of UDP Flood DDoS attacks.

Bottom Line

Hopefully, this article builds a picture of what we can expect from HTTP/3 and QUIC.

I'm keen to see how the world will adopt the new protocol and what will be the future strategy for enabling it. I reckon there are industries that might want to adopt it ASAP. Gaming, video streaming, online communication, meta to name a few.

I'm glad that TCP is getting well-deserved retirement. I'm still surprised at how long it worked on a global scale. It set the bar high.

QUIC is already here. As I mentioned, majority of modern browsers support (to a different extend) HTTP/3, hence QUIC. I'm waiting with anticipation to see if our hopes for a new internet evolution step will be justified.

Data Consistency in the Microservice Architecture

Valerii Udodov — Tue, 14 Jun 2022 09:07:47 +0000

Data Consistency is an enigma of Distributed Architecture. It is a rather poetic way to say that something is a pain in the ass.

It might not be that obvious at the first glance, but Data Consistency never exists in isolation. It is heavily bonded with Availability and Partition Tolerance. If they sound alien, don't worry. We will closely look at them and their friendship in a moment
Because of the close bond, the change in one will silently trigger a change in another, and so forth. In its turn, this change train 🚆 will replace one set of problems with another. And there you have it, change on one end, brought problems on the other.

An interdependency between Consistency, Availability and Partition Tolerance in the distributed system has been described by the CAP Theorem. Originally it was formulated by Eric A. Brewer for distributed data stores. But it is applicable for any distributed stateful architecture, hence Microservice Architecture.

I think its applicability is worth explaining.

We will star with Microservice Architecture definition. Here's a very concise definition

loosely coupled service-oriented architecture with bounded contexts

Adrian Cockcroft

If we'll elaborate on it...

A Microservice Architecture is an approach where the application is built with a set of independently deployable services. The separation of concerns (SoC) is used to set service boundaries. Hence each service has its own well-defined purpose. And is either stateless or owns its data.
Me in my previous article

It is not uncommon for a cluster of services to have an interest in the same subset of data. Because each stateful service is supposed to own its data, a cluster like this is a distributed storage for that subset of data. This means we can apply a CAP Theorem to it.

CAP Theorem

The theorem states that, though it's desirable to have Consistency, Availability, and Partition Tolerance, unfortunately, no system can achieve all three simultaneously.
In other words, we can choose at most two from given three characteristics.

Before refining this theorem for Microservices let's define C, A, and P...

Consistency

Data Consistency comes in two flavors: Strongly Consistent or Eventually Consistent.
The data is Strongly Consistent if any two arbitrary services in the cluster that share a subset of data have the same version of the data at any given moment.
The data is Eventually Consistent if any two arbitrary services in the cluster share a subset of data but don't necessarily have the same version of the data at any given moment. But they guaranteed to have the same version eventually.

This theorem implies Strong Consistency by this characteristic. In other words, if your architecture has this characteristic, the data within is strongly consistent.

Availability

Availability means that any arbitrary service is not blocked/locked at any given moment. Note, it is not an "availability" from an uptime perspective (aka High-Availability), but rather from a serving perspective. The service is available for request processing even though it might not have the latest version of the data at any given moment.

Partition Tolerance

In the context of Microservice Architecture, this characteristic is not really an optional one, it is a given one.
Partition is a break or delay in the communication between services. Having partition tolerance means you are confident in the glue between your services and the underlying infrastructure. Given modern infrastructure, cloud providers and most (all?) modern message brokers guarantee "at least once" message delivery. This is a rather given and non-negotiable for Microservice Architecture.

Refined CAP Theorem (CA Theorem)

Said that let's refine the general definition of CAP Theorem and turn it into a Microservice Architecture edition. Because Partition Tolerance is a given, we will dismiss it from the definition.

In Microservice Architecture, for any given cluster of services, we can guarantee either Strong Consistency or Availability.

Consistency vs Availability

Let's look at how we can guarantee one or another characteristic in Microservice Architecture. And at what cost.
Spoiler Alert: as we go, we will observe that for Microservice Architecture the choice is pretty much predefined.

Two-Phase Commit (2PC)

Two Phase Commit (aka Distributed Transaction) is an attempt to commit/write/update a shared piece of information for each service in the cluster in (thanks, captain obvious) two phases. This approach will require a coordinator service that will control the execution of both phases.

Phase 1: The coordinator checks each service in the cluster on readiness to perform the transaction. This phase locks each service right after service response. The lock is necessary to ensure that when we are going to carry on with the actual operation (phase 2), services will remain in the same state as we leave them in this phase. If any service is not ready, we cancel the whole transaction and unlock all services.
Phase 2: Actually perform an update operation for each service in the cluster. Once this phase is over, all services are unlocked.

Evidently, this approach guarantees Consistency over Availability (CA Theorem). All services in the cluster will maintain strongly consistent data after every 2PC transaction. However, they will be locked during the whole process, hence unavailable.

If you decide to use this approach in the Microservice Architecture, I'd strongly recommend reconsidering the boundaries of all services included in the cluster. This approach strongly couples all services in the cluster and goes against the definition of Microservice Architecture. And fits well in the definition of the Distributed Monolith.
On top of that, I don't believe any modern message broker provides 2PC as an option, hence you will have to build and maintain your own Coordinator.

Sagas

In opposition to Two-Phase Commit, Saga guarantees Availability over Consistency. Meaning that data will be eventually consistent.
It is the most common approach to enforcing data consistency in Microservice Architecture.

Saga represents a controlled sequence of independent transactions executed by each service in the cluster. If one of the services fails to execute the necessary transaction, the rollback is performed by a sequence of compensative transactions.

The saga comes in two flavors. Depending on who coordinates its execution. It can be either service choreographed or service orchestrated.

Service Choreography

Service Choreography is a model of decentralized service composition. Knowledge of Saga and how to execute it is spread among services that participate in Saga.
Each service knows which service it needs to send a message to if it successfully executes a local transaction. And it also knows how to construct (and where to send) a compensative message in case a local transaction fails or a successive service sends a compensative transaction.
We wouldn't necessarily use direct communication between services (like RPC), but rather a queue.

Service Orchestration

Service Orchestration is a model of centralized service composition. Saga is coordinated by orchestration service. The main role of the orchestrator is to deliver the message from the sender to all other Saga participants (aka message subscribers). Often a message broker is employed as an orchestrator. Both general and compensation messages are coordinated by the orchestrator.

Bottom line

I'd recommend using Service Orchestrated Sagas with a modern Message Broker as an orchestrator for implementing data consistency in the Microservice Architecture.
The message broker will decouple services in the cluster. It will reduce friction surfaces between services, and in opposition to Service Choreographed Sagas, it will remove unnecessary awareness from each service about its Saga predecessor and successor.

Monolithic Architecture

Valerii Udodov — Tue, 07 Jun 2022 10:03:51 +0000

Nowadays, Monolithic Architecture carries this exaggerated ill fame. I personally worked with a few monolithic architectures in the past. And there's something shameful in admitting that you work or have been working with a monolith. Imagine going to the interview and saying that you have deliberately built a monolith... Without supervising this claim with a context, you probably better not wait for an offer.

Surprisingly, as we'll reveal a bit later, such a bad reputation was not caused by an architecture itself, or should I say solely by it.
So why does this revolting feeling occur every time someone mentions Monolithic Architecture? And why do organizations keep building monoliths nowadays?

What is a Monolith?

I'd like to draw a bold line 🖍️ between monolithic architecture and a big ball of mud.

The Monolithic Architecture suggests that the application is a single unit, single logical executable, and single whole. Thus application is stored, developed, built, executed, and deployed as a single unit. The Monolithic Architecture is self-contained application architecture.

Monolithic Architecture itself does not suggest any specific implementation practices or patterns. Underneath it might have a good separation of concerns (SoC), follow SOLID principles or implement event-sourcing, built within functional or object-oriented paradigm, etc.

I'd like to emphasize that the Monolithic Architecture is not a bad practice or an anti-pattern. As well as the monolithic application is not necessarily a poorly designed one, and internally employs the worst available practices.

So what's the catch? 🤨

Conway's Law

Any organization that designs a system will produce a design whose structure is a copy of the organization's communication structure.
— Melvin E. Conway

An application and thus an architecture is a permanently evolving organism. It changes and adapts to an ever-changing environment. To survive it has to react to the most critical factors of the environment. Those factors usually include (but are not limited to) business needs and/or market opportunities, technical limitations and scalability requirements, financial aspects, etc. Therefore any architectural decision must be always viewed in the context of the time, phase of the product, and business targets at the time.

Most of the time Monolithic Architecture is an unavoidable first step in the solution lifetime and the first stage of the application architecture evolution. And there are a few good reasons for that. First and foremost it is the easiest and fastest way to build an MVP (minimum viable product). Whereas time is an essential factor, especially if an organization adopts Lean Design and Agile practices.

Often MVP is produced by a rather small organization or unit within the organization. Where communication between all members is efficient and effective. Given all that, this design fits well with Conway's law.

Pivotal point 📉

Of course, Monolithic Architecture has its own limitations (we will look closely on them in a few moments).
And the first time when business bumps into them, it is rather a good sign. It signifies that the business took advantage of the market opportunity and successfully passed early adopters' validation. This is a pivotal point.

It is crucial to recognize achieved milestones. And gently start shifting from strategic to tactical thinking. With business moving into the transition phase, it is a perfect moment for architecture limitations assessment and its re-consideration.

Neglecting architecture evolution will unavoidably trigger fast-paced technical debt accumulation. And the dark side of Monolithic Architecture will start to show off. A rapidly growing business will most likely observe a snowball effect vividly, where overall development efficiency and application availability will degrade exponentially with respect to the business growth.

Limitations

All limitations we discuss below become evident after the MVP milestone. Where application enters the rapid growth phase. Focus transitions from the validation to the market growth (increase in active users) and new feature development become the main focus. This usually comes hand in hand with the development forces count increase.
However, the longer the application architecture stays unchanged after the MVP the more emerging effect these limitations will have.

This is where the bad reputation for Monolithic Architecture is originating from.

Contributors

The Monolithic Architecture suggests a single shared code base. And a single source of truth for the application's data.
A growing amount of contributors will increase the effort required for new feature development. At first any significant and later almost any change will require a series of meetings between teams and extra orchestration.
Obviously, it will unavoidably increase development time. And as a side-effect, it will also build up developers' reluctance to change shared parts of the application, especially the data-access layer. Which will lead to mixed separation of concerns (SoC) and ultimately degrade code quality.

Release

The growing amount of contributors and teams entails a growing amount of integration/friction points. Any small change requires the re-deployment of the whole application. Deployments and especially releases now feel like a burden
Continuous Deployment quickly goes out of the question.

The release process becomes convoluted, shattered with bottlenecks and various box-ticking exercises.
Every release will require some involvement from at least one representative from each team. Release of any size must be planned in advance. Often organizations introduce gatekeepers to control the process.

Often each team will have its own dedicated testing environment to ensure that the development and feature testing process is isolated from constant interruptions by other teams' changes. This in its turn will introduce a certain level of testing redundancy in the release process, as now changes must be double-checked in the scope of release changes.

Scalability 🆙

Monolithic solutions have only one way of meeting growing demands. Scaling up, aka vertical scaling strategy. In other words, grow machine resources. This approach has multiple well-known disadvantages compared to scaling out (horizontal scaling strategy). And typically considered as a poor choice for scaling strategy.

Compared to scaling out. It has a close hard limit. It is not flexible and poorly handling spike loads. Finally, it has lower failure tolerance and unavoidably longer downtimes. Should I say it is way more expensive?

Technology

Monolithic Architecture is usually constrained by technologies selected in the early stages.
However, things are not necessarily smooth even with the existing tech stack. Any change in the framework or language will impact the whole application.
Version upgrades are a risky and laborious process. Usually postponed for as long as possible. And as you can guess only stimulates technical debt accumulation.

Distributed Monolith

As an alternative to the Monolithic Architecture community came up with a Microservice Architecture (aka Microservices). However, often developers unintentionally introduce Distributed Monolith instead of (or within) Microservice Architecture.

A common delusion is that a Microservice Architecture is an approach where some business process or application is built from a set of services (preferably small) as opposed to a Monolithic Architecture where everything is self-contained in a single whole.

This is somewhat true. Although the definition above is leaking a few critical details.

A Microservice Architecture is an approach where the application is built with a set of independently deployable services. The separation of concerns (SoC) is used to decide what concludes an individual service. Hence each service has its own business flow, well-defined purpose and boundaries. Each service is either stateless or owns its data.

The Distributed Monolith is an application that does satisfy the first definition but does not satisfy the second one. Or...

A Distributed Monolith is an approach where the application is built with a set of services and at least one of the points below is true:

some services can't be deployed independently
some services are very chatty
some services share data source
some services don't scale dynamically (independent scaling)

Conclusion

Nowadays Monolithic Architecture is still a good tactical architecture for building an MVP. However, it is very risky to follow a monolithic approach after the initial phases of the product.

Amazon, Netflix, and many others started with Monolithic Architecture. Of course, at that time they didn't have much choice as Monolithic Architecture was considered a traditional architecture, there were no cloud providers, etc.
Nevertheless, nowadays a lot of organizations prefer to start with a Monolithic Architecture. Some of them wisely left the door open for further architectural evolutions. And more importantly, use it when the time comes. Others don't and as a result their development process ends up in a stagnation and solution falls into the tech debt spiral.
In the latter case ultimately everyone agrees to blame Monolithic Architecture and promise "never again".

I think Monolithic Architecture is undeservingly carries bad reputation. Even nowadays Monolithic Architecture has its own place and purpose in business automation and application development.

JavaScript. Memory. Architecture and Lifecycle.

Valerii Udodov — Tue, 19 Oct 2021 07:13:38 +0000

I'll start this article with a quote that changed the way I think of memory. The way I perceive memory lifecycle in major modern languages (those that have automatic memory release aka garbage collection).

Garbage collection is simulating a computer with an infinite amount of memory.
-- Raymond Chen

This is exactly how we think of memory in JavaScript. We don't...

Indeed, since I stopped writing C++ code I forgot about memory management. And I couldn't be bothered. Why would I? I mean it just works. Here's a variable, here's another one, no worries at all... Nowadays memory leak is rarely an issue. Most of the time you need to put an effort to create a one...

But it wouldn't be JavaScript if there were no interesting quirks and features hidden behind this area...

Further, we'll explore JavaScript memory architecture, main concepts and organization. And memory lifecycle, from allocation to release.
Also, we'll look through some common memory leaks and how to avoid them.

Memory

In programming everything requires space. Number, string, object, function. Even in the abstract Computer Science algorithmic department, there's a measurement for a space complexity.

Memory is different

In JavaScript (similarly to many other languages) there are two main types of memory Stack and Heap. Both are managed by the JavaScript Engine, both are for storing runtime data.
The difference lays in speed and size. Heap is bigger and slower, Stack is smaller and faster.

How does the engine know which one to use? The rule of thumbs is: if the engine is not sure about the size it uses Heap. If the engine can calculate the size beforehand, it uses Stack.

All the primitives like number, boolean, string, Symbol, BigInt, null and undefined always go to the Stack. Also, references are stored there, we'll talk about references in a minute.
What's left will end up in the Heap. This includes arbitrary objects and functions.

💡 The data that goes in the Stack is usually called static because it has a static size that won't change, hence it is allocated at the compile-time.
The data that goes in the Heap is usually called dynamic because it has unpredictable size (and potentially can change throughout the program execution) and is allocated dynamically at the runtime.

ℹ️ Have you heard of the term Hoisting?

Memory allocation in the Stack (aka static memory allocation) happening right before the code (next lexical scope) execution. References are stored in the Stack, thus they are allocated before the code is executed. Hence if we declare the variable it will be available even before the actual declaration in the code. Although value will be undefined because it doesn't have value to point to yet...

console.log(yolo); // undefined

var yolo = "hello!";

Variables declared with let, var, const are hoisted, although let and const won't return undefined.

References

The referencing concept is a major pillar of the JavaScript memory organization. It indirectly impacts how most of the key operations (such as assignment and equation) work.
However often it is poorly understood and thus results in occasional surprises and confusions.

Imagine a big bookshelf with multiple compartments. Each compartment has a label with a unique number on it. Every time you place something in the compartment you take a piece of paper and write down the number of the compartment and a short description of what is stored there.

This is the gist of how references work. The short description is a variable name, the shelf number is a memory address. The address is stored in the variable, which is stored in the Stack. And the actual object on the shelf is an object stored in the Heap, referenced by the variable...

Every time we use the assign (=) operator we are not assigning the value... We are creating a pointer to the memory where the value is stored. Your variable storing the address, that pointing to the memory where the actual value is stored.

Some personal opinion here...🤪

I think the language we use matters. Therefore I think the word "assign" and operator = is ~~evil~~ misleading and creates cognitive confusion and unnecessary simplification. I think a huge amount of bugs came from such confusion.

I'd personally prefer to be more explicit about what is happening and suggest using a term like "pointing" or "referencing" instead of "assigning" and operator like -> instead of =.

But we have what we have 🤷

Now that we have an idea of memory organization, let's reinforce it with some examples. We will start with primitive values and gradually move toward objects...

let answer = 42;

As we figured before we are not setting value we are pointing to it... Pretty straightforward so far, let's make it a bit more complicated...

let answer = 42;
let true_answer = answer;
answer = 43;

console.log(answer); // 43
console.log(true_answer); // 42

Same principle here. First both answer and trueAnswer point to the same address where value 42 is stored. Once we do answer = 43 we change not the value, but memory where we pointing...

Primitives are immutable. It kinda becomes obvious and almost redundant to mention if we talk it through. If we try to change 42 (e.g. add 1 to it), we will simply get another number, which is not 42...we won't change 42 (42 will still exist)... Hence it is immutable.
Nor we can extend it. E.g. 42.value = 22 won't work, although it will if 42 would be an object...

Hope it all made sense lol 😅

Let's do another example with primitives... null and undefined are primitives. What does that mean? They act like all primitives...

const null1 = null;
const null2 = null;
console.log(null1 === null2); // true

let undefined1;
let undefined2;
console.log(undefined1 === undefined2); // true

Now we see why both values are strictly equal, pointing to the same value.

Funny fact

console.log(typeof null); // object

It is not true, null is not an object. It is a bug that can't and won't be fixed...

Let's do the last one on primitives...

const a = true;
const b = false;
const c = true;
const d = false;
const e = true;

Everything looks very familiar.

Now let's try something new. Objects. Objects are different, they represent a more complex tree-structure 🌳. And unlike primitives, objects are mutable. This property produces some interesting effects.
This is where the = operator will reveal its full evilness 😈.

const catzilla = { name: "Catzilla", breed: "Bengal Cat" };

const peanut = catzilla;
peanut.name = "Peanut";

console.log(catzilla); // { name: "Peanut", breed: "Bengal Cat" }
console.log(peanut); // { name: "Peanut", breed: "Bengal Cat" }

Probably not what was intended...
Remember that the = actually points to the data. We are just routing pointers here.

Luckily we can fix it easily...

const catzilla = { name: "Catzilla", breed: "Bengal Cat" };

const peanut = { ...catzilla };
peanut.name = "Peanut";

console.log(catzilla); // { name: "Catzilla", breed: "Bengal Cat" }
console.log(peanut); // { name: "Peanut", breed: "Bengal Cat" }

With a help of ... (spread operator) we managed to clone whatever catzilla was pointing to in the new address and made peanut point to it. This is not the original intention, how this operator should be used. But (as it usually happens with JavaScript) this side-effect was warmly accepted by the JavaScript community as a way to perform shallow cloning.

Things start to get really messy with more complicated objects...

const breed = {
  name: "Bengal Cat",
  origin: "United States",
  color: { pattern: "spotted", name: "brown" },
};

const catzilla = { name: "Catzilla", breed: breed };

const peanut = { ...catzilla };
peanut.name = "Peanut";
peanut.breed.color.name = "marble";

console.log(catzilla);
/*
  {
    name: "Catzilla",
    breed: {
      name: "Bengal Cat",
      origin: "United States,
      color: {
        pattern: "spotted",
        name: "marble"
      }
    }
  }
*/
console.log(peanut);
/*
  {
    name: "Peanut",
    breed: {
      name: "Bengal Cat",
      origin: "United States,
      color: {
        pattern: "spotted",
        name: "marble"
      }
    }
  }
*/

It happened again... Both cats have the same color, although it wasn't the intention...

We are performing the so-called shallow clone only top layer (first level of the tree), to make it work properly we need to perform so-called deep cloning. The easiest way would be doing something like...

// ...

const peanut = JSON.parse(JSON.stringify(catzilla));

// ...

Ugly, but does the job. It forces the engine to allocate a new chunk of memory and fill it with object data.
Unfortunately, JavaScript does not provide a good cloning mechanism out of the box. Hence this is the approach to clone the object without employing extra tools.
If you are after a more elegant and efficient solution, I'd recommend using something like underscore.js.

Alright, here's a curly one ⚾... Can you guess why this happening?

console.log({} === {}); // false

Surprised?
Let's try to re-write this example a bit...

const value1 = {};
const value2 = {};

console.log(value1 === value2); // false

Does it make more sense?

To understand it completely we need to understand how the equals == and the strictly equals === operators work, unfortunately, it is not very trivial. However, to prevent this article from bloating, let's just say that comparison happening by actual value in the variable. As we know now it is an address of the object, rather than value. Because we are pointing to two different objects, located by two different addresses. Values are not equal...

Garbage Collection

The concept of reference (which we just discussed) is what the process of memory releasing/cleaning (aka garbage collection) is based on. Using references garbage collector can determine what is "garbage" and requires a collection and what is not yet.

There are two main algorithms used for that matter.
The "new" one: its variation is used in all modern browsers
And "old" one: nowadays its variation is rarely used anywhere, because of its built-in flaws (we'll talk about them further)

New: Mark And Sweep

Principle lays in finding unreachable objects...
The unreachable object is any object that can't be reached via traversal through references from the so-called root. In browser-world root is represented by the window object (aka Global Scope).

📝 Just a side-note, that all global variables in JavaScript are not hanging in the air, they are rather attached with references to the window object...

Every now and then, garbage collector starts. And follows these phases

Start phase: Once started, it assumes that all objects are unreachable.
Mark phase: Then the actual tree traversal from the root (through references) starts. Every object found on the way is marked as reachable.
Sweep phase: Once traversal is finished all unreachable objects are eliminated.

Optimization

Mark and Sweep algorithm belong to the Tracing Garbage Collection family. There are few family-dedicated optimizations (like tri-color marking). These are low-hanging fruits 🍐.

Nevertheless, most JavaScript Engines will perform some additional optimizations that are usually borrowed from other garbage-collected languages.

One such classic optimization is the so-called garbage collection based on generations.
The principle is based on one observation. Old objects are less likely to be garbage-collected. They proved it by surviving multiple garbage collections. Thus statistically we can assume these objects will be kept in use.
With this knowledge, we can improve the garbage collection time significantly by simply rarely bothering old objects 👴.

Here is how it works. Each object is assigned to a generation. All objects start at the zero generation. If an object survives garbage collection it moves up, to the next generation. The garbage collection is happening on the young generations more frequently than on old ones.
The more garbage collections object survive the older generation it is assigned to and the less likely it will be collected.
Ultimately this approach reduces traversals through statistically "low-chance-collection" candidates. And focus on those who statistically have higher chances to be collected...

Old: Reference Counting

This algorithm was last used in IE 7 and deprecated since 2012. So this section serves purely historical purposes.

Unlike the Mark and Sweep, this one will try to find unreferenced objects instead of unreachable...
This algorithm does not try to determine whether the object is still needed (in the previous example reachable from the root). Instead, it only checks if anything references the object.

This might not look like a big difference, but this approach is less restrictive. And due to this fact comes with a major flaw.

Major flaw

The major flaw is circular references. Two objects might not be reachable, but as long as they reference each other they won't be collected.

Let's look at the following example...

function catdog() {
  let cat = {};
  let dog = {};

  cat.dog = dog;
  dog.cat = cat;

  return "hello";
}

catdog();

The above code (if used with the current algorithm) creates a memory leak. Because memory allocated for variables cat and dog will never be collected, even though it never used in outer scope...🐱🐶

Memory Leaks

🤔 Why do memory leaks still exist?

Because the process of determining whether a certain piece of memory is used or not is a so-called undecidable problem. Sounds scary, but it means that there's no good way to program a machine to determine if memory can be safely released. Thus only a human can make a real complete judgment about it.

While we were exploring the old garbage collection algorithm we saw an example of a memory leak. It appears that a memory leak is just an accidentally forgotten reference to an object. An object that never going to be garbage-collected. And will keep uselessly occupy memory as long as the application is running. There are quite a few ways to create a memory leak.
Since we know how the memory is allocated and garbage-collected we can look through few most common examples

Global variables

Nowadays usage of global variables is a mauvais ton (bad practice). If happens, it is usually accidental. This problem can be easily caught by the linter 👮. Or prevented from happening by adding use strict at the beginning of the file.

The leak happens like this.

We create a global variable (it is automatically referenced by window).
And it forever stays there...

The Fix

Don't use global variables.
It has been recognized as a bad practice for a reason. So the best way to avoid this problem is simply to avoid global variables.

Observers or Forgotten interval timers

This one is harder to trace, we forget to release timers once we don't need them.

This leak happens like this.

We create an interval timer with a callback like setInterval(() => {}, 1000);
We make sure we referencing something from the outer scope
The thing we reference will never be garbage-collected

const memoryLeak = {
  counter: 0,
  massiveData: new Array(100).join('I am your memory leak!');
};

setInterval(() => memoryLeak.counter++, 1000);

The memoryLeak object will never be released even though we might not need the whole object anymore.

The Fix

The best way to prevent this from happening is

// ...

const timerId = setInterval(() => memoryLeak.counter++, 1000);

// do stuff

clearInterval(timerId);

A Camouflaged version of the global variable or Detached DOM elements

Another classical one. If you are working with something like React or Angular, there's no reason to worry. Nevertheless, it is an interesting way to lose some memory 🧠...
It is a camouflage version of the global variable memory leak. And it happens even nowadays pretty often, usually in-between the script tags.

This leak happens like this.

We reference arbitrary DOM elements in the code (e.g. by calling document.getElementById('i-will-leak'))
Even though we delete the element from the DOM it still hangs in the lexical scope or global scope (e.g. by calling document.body.removeChild(document.getElementById('i-will-leak')))

<script>
  var memoryLeak = document.getElementById('i-will-leak');
  document.body.removeChild(memoryLeak);
</script>

The memoryLeak will never be garbage-collected, the removeChild here is very misleading, it seems like it will remove the element from everywhere, but it does it only for the DOM tree.

The Fix

The fix is the same as for the Global Variables leak. Don't use global variables 😀 Instead, we can use child lexical scope, e.g. function

<script>
  function doStuff() {
    var memoryLeak = document.getElementById('i-will-leak');
    document.body.removeChild(memoryLeak);
  }();
</script>

This is self-executable function will create a local lexical scope and after it will finish execution, all local variables will be garbage-collected.

P.S.

If you've read my previous JavaScript-Runtime-related articles, you know that JavaScript Runtime differs between browsers. Therefore the way memory is managed from browser to browser might be different. Although it would be unfair not to mention that in the past decade more and more commonalities appearing. And reduces a headache for us...
Moreover, given the unstoppably growing JavaScript infrastructure, including various linters, module bundlers, and well-matured frameworks for DOM interactions, problems with memory leaks are reduced to a bare minimum.

But...Garbage collection is still listed as an undecidable problem, hence there's always a way to make a boo-boo. Understanding the way JavaScript organizes the memory and how references are managed might save you hours and hours of debugging.

Anyhow, hope you enjoyed the read and found something new for yourself 😀

Run, JavaScript, Run

Valerii Udodov — Thu, 09 Sep 2021 02:09:10 +0000

Preamble

Let's admit. JavaScript is not the most predictable language out there. It might get pretty quirky very easily.
Let's look at the following example.

setTimeout(() => console.log("1. timeout"));
console.log("2. console");
Promise.resolve("3. promise").then((res) => console.log(res));

// prints
// 2. console
// 3. promise
// 1. timeout

Even if we will change the order of instructions, it won't impact the final result 🤨

Promise.resolve("1. promise").then((res) => console.log(res));
setTimeout(() => console.log("2. timeout"));
console.log("3. console");

// prints
// 3. console
// 1. promise
// 2. timeout

It doesn't matter how we will shuffle these three lines, they will always end up executed in the same order console, promise, timeout 😐

Why? Well, you know...

Of course, there is a good (enough) reason for that. And we'll get to it shortly. But first, we need to clarify a thing or two.
Put on your JavaScript hat and let's go! 🎩

We are going to focus on the Web Browser JavaScript, nonetheless most of the things we are going to discuss can be correlated to other agents, such as NodeJS.

ℹ️ Worth mentioning

setTimeout(() => {}) is equal to calling setTimeout(() => {}, 0).
Although neither will guaranty immediate execution as the timeout value (0) is used to set the minimum wait period, not the exact period.
Anyhow example above is completely legit in a given context.

One thing at a time

There's one important aspect of JavaScript we need to call out from the start. The single-threaded nature of the environment it runs in. It is hard to overstate the impact of this fact on the language, web browsers, and ultimately anything that runs JavaScript.

one thread === one call stack === one thing at a time
Pause here for a sec... One thing at a time...

Even when it seems like multiple things are happening simultaneously, in reality, there's only one single task that gets executed at every given moment, just really fast.

The single thread we were talking about is called browser main thread (nowadays more accurate name would be a tab main thread 🙃)... Thus everything that happening on the page is happening in one single thread.
It is easy to underestimate the scale. While our gorgeous code is running, meantime the web browser is rendering page content, receiving and dispatching all sorts of events, doing garbage collection, distributing future work, and much more...

ℹ️ What about JavaScript Console, that thing we all use in the Browser Dev Tools?
It depends, but most likely it will be a different process, hence a different thread.

❗Exception...

The "single thread" thing is the default behavior, however, we can branch from the main thread and run our JavaScript code in the separate thread with a help of Web Workers API.

A single thread is not a mistake or a bad design. Make JavaScript single-threaded was a conscious decision... Years ago, the average computer had a single core and was less powerful than any mid-range phone today. Websites were not really interactive (if at all), hence didn't really need any JavaScript magic.
Who could foresee where it is going to end up...

That thing that runs your JavaScript

Often terms JavaScript Runtime and JavaScript Engine are used interchangeably. Nevertheless, they are like salt 🧂 and green 🟩. Two completely different things. Let me explain what I mean.

Three main pieces constitute the JavaScript Runtime. They are conceptually separated. And most likely developed by different people/teams/companies, and represent independent pieces of software. However, they work in close collaboration.

JavaScript Engine: compiles, optimizes, and executes code, handles memory allocation and garbage collection
Event Loop: orchestrates and distributes the work, enables asynchronicity.
Browser Web API: allows communication with things located outside of the Runtime (e.g system timers, file system, HTTP, address bar, DOM, etc.)

The Big Picture

The Engine

The JavaScript Engine... does not run JavaScript...It runs ECMAScript.
Isn't it the same thing? Appears no, I'll explain.

If we will look through the source code of an arbitrary JavaScript engine (you know, cuz it is a casual thing we do lol 🤪), we will find an implementation of the ECMAScript declaration. This will include all sorts of base objects (including Object) such as Date and String, key language constructions like loops, conditions, and so forth.
However, if we will look for say setTimer or fetch, we won't find much. Because they are not part of ECMAScript. They are part of Browser Web API (nothing to do with Web itself really, more like Browser API 🙃, but you'll find it going under Web API, Web Browser API, Browser API and simply API).

The JavaScript Engine will be managing memory and controlling the execution of our fabulous code. Which will never be executed in its original shape, the engine will keep modifying it all the time. Most of the engines are pretty smart, they will keep optimizing the code throughout the page lifetime in the constant chase for performance improvements.

Important though is that the engine only executes the code that it finds in the Stack of Frames (or Call Stack or simply the Stack). Each frame represents a function call. While the engine is running the code, it might discover a new function call (not to be confused with function declaration) and push it to the Call Stack as a new frame. Once a new frame has been added, the engine pauses the execution of the current frame and focuses on the new one. After Engine finishes frame(function) execution it pops it from the stack and continues where it left, assuming it is not the last frame.
Every function call will end up as a new item on the Call Stack. Worth mentioning that Engine does not own exclusive rights on pushes to the Call Stack, new work might be pushed from the outside of the engine boundaries (we'll talk about it next).
The Call Stack controls the execution sequence inside Engine. Engine won't stop popping frames from the Call Stack until it is empty. And it won't allow any interruptions from outside until it is done.

⏪ In the previous article Web Browser Anatomy we've already discussed some of the key JavaScript engine aspects (parsing, pre-parsing, compilation, and optimization/de-optimization). With a deeper focus on the V8 Compilation Pipeline.
The article is more focused on the code processing itself and slightly touches Browser Engine (not to be confused with JavaScript Engine) and basic rendering concepts, so if it sounds interesting, don't forget to check it out after. 😏

The Loop

The Event Loop is an orchestrator and the main distributor of the work. It does not perform the work itself, but it ensures that the work is distributed in the expected manner (which may vary from browser to browser).

It is literally an infinite loop ♾️ which constantly keeps checking if there's any work it can schedule for execution.
A simplified version would look like this

while (true) {
  if (allDone()) {
    const thingsToDo = getThingsToDo();
    doThings(thingsToDo);
  }
}

ℹ️ On each iteration, the Event Loop performs an ordered series of jobs defined in the processing model documentation. We will be getting back to it through the course of the article.

The Event Loop and event loops

The Event Loop we usually refer to in the context of the web browser is a Window Event Loop. Every origin will get one. However, sometimes few tabs/windows from the same origin might share a single loop. Especially when one tab is opened from another. (This is where we can exploit multiple tabs/pages at once)

Anyhow, Window Event Loop is not the only one event loop running in the browser. Web workers (and other workers) will use its own Worker Event Loop. Sometimes it will be shared across all workers. And worklets will have its own Worklet Event Loop.

But hereafter when we refer to Event Loop we will actually be referring to the Window Event Loop.

Tasks, Microtasks and Macrotasks

Given the single-threaded nature of the language, it is hard to overstate the importance of asynchronicity.
The async behavior is implemented by a set of queues (FIFO).

This is a very common approach. Queues are very comfortable for implementing asynchronicity in software (and beyond its boundaries).
Think of a cloud architecture. With a high probability in its heart, there will be some sort of queue that will be dispatching messages all over the place.
Anyway, back to JavaScript.

There are two (not three...) main types of queues, task queue, and microtask queue. At the first glance, it might look like they are identical. And it is true to some degree, they have the same role: postpone code execution for later. The difference lies in how Event Loop uses them.

❔You probably wondering where did macrotasks go...
Macrotask is just a V8 name for the task. So thereafter we will use the term task and everything we say for the task can be applied to macrotask

Task queue

The task queue is what keeps the whole thing spinning. This is where most of our code gets scheduled for execution. Event the initial code (the one that we place in-between the <script>...</script> tags) gets to the Call Stack through the Task Queue.

Often our code looks like this

do this on button click
do that when the server responds
call the server

In other words, we define callbacks (what to do) and assign them to events (when to do) that suppose to trigger them. When the event happens it does not execute the callback immediately, instead, it creates and enqueues a task in the Task Queue, which in its turn will be eventually processed (in other words pushed to the Call Stack).

The queue is out of our direct reach. Dequeueing is happening inside the event loop. Most of the tasks are enqueued through so-called generic task sources. This includes user interactions, DOM manipulation, network activity and history. Although we obviously have a way to impact what and when will get to the Task Queue (e.g through event handling).

Ok, that's gonna be a tough sentence, so bear with me here... Dequeueing process happening once per iteration and it will least (keep dequeuing) until the newest task from the previous iteration (that have been in the queue at the moment of the beginning iteration) is still in the queue. Keep in mind that the newest tasks will be in the tail of the queue, due to FIFO (First In First Out) concept.
In other words, all new tasks we are adding will be executed in the next iteration, all current/old tasks will be executed in this iteration.
As per processing model documentation.

😮 The task queue is not really a queue, but an ordered set. However, it is not very important as its behavior in this context is equivalent to the queue.

There might be (and probably will be) multiple task queues in a single event loop. The most common reason for that is task priority management. E.g. there might be a separate task queue for user interactions and another queue for everything else. This way we can give user interactions higher priority and handle them before anything else.

Microtask queue

Promises, asynchronous functions all this goodness is empowered by the microtask queue. It is very similar to the task queue, except for three major differences.

Microtasks are processed at different phases in the Event Loop iteration. We mentioned above that each Event Loop iteration following strict order known as processing model;
Microtasks can schedule other microtasks and the new iteration of the Event Loop won't begin until we reach the end of the queue;
We can directly enqueue a microtask with queueMicrotask;

The rest is pretty much the same, once a task is dequeued and a callback is extracted, it will be pushed to the Call Stack for immediate execution.

Browser Web API

The final piece in the puzzle is an API, the Browser API. The connection bridge between the code and everything outside of the runtime.

Communication with a file system or remote service calls. Various event subscriptions. Interactions with the address bar and history. And more. Is facilitated by Browser API.

Browser API allows us to define event handlers. And this is the most common way for developers to pass callbacks (event handlers) to the Task Queue.

Browser API are browser-specific. Each browser implements them separately. Hence they work differently, although probably will have the same effect.
Hence every now and then you might bump into a cool new feature that won't be supported by ~~Internet Explorer~~ Browser X. And the most common reason, the API is not implemented in the Browser X.

At least nowadays the naming is kinda conventional and no one tries to show uniqueness...
Imagine writing code when all browsers would name things differently and everything would produce different effects... That would be a nightmare, wouldn't it?
Well, it used to be like that. And it is kinda like this nowadays lol. Fortunately, we have many tools like BabelJS and a huge community behind that helps mitigate this problem for us.

I still remember 👴 how you had to implement ajax calls (XMLHTTPRequest) for all possible browsers in your code until the jQuery appeared. That was a game-changer.

Bringing things together

We've discussed quite a few things thus far. Let's bring them all together in a single list. And go over it in the same order as Event Loop will.

Remember that once some code gets in the Call Stack, the Engine will hijack control and start popping, executing, and pushing the code until finally, the Call Stack is empty. Once reached the end of the stack it returns control to the same point where it hijacked it.

The browser will find some JavaScript either in-between the <script> tags or in the DevTools Console. And ultimately it will push it to the Task Queue...

The Loop keeps checking the Task Queue. Once it finds the initial code the Loop will move it to the Call Stack. The Engine immediately takes over and doing its job until it empties the Call Stack.
The Loop will check microtask queue(s). It will keep dequeuing tasks from the queue and pushing them (one item at a time) to the Call Stack (and it will keep executing until empty) from the microtask queue until the microtask queue is empty. Remember that microtask code can push another microtask in the queue and it will be executed during the same iteration (right here).
Both Engine Call Stack and Microtask Queue are now empty.
Finally the Loop gets back to the Task Queue. Keep in mind that events were emitting all the time, either in the code or outside of it. The Loop will mark the newest task (the one in the tail of the queue) in the queue and start dequeuing tasks from oldest to newest (head to tail) and pushing code to the Engine Call Stack until it reaches marked task.
Next it will do some other unrelated to the runtime work, like rendering.
Once all is done the new iteration starts from point 1

The example

Let's revisit the example from the beginning of the article...

setTimeout(() => console.log("1. timeout"));
console.log("2. console");
Promise.resolve("3. promise").then((res) => console.log(res));

// prints
// 2. console
// 3. promise
// 1. timeout

Doesn't matter how we would shuffle instruction, the produced result will stay the same

Actually now it makes much more sense, check it out.

First, all this code is sent to the Call Stack and executed sequentially.
- setTimeout almost immediately sends a callback to the Task Queue.
- console.log prints string in the console (this is our first line 2. console).
- Promise.resolve(...).then(...) is immediately resolved promise, thus it sends the callback to the Microtask Queue the same moment it is executed.
Stack finishes execution, it is empty and it passes control back to the Event Loop.
Event Loop checks Microtask Queue and finds there callback from the resolved promise and sends it to the Call Stack (this is our second line 3. promise)
Microtask Queue is empty, Call Stack is empty, it is Task Queue turn now.
The Event Loop finds a timeout callback in the Task Queue and sends it to the Call Stack (this is our third and last line 1. timeout).

And we are done, the stack is empty along with all queues.
That wasn't too bad, was it?

Recursion Examples

Alright, it is time to have some fun! 🤓
Given we already know how to interact and what to expect from both queues and a stack. We will try to implement three different infinite recursion examples. Each will utilize one given mechanism.

It will be more fun if you'd open a console and try to run code examples on your own. Just don't use this page's console lol.
I'd also advise preparing Browser Task Manager to keep an eye on changes in memory and CPU consumption. Most of the modern browsers will have one somewhere in settings.

Let's start with classics.

Call Stack

const recursive = () => {
  console.log("stack");
  recursive();

  console.log("unreachable code");
};

recursive();

console.log("unreachable code");

/*
stack
stack
stack
...

Uncaught RangeError: Maximum call stack size exceeded
    at recursive (<anonymous>:2:1)
    at recursive (<anonymous>:3:1)
    at recursive (<anonymous>:3:1)
    at recursive (<anonymous>:3:1)
    at recursive (<anonymous>:3:1)
    at recursive (<anonymous>:3:1)
    at recursive (<anonymous>:3:1)
    at recursive (<anonymous>:3:1)
    at recursive (<anonymous>:3:1)
    at recursive (<anonymous>:3:1)
*/

The infinite recursion and its good old buddy Stack Overflow Exception. I bet you've seen a few of these before...
The Stack Overflow Exception is about reaching the max size of the Call Stack. Once we exceed the max size it will blow up with a Maximum call stack size exceeded.

Note that there are a few console.log that will never get printed.
Remember that every time we push a new item on the Call Stack, the Engine will immediately switch to it, since we are just pushing new items and never popping. The stack keeps growing until we reach its maximum...

Task Queue

Let's try the Task Queue now. This one won't blow up immediately, it will run much longer util the browser propose you kill the page (or wait if you are insistent).

const recursiveTask = () => {
  console.log("task queue");
  setTimeout(recursiveTask);

  console.log("reachable code 1");
};

recursiveTask();

console.log("reachable code 2");

/*
reachable code 2
task queue
reachable code 1
task queue
reachable code 1
task queue
reachable code 1
task queue
reachable code 1
...
*/

Note that both extra console.log statements are printed. Because all the time we are adding a new task to the Task Queue, we add it for the next iteration and not for immediate execution. Hence all code in this example is processed before starting a new iteration.
Keep an eye on the memory footprint. It will be growing fairly fast together with CPU usage. Under a minute my tab went over 1 Gig of memory.

Microtask Queue

Ok, the final one, we'll do the same stuff, infinite recursion, but this time for the microtask queue.

const recursiveMicrotask = () => {
  console.log("microtask queue");
  queueMicrotask(recursiveMicrotask);

  console.log("reachable code 1");
  setTimeout(() => console.log("unreachable code 1"));
};

recursiveMicrotask();

console.log("reachable code 2");
setTimeout(() => console.log("unreachable code 2"));

/*
reachable code 2
microtask queue
reachable code 1
microtask queue
reachable code 1
microtask queue
reachable code 1
microtask queue
reachable code 1
...
*/

Note how tasks from the Task Queue are never executed ("unreachable code"). This is happening because we never end up current Event Loop iteration, we keep adding microtasks to the Microtask Queue and it prevents the iteration from finishing.
If you will leave it for long enough you'll notice that the page (including the address bar) becomes less responsive. Until it completely dies.
Of course, the memory footprint (and CPU usage) will keep growing much faster, since we polluting the Task Queue, but if we will remove both setTimeout it will reduce the pace of memory footprint growth.

📝 Side note

Recursion might be dangerous for infinity simulation. I'd recommend looking into generator functions for such matters. We won't get under the boot of generator functions. At least for now.

But here's a small example of an infinite number generator, which shows the gist of it.

function* generateNumber() {
  let i = 0;

  while (true) yield i++;
}

const numbers = generateNumbers();

console.log(numbers.next().value); // 0
console.log(numbers.next().value); // 1
console.log(numbers.next().value); // 2

That's it.

Of course, everything we looked at is a simplified representation. However, it illustrates in enough detail how the Runtime functions. It is accurate enough to explain the true nature of asynchronicity and code execution sequences in JavaScript. As well as hopefully reveal some "odd" behavior and "unexpected" race conditions.

JavaScript has an extremely low entrance barrier. And often it is confused with being unstable.
However, some of its behavior is a trade-off of some sort and payment for such a low entrance barrier. Although few bugs are left there for backward compatibility lol...

If you enjoyed the read, don't forget to check out another related article Web Browser Anatomy.

👋

Clean Event-Driven Architecture

Valerii Udodov — Thu, 15 Jul 2021 12:13:25 +0000

In general clean architecture is a pretty bold statement. However, at the same time, it is a hollow and opaque thing to say.
How do you measure the cleanness of the architecture? By the number of components in the system? Nope... Whether it is cloud-first or not? 🤷. By the number of rectangles on the whiteboard? Probably not. Does your source code suppose to look good? It supposes to, but you know... Test coverage? Easiness of writing tests? Extensibility? Is 10-year-old clean architecture is still considered clean nowadays?

You will find million of clean architectures online. Whenever someone says "clean architecture" both my subconsciousness and google search pulling out the same thing. The book "Clean Architecture: A Craftsman's Guide to Software Structure and Design" by Uncle Bob Martin. The main pillar, or to be more precise 5 pillars are S.O.L.I.D. principles. You can even find it on Wikipedia. I mean you know the thing is serious when you can find it there...
Once something gets popular it immediately starts the flame of rage. Like Linux vs Windows, Android vs iOS, C# vs Java, Angular vs React, you name it...
Well S.O.L.I.D is no exception. There are many people in opposition to ole' Uncle Bob. One that (IMHO) outstands is Dan North. You might have heard of him as one of the originators of Behavior-Driven Development (aka BDD). This guy deserves some credit. Anyway, he came up with his own Clean Architecture principles CUPID.

What I'm saying here is that the principle acronym must form a catchy word! Oh and that any principle is not a silver bullet, even following SOLID principles you might end up with a big ball of mud. But there are a bunch of valuable guidances, following which might reduce the probability of 🦆ucking things up.

I think of Clean Architecture as a philosophy of some sort. It is not completely about the system today, but about the system today and tomorrow. It is not an arbitrary set of patterns, approaches, or coding technics. Clean Architecture is a product of system thinking that enables system evolution through continuous refactoring without ruining the integrity of the system (in any way you can think of it).
There is no such a thing as a complete code or finished software. There is abandoned or deprecated software. Everything else is a "work in progress".
Unfortunately, we can't forecast the future, but we can make sure that however, we decide to build the application today won't bite us in the future. The design must be sustainable, robust for changes. It should be built with refactoring in mind.

Of course, a nice diagram is a must too 🙃

The Triangle 📐

So here we go, let's start with the diagram...

It is pretty much 3 triangles, one overlaying another forming three levels. All together it represents a visual representation of the architecture. We will go over all of the levels from the inside out.

Inspirations and ideas

At the high level, this architecture represents a mixture of hexagonal architecture (aka ports and adaptors) and its close buddy onion architecture.

Here are few things worth highlighting at the start

Coupling. The coupling goes inwards and only one level deep. There should be no outward dependencies and hops or bypasses between triangles.
Levels. Every triangle/level bounds together concepts that have a similar rate of change.
Sides Sides are these named trapezoids. There are three sides on each level. Each side can communicate with its level neighbors.
Direction. Every side has a strictly defined direction of data flow and communicational purpose.

At the first glance, all these concepts might feel a bit convoluted, but by the end of the article, they should make more sense. So without further ado, let's begin.

Core Triangle. Level 1. Events. Storage.

In the heart of the architecture are events. It kinda makes sense, given we are talking about event-driven architecture 🙃.
This means that the source of truth for the system state is stored as event streams. In the... wait for it... event store. You might know this pattern as Event Sourcing.

The fundamental idea of Event Sourcing is that of ensuring every change to the state of an application is captured in an event object, and that these event objects are themselves stored in the sequence they were applied for the same lifetime as the application state itself.
-- Martin Fowler, Event Sourcing

Event Sourcing is not new, it has been around for decades. I believe one of the reasons for its gaining popularity is that it fits really well in the Domain-Driven Design. In fact, one of the key elements of Domain-Driven Design is so-called Domain Events. Which will be a one-to-one map to what we will be stored in our "clean" Event Store. More on DDD coming further

This architecture is not database-centered, following the advice from onion architecture, the database is infrastructural detailed. And as per this diagram, it lays in another dimension.

These events are what we would call private events. Events that will never leave boundaries of this application. Or event level 2. Hence is the name private events.

Key takeaways

Events are a source of truth for the system. They are hidden from the outside and never leave application boundaries.

Middle Triangle. Level 2. The Logic.

This is the place where a lot of things will be going on. Business logic, data mapping, and exposure, and much more...

Domain

Let's start with the Domain. I'm a Domain Driven Design evangelist. Thus here under Domain I imply what Eric Evans implies by Domain in the Blue Bible of Domain-Driven Design

Domain-Driven Design is an approach to software development that centers the development on programming a domain model that has a rich understanding of the processes and rules of a domain.
-- "Domain Driven Design" Martin Fowler

The key thought is -> Without a well-crafted, religiously modeled domain, there's no way we can produce clean architecture. That's a given. We must understand, not guess, but understand what we are building. Which business problem we are solving. DDD is a great tool for that.

There's a bit of color-coding going on on the diagram. If you look closely, you can see that domain and commands are in different colors. The color indicates the direction of the data flow in the system. The domain belongs to the writing layer.
Domain encapsulates all invariants and emits events. The role of the Domain is to validate whether the system in its current state can satisfy the incoming request (aka command) or not.

Notifications ✉️

Notifications aka public events. These are events that are often constructed from private events. Their only responsibility is to notify the outside world that something important has happened. These events are used nowhere internally, they always go outside. Think of public events as public APIs. Hence the name public events.

Segregation of private and public events is not a new thing. It is quite easy to get into the boundary trap that exists between event-sourced application and outside.

Keep in mind, it is not necessary one-to-one mapping with private events. Different strategies might be employed here to reach the expected outcome. Some time ago I wrote about accumulator pattern. That helps the system to produce good quality public events, and not broadcast everything that is happening internally.

Events might be as lean as

{
  "name": "user-added",
  "id": "fd4d6b2a-7079-4898-9624-3d2b1558b452"
}

This event basically notifies the outside world about the fact that the user has been added and provides a piece of minimal viable information for anyone to go and pull any extra required information.

Or an event might be beefier like

{
  "name": "user-added",
  "id": "fd4d6b2a-7079-4898-9624-3d2b1558b452",
  "firstName": "John",
  "lastName": "Doe",
  "sex": "male",
  "dob": "12/12/1980",
  "shoeSize": 42
}

This event transmits everything the system knows about the new user.

Which one to use is dependent on how generic and re-usable your public event should be. Do you want to serve extra information on-demand or broadcast all the changes once they occur?

Projections

Projections or projected views serve purely read purposes. They usually represent a denormalized representation of the data stored in the event store. Denormalization of the data is necessary to tune its shape to a specific query. Therefore provide a cheap and easy way to query the information.
It is a great way to serve general-purpose queries, e.g. "give me a list of all users in the system". Another way of looking at it is as a long-living cache.

Denormalization of data is a sort of anti-DRY principle. Data duplication is natural for this approach. The key driver is to make the read layer as efficient as possible, by reducing time-waste on data construction. The data is not constructed on demand, it is prepared upfront for the easiest digestion. Moreover, the data might be preformatted, to reduce the load from the UI (or any other consuming system).

Projections are filled during the application runtime. Usually, it depends on whether data have to be strongly consistent or not, the projection process will be either synchronous or asynchronous.

Key takeaways

The only way to mutate the system state is through the Domain. A well-crafted Domain is crucial. The domain is responsible for validation and events emission.
Notifications are public events that are targeted outside of the application boundary, keeping external systems up to date with important updates.
Projections are denormalized views of the event store. Projections are filled by projecting private events during the runtime. Data is always shaped in the most comfortable way for query execution.

Outer Triangle. Level 3. The Exterior.

The outer layer is exposed to the outside world and defines communication contracts. Disregard any particular technology or communication protocol. We are all about abstractions and fancy diagrams here :D

💡 Key patterns used here are Command Query Responsibility Segregation (aka CQRS) and Outbox.

We'll start with a traditional CQRS, that will cover two corresponding sides of the triangle. I'm sure you guessed, but anyway 🥁... commands and queries.

Commands

The only way to mutate the system state is by issuing a command. If the client wants to perform an action that supposes to end up with a state update, it has to go through the commanding part of the layer. A command is an intention, not a fact. It might be rejected as well as accepted. If the Domain from Level 2 says "no" to a command it is marked as rejected.

Queries

On the other hand, if the client wants to read the state, the inquiry has to go through the querying part of the triangle. The query must ask a well-defined, expected question. The projections (from Level 2) will provide well-formatted sufficient data, that will be propagated all the way to the client.

🎈 A while ago, I wrote a few articles dedicated to CQRS. The introduction into CQRS and series that explains how to implement CQRS via HTTP. So if you are keen, check it out ;)

Outbox 📤

Last, but not least is the Outbox. It consumes so-called public events (aka notifications) and ensures they are dispatched outside with an "at least once" delivery guarantee and respecting the order. This is the main channel for public events to get outside.
The concept of public events and outbox eliminates the boundary trap.

Key takeaways

This level defines clean mechanisms for communication with the system. There's only a single way to impact the system state, through Commands. There's the only way to read state, through Queries. And finally, there's the only way to subscribe to the latest updates from the system, through the Outbox.

Bottom Line

That's how I envision clean event-driven architecture. Each moving part has a well-defined responsibility and direction of data flow. And this way each part can evolve, scale, be replaced, or re-factored independently.

Hope it all makes sense, let me know if it doesn't.
Keen to hear your thoughts and arguments 🧠 💭

Event Sourcing: Events Evolution, Versioning, and Migration

Valerii Udodov — Sun, 20 Jun 2021 09:32:07 +0000

Before we begin

There are few things worth noting before we kick things off...

First thing

Let's clarify what do we mean by the term Event Sourcing. Event Sourcing is an approach for storing and restoring system state in/from a series of strictly ordered events, grouped into streams.. Ultimately it is a way of communication with the database or wherever events are stored.

The fundamental idea of Event Sourcing is that of ensuring every change to the state of an application is captured in an event object, and that these event objects are themselves stored in the sequence they were applied for the same lifetime as the application state itself.
-- Martin Fowler, Event Sourcing

If you'd like to get a more in-depth definition of the term Event and look at different technical contexts that utilize events, check out my previous article "Different Flavours of Events". Where I go over major event-driven architectures, including Event Sourcing.

Anyhow all the definitions above miss one important aspect. Events are not arbitrary blobs of data or objects. Each event has a name (or we can call it a type) that captures its meaning for the system and often some extra data to enrich the cognitive value of itself.
Another way of looking at events is as a contract. In Event Sourcing, it is a contract between something that uses events and something that stores events. Let's keep it in mind for later.

Second thing

Few more terms that often have a vague meaning. Sometimes event versioning and event migration are used as synonyms or substitutional terms to define the actual process of event evolution. However, it is two separate, although dependent problems that need to be tackled independently. Thus I emphasize attention on segregation, versioning goes left, migration goes right.

Third thing

You probably heard of it. Event Store is immutable. And it is not completely true. Hold your tomatoes 🍅 for a minute. I'll try to explain what I mean, without going too far in-depth...
The data in the Event Store is immutable or should be treated as immutable only from the business perspective. In other words, during the routine application work, the only allowed actions are new stream creation and new event emission. And any sort of reading actions.

Imagine a banking application where each bank transaction ultimately becomes an event. If the user mistakenly transfers money from one account to another and wants to revert the faulty transaction. The revert action should not eliminate the original (faulty) transaction, instead, the revert transaction should happen, which will compensate for the original faulty action.
In the end, we will have the original balance and two events, one compensating another.

Out of routine application work, there are a lot of reasons to merge, split, update, remove streams of events, events, or even event data.
The most common reason is optimization. If the data in the Event Store becomes a historical artefact that does not tell anything about the current state of the system and won't be used for audit purposes, archive it and eventually hard delete it. It is just useless.

The Evolution

Evolution is change in the heritable characteristics of biological populations over successive generations. These characteristics are the expressions of genes that are passed on from parent to offspring during reproduction.
-- Wikipedia

Let's talk about evolution in the context of Event Sourcing. There is no such thing as a finished application. Systems do evolve with time. Most of the time it is either business requirements evolution or bugs that stimulate this process. Both of these occasions don't require an extra introduction. However, they will unavoidably impact events.

There are two ways how event can evolve:

the event might become a new version of itself
or become a new event (or set of new events).

What determines the direction of the change? When does an event evolve into a new version and when it evolves into a new event?
The event will evolve into a new incarnation (version) of itself when evolved requirement does not change the event's meaning, but rather schema. Hence a new version of an event must be convertible from the original one (old version). Therefore the name/type, which represents the essence of the event must not change.

If an event's meaning changed and one-to-one conversion is impossible, that's a sign to introduce a new event (or events) that carries new meaning.

A new version of an event must be convertible from the old version of the event. If not, it is not a new version of the event but rather a new event.
-- "Versioning in an Event Sourced System" Greg Young

We can use this as a rule of thumb: if you are struggling with a conversion of the old version of an event into a new one, most likely you are dealing with the new event, not with a new version.

Let's look at the example below.
Imagine there's a comment system where users can delete comments. Every time user deletes a comment new event is emitted

{
    "name": "comment-deleted",
    "comment-id": 1,
    "user-id": 33
}

Time passed and new requirement arrives. "All users must specify the reason for the deletion". Sounds reasonable, so from now on the event should look as follows...

{
    "name": "comment-deleted",
    "comment-id": 1,
    "user-id": 33,
    "reason": "I didn't like it"
}

This is a simple example of event evolution forced by requirement change. The meaning of the event did not change. However, the payload did.

The Breaking Change

We mentioned that event also represents a contract. The contract between the event store and the system/application.
If we look at events through this lense the biggest driver to introduce a new version would be a breaking change in the existing event schema. A breaking change is any non-backward compatible change. In other words, something will break if we change the event's schema this way. We'll get back to this topic in more detail later.

In real life, events do not always evolve from one version to another by expansion. Sometimes they shrink.
When a new version of an event loses some of the payload without gaining, it is not a breaking change. Hence we don't really need a new version of an event, we can just ignore the data that we don't need.

I use the following table as a decision navigator.

Scenario	Action	Do we need a new version?
all data exists on the old version and required in the new version	should be copied	no
data exists on the old version, but not all of it required in the new version	ignore obsolete data	no
a new version has some new fields, but they are nullable	set null	no
a new version has some new fields, but they are not nullable	conversion required	yes
data exists on the old version and on the new, but the schema of data changed (e.g. type changed or field name)	conversion required	yes

Long story short. Unless it is a breaking change, there's no necessity for a new version of the event. Unless you want to capture all schema permutations.

Where's the catch? 🎣

With the new event, it is pretty straightforward. Follow the regular routine, how you'd introduce a new event on any other occasion.

With the new version, it is a bit more tricky. Once you introduced a new version, now you have two events that carry different data but have the same meaning. Moreover you probably already accumulated some old events in your event store. Looks ambiguous, isn't it?
The original reason behind the introduction of a new version of the event is a new/evolved requirement (or bug). The same reason makes the old version of the event obsolete.

What does it mean from the system perspective? The system should only see a single version of the event, the latest one.
From now on, the new event version is the only legit representation. Any old version should be simply invisible. It's like it never existed before.

Getting back to one of our initial claims: the event store is immutable. And it is not a problem when we introduce a new event or deprecate an old event. But what should happen when we introduce a new version of the event?

Let's try to visualize what we've just said.
Imagine there's an event stream. Where different color represents different events. It has been going on from 2:00 o'clock. Somewhere between 3:00 and 4:00 we introduced a new version of the light blueish event (v2).

On the left is reality, what we will end up within the Event Store. On the right is what our system should expect. Notice the difference? On the right-side, all events are of the latest version.

Distillation

Event evolution is a natural process of any active event-sourced application.
The event might evolve into a new version of itself or into a new event. You can determine the direction by validating whether you can easily convert an old event into a new one. If you do, you are dealing with a new version, if not a new event...
The main driver behind the event's version-to-version evolution is a breaking change in the event's payload schema. Use a table from the above to determine whether you are dealing with the one.
Last, but not least, the system must "see" only a single version of the event, the latest one.

Further down we will focus on the version-to-version evolution and possible ways of dealing with it.

Event Versioning

First and foremost let's find a good data structure to describe the event version, given what we know so far about it.
Let's go over key aspects of versioning.

old version must be convertible to the new one;
we don't have any limits on the number of versions, our system might well have any arbitrary number of versions for any particular event;
given our system "forgets" about old versions we can only operate with the current version and future version (the one we are introducing) at any given point in time;

What if we will represent every version of an event as a node. And the ability to convert the old version into the new one as a directional connection. Boom and we are getting a Linked List.
Let's try to visualize it really quick.

Looks very nice and elegant. Responsibility boundaries are well defined. Any given version will know how to convert itself to the next one and only the next one. And the tail will always represent the latest version. The one that our system is actually interested in.

Conversion/Migration

Given we came up with a linked list to describe the relationship between versions, the conversion from any given version to the next one and ultimately to the latest becomes very trivial. All we need is traversal from the current version to the tail. And tail will always be the last available version.

When?

Seems like we have a good way forward. We have a way to define a version, we have a good understanding of how to get from any given version to the last one. So when should we do it? And the answer is "it depends..."

It depends on whether you can afford to have a down-time, on the average active lifetime of arbitrary stream in your system, and your snapshotting strategy.

I have only my own experience at my disposal so I'll use it to define the median case.

In-store migration

This is when you update data in the event store itself. I don't like this approach as it kinda violates the integrity of the data. You are mutating the Holy Grail of the Event Sourcing... Events.

Additionally performing something like blue-green deployment or canary deployment without downtime is possible, but might appear painful :). Keep in mind you will have to compensate accumulated delta between releases.

Out of the store migration

More common and in my opinion more reasonable way of dealing with it is covert on demand. This means we will leave the event store untouched, instead, our state reconstitution process will be responsible for event conversion.

Let's get look at the reality vs. expectation example, but now with conversion in-between.

It is particularly useful when the active stream lifetime is not very long and you know that ultimately every stream will be either archived or serve only for audit purposes. It means that eventually your Event Store will be constituted of streams with predominantly new versions of events. And those with old events will get less and less usage.

On the other hand, if your streams have a fairly long active lifetime you probably will employ snapshotting strategy at some point in time. This will reduce the usage of old events as they will be processed during snapshot construction. However, it will require us to re-build the snapshot whenever we introduce a new version of the event as it will impact the snapshot.

Bottom Line _______

Applications evolve and unavoidably impact the shape of the data in the data storage. If you are using event sourcing, it means your shape of events will be evolving making some events in the event store stale.

Generally speaking, an event has two main responsibility:

signalize about a change that has happened
and carry information to enrich the value of the signal

If evolution changes what the event should signalize about it is a new event, if it changes underlying payload schema it is a new version of the event.

Event versioning is nicely fitted into the Linked List data structure.

The system uses only the latest versions of events. And to facilitate it we have two ways of dealing with old events. The in-store and out-of-store migration/conversion. I'm personally in favor of the last one, but presumably, there might be better cases for the first one.

Keep in mind that there are other strategies for dealing with event versioning, such as double push, etc. I think they are rather more applicable to asynchronous services than to event-sourced systems. But don't take my word for it, there's no silver bullet in the software engineering ;)

Server-side Redux. Part III. The Code.

Valerii Udodov — Mon, 14 Jun 2021 05:46:01 +0000

The State Management Goes Wild

his is the final article of the series where we explore Redux and its boundaries. In the previous articles, we first dived into the main principles of the Redux, then we tried to move things around and conceptually move Redux from one side to another.

This article is all about hands-on experience, and by the end of it, we will have a working application that will follow the design we settled before.

Enough talking let's get down to business.

Feel free to pull complete application code from Github.

Given

Let's quickly go over the design. The main connection points are Redux and React, they will talk via WebSocket. React components will dispatch actions, those will be processed by Redux, which in its order will push the updated state back to the React.

Client-side

Well, you know it, it will be React. We will try to consume create-react-script to quickly set up everything we need and don't waste time configuring Webpack, Babel and other 1001 libraries we need to make those two work together.

Server-side

Since Redux is a JavaScript library, it makes sense to take a JavaScript-based backend environment. You got it again, it will be NodeJS.

ℹ️ At the time I'm writing this article NodeJS just included experimental support for ECMAScript modules.

We will configure it globally for the whole back-end application with setting "type": "module" in the root of the server-side package.json.

Note: This feature is available starting from version 13, so try to run node -v in your terminal, and if it is lower make sure to update it.

We spoke about the mythical immutability by convention, mythical because it is not a real thing 🦄🙃. Therefore we will use immutable.js to keep our state truly immutable.

In between

We will be using WebSocket as a communication protocol between client and server. Probably the most popular library for that matter is socket.io.

We figured out all the main tech choices. Let's look at how dependencies sections from both package.json files will look alike

back-end:

"dependencies": {
    "immutable": "^4.0.0-rc.12",
    "redux": "^4.0.5",
    "socket.io": "^2.3.0"
  }

front-end:

"dependencies": {
    "react": "^16.13.0",
    "react-dom": "^16.13.0",
    "react-scripts": "0.9.x",
    "socket.io-client": "^2.3.0"
  }

Plan

We will kick things off by implementing a Tic Tac Toe game in pure React. It will be based on the React tutorial. The first iteration won't support a multi-browser multiplayer. Two players will be able to play, but in the same browser window, since the state will be local for the browser window.

After we will add back-end with Redux Store and move logic from the front-end components to back-end reducing functions. With all the logic gone, we will do a bit of housekeeping and make sure that all components are stateless/pure.

And finally, we will connect front-end and back-end with socket.io and enjoy a multi-browser multiplayer 🎮.

Step I. Pure React Implementation

TLDR; You can find complete code for this step here.

This example is based on the react intro tutorial, so if you'd like to go through the step-by-step process, feel free to jump there. We'll go through the most important bits here.

The whole application is assembled from three main components, which are Game, Board, and Square. As you can imagine the Game contains one Board and the Board contains nine Square's. The state floats from the root Game component through the Board props down to the Square's props.

Each Square is a pure component, it knows how to render itself based on the incoming props/data. Concept is very similar to pure functions. As a matter of fact, some components are pure functions.

// .\front-end\index.js

function Square(props) {
  return (
    <button className="square" onClick={props.onClick}>
      {props.value}
    </button>
  );
}

The Board is also pure component, it knows how to render squares and pass state down there.

// .\front-end\index.js

class Board extends React.Component {
  renderSquare(i) {
    return (
      <Square 
        value={this.props.squares[i]} 
        onClick={() => this.props.onClick(i)}
      />
    );
  }

  render() {
    return (
      <div>
        <div className="board-row">
          {this.renderSquare(0)}
          /* ... render 8 more squares */
        </div>
      </div>
    );
  }
}

And finally the state orchestrator, the Game component. It holds the state, it calculates the winner, it defines what will happen, when user clicks on the square.

// .\front-end\index.js

class Game extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      history: [{
        squares: Array(9).fill(null),
      }],
      stepNumber: 0,
      xIsNext: true,
    };
  }

  jumpTo(step) {
    /* jump to step */
  }

  reset() {
    /* reset */
  }

  handleClick(i) {
    /* handle click on the square */
  }

  render() {
    /* check if we have a winner and update the history */

    return (
      <div className="game">
        <div className="game-board">
          <Board
            squares={current.squares}
            onClick={(i) => this.handleClick(i)}
          />
        </div>
      </div>
    );
  }
}

Step II. Adding Server-Side and Redux

TLDR; You can find complete code for this step here

Well, I guess this is it, the moment we've all been waiting for. The moment when we will marry the Redux and NodeJS app 🙌.

The State 🌳

We will follow the Redux best practices and first define how the state tree will look alike. We will base it on the state model which we used in the previous step.

On the first level, we have

the turn indicator "is X next?", which determines whether it is X or O turn;
the step #, which is essentially a move counter, showing current step
the winner, true if the winner was identified
the history, snapshot of Squares on each move

Each node in the History represents a collection of Squares, each Square has an index and one of three states "_", "X" and "O".

Let's try to model how initial state might look like

const INITIAL_STATE = {
      history: [{
        squares: Array(9).fill(null),
      }],
      stepNumber: 0,
      xIsNext: true,
    };
  }

In the first article, we spoke about immutability and particularly about immutable.js. This is the place we are going to utilize it. We will mostly use List and Map objects, for the sake of this example. Now let's compare to how the state initialization will look like after we applied immutable.js

const INITIAL_STATE = Map({
  history: List([ 
    Map({
      squares: List([
        null, null, null,
        null, null, null,
        null, null, null
      ]),
  })]),
  stepNumber: 0,
  xIsNext: true,
  winner: false
});

A bit more code, yet it is a fair trade, taking into account that all operations will automatically produce a new immutable instance of the state in the most efficient manner.

Something like const newState = state.set('winner', true); will produce new state object. How cool is that?

Actions

Now that we know the shape of the state, we can define allowed operations. And no surprises here either. We will re-use the same operations we used in the front-end and transfer them into actions. Hence there will be three main actions

PERFORM_MOVE to perform a move, action will carry a box index that move was made for
JUMP_TO_STEP to enable time-traveling, this action will carry step number to which the user wants to jump to
RESET resets the whole game progress to the initial empty board

Reducers

We have actions, we have a state...

Now we need to connect them.

Before we start it is worth mentioning that Reducer is responsible for setting the initial state, we will use the initial state we defined before. And just set it if nothing was passed (this is handled for us)

// .\back-end\src\reducer.js

const INITIAL_STATE = Map({
  history: List([ 
    Map({
      squares: List([
        null, null, null,
        null, null, null,
        null, null, null
      ]),
  })]),
  stepNumber: 0,
  xIsNext: true,
  winner: false
});

...

export default function reducer(state = INITIAL_STATE, action) {
  switch (action.type) {
  case 'PERFORM_MOVE':
    /* todo */

  case 'JUMP_TO_STEP':
    /* todo */

  case 'RESET':
    /* todo */
  }

  return state;
}

Let's go over reducing functions one by one.

PREFORM_MOVE On every move we will first check if the move is legit, meaning that we might already have a winner and the game is over or the user tries to hit filled box. If any of these happens we will return the same state with no modifications.

Checks are done, the move is legit, we perform actual move depending on whether it should be "X" or "O". After we made a move we need to check whether it was a winning move or not.

And finally update state.

// .\back-end\src\reducer.js

function performMove(state, boxIndex){
  const history = state.get('history');
  const current = history.last();
  let squares = current.get('squares');
  let winner = state.get('winner');

  if(winner || squares.get(boxIndex)) {
    return state;
  }

  squares = squares.set(boxIndex, state.get('xIsNext') ? 'X' : 'O');

  winner = calculateWinner(squares);

  return state
    .set('history', state
      .get('history')
      .push(Map({ squares: squares }))
    )
    .set('stepNumber', history.size)
    .set('xIsNext', !state.get('xIsNext'))
    .set('winner', winner);
}

JUMP_TO_STEP To perform a time-travel we need to reverse the history to the step we want to move to and update current step number with a new value. And of course return new state.

// .\back-end\src\reducer.js

function jumpToStep(state, step){
  return state
    .set('history', state.get('history').take(step + 1))
    .set('stepNumber', step)
    .set('xIsNext', (step % 2) === 0)
    .set('winner', false);
}

RESET Reset is pretty much like a JUMP_TO_STEP, with only difference that we are jumping back to the very first step. After we are done, we return a new state.

// .\back-end\src\reducer.js

function reset(state){
  return state
    .set('history', state.get('history').take(1))
    .set('stepNumber', 0)
    .set('xIsNext', true)
    .set('winner', false);
}

Now we constructed all necessary reducing functions, we can put together the reducer.

// .\back-end\src\reducer.js

export default function reducer(state = INITIAL_STATE, action) {
  switch (action.type) {
  case 'PERFORM_MOVE':
    return performMove(state, action.boxIndex);

  case 'JUMP_TO_STEP':
    return jumpToStep(state, action.step);

  case 'RESET':
    return reset(state);
  }

  return state;
}

Create Store

We have everything we need and it is time to create a new redux store based on the freshly created reducer

// .\back-end\index.js

import redux from 'redux';
import server from './src/server.js';
import reducer from './src/reducer.js';

const store = redux.createStore(reducer);
server.startServer(store);

Step III. Connecting client and server

TLDR; You can find complete code for this step here.

This is the last step. It is mostly about connecting two points, client-server and deduplicate the logic.

Connection

First, we will configure the connection on both ends. Before performing any configuration let's figure out how does socket.io works.

The first-class citizens in the socket.io library are events. You can emit or subscribe to event on both sides.

Which kind of events we need? I think we already have an answer to this question. Let's get back to our design diagram.

We need to push state from the server to clients and actions from the clients to the server. Translating it to socket.io language we need to have a state-changed event that we will emit on the server and subscribe to on the client. And we need to have an action event that we will emit on the client and subscribe to it on the server.

So far so good, the only bit missing is the connection. We need to pass the current state to any new socket connection to our server. Luckily this is built-in functionality. We have a connection event that will be triggered every time a new connection appears. So all we need is subscribe to it.

This should do for our design and data transition needs.

Now let's do actual configuration. We'll start with the server. First, we will subscribe to any new connection, after connection happens we immediately emit a state-change event on that socket to transfer the latest state from the Redux Store. Then we will also subscribe to an action event from the same socket and once an event will arrive we will dispatch the whole object into the Redux Store. That'll provide a complete setup for the new socket connection.

To maintain the rest of the connections up to date we will subscribe to the Redux Store changes, using Listener callback. Every time the change will appear we will broadcast a state-change event to all connected sockets

// ..\back-end\src\server.js

function(store) {
    console.log("Let the Game begin");

    const io = new Server().attach(8090);

    store.subscribe(
      () => io.emit('state-change', store.getState().toJS())
    );

    io.on('connection', (socket) => {
      console.log('New Connection');

      socket.emit('state-change', store.getState().toJS());
      socket.on('action', store.dispatch.bind(store));
    });
  }

Moving to the client-side, first thing we need to set up a way to receive fresh state. We will subscribe to the state-changed event for that matter and pass received state execute the ReactDOM.render(<Game gameState={newState} />, ...);. Don't worry, calling ReactDOM.render() multiple times, absolutely fine from the performance perspective, it will have the same performance implication as calling setState inside the component.

Finally, we define the dispatch callback which takes action object as a parameter and emit an action event through the socket connection.

// .\front-end\index.js

const socket = io("http://localhost:8090");
socket.on('state-change', state =>
  ReactDOM.render(
    <Game 
      dispatch={(action) => socket.emit('action', action)}
      gameState={state}
    />,
    document.getElementById('root')
  )
);

That's it, that'll be our communication framework. Now we need to pull the right string in the right moment.

Cleanup

The logic moved to the back-end reducing functions. This fact allows us to make our front-end completely stateless and pure. All our react components are now only data-containers. The state itself and the interaction rules (reducing functions) are stored on the back-end.

If we look back on the data-transition diagram we can notice that in reality Square and Board components were already pure, now it is just a matter of making the root component, Game pure as well.

After a bit of refactoring the code will look as following

// .\front-end\index.js

/* Square and Board were not changed */

class Game extends React.PureComponent {

  jumpTo(step) {
    this.props.dispatch({type: 'JUMP_TO_STEP', step});
  }

  reset() {
    this.props.dispatch({type: 'RESET'});
  }

  handleClick(boxIndex) {
    this.props.dispatch({type: 'PERFORM_MOVE', boxIndex: boxIndex})
  }

  render() {
    const { history, stepNumber, xIsNext, winner } = this.props.gameState
    const current = history[stepNumber];
    const status = winner
      ? 'Winner: ' + winner
      : 'Next player: ' + (xIsNext ? 'X' : 'O');

      const moves = history.map((step, move) => {
        /* time travelling */
      });

    return (
      <div className="game">
        <div className="game-board">
          <Board
            squares={current.squares}
            onClick={(i) => this.handleClick(i)}
          />
        </div>
        <div className="game-info">
        <div><button onClick={() => this.reset()}>Reset the Game</button></div>
        <div>{status}</div>
          <ol>{moves}</ol>
        </div>
      </div>
    );
  }
}

That's all folks

Please find the complete code example in my GitHub repo.

In a course of three articles, we have proposed a hypothesis, that Redux might be used as a state management tool on the back-end and distribute the state across multiple front-ends, we've built a design prototype to facilitate the experiment. And finally, we've built a proof of concept tic-tac-toe application that proved our design prototype hence proved that the hypothesis was correct.

There are multiple ways to optimize and improve this code example, we mentioned a few.

You are more than welcome to express your thoughts in a form of comments or commits.

Server-side Redux. Part II. The Design.

Valerii Udodov — Thu, 03 Jun 2021 05:02:05 +0000

The State Management Goes Wild

This is the second article of the series where we will try to find out if there’s a place for Redux on the other side of the fence.

Even though this series is base on the assumption that you are more or less familiar with what is Redux, don’t worry if not, as we covered all necessary concepts in the previous article. Take your time and make yourself comfortable with Redux.

Roots

In the previous article, we witnessed, how Redux can drag responsibility of being a source of truth for the state, manage its distribution and help multiple independent components stay in sync. A good example would be a scenario that forced Facebook to come up with something like Flux in the first place: a large facebook message view, where you can have three independent components depend on whether you read a message or not. Main view, compact view in the right corner and icon-counters on the top.

With the help of Redux, the state distribution in this sort of application will look as following

Front-end Redux state distribution

Moving things around

The Whys

Now, finally, we are reaching the important point of this series, where we will answer the question: why would the one possibly want to use Redux somewhere away from the front-end? 🤯

Pretty much for the same reason why you would use it in the front-end... Single source of truth for the state, its distribution, and centralized management. Even though the idea might make sense, the scenario is not very clear yet.

The Scenario

Let's get back to the Facebook case study first. The root cause of the problem there was the data synchronization between components without a direct connection. The more dependent nodes appeared, the more convoluted distribution tree became. Complexity was growing exponentially.

Imagine replacing components with front-ends. Front-ends that are simultaneously working and interacting with the same state. It might be the same client-side application in different browser windows as well as absolutely different front-end applications. Main criterion: they need to interact with the same state.

The following diagram represents a conceptual state distribution graph for such an application. The left side and right side are separate React front-ends with a Redux-equipped server in the middle. One of the right-side front-end components performs a change in the state (green circle), change (action) delivered to the server where it is dispatched to the Redux Store. The reducing function performs all necessary state changes and finally, the new state got delivered back to the front-ends. In this case, we are using the top-level component distribution model in both front-ends to deliver the state to the dependent components (yellow circles).

Back-end Redux state distribution

The Hows

So far so good, it makes sense and everything seems to logically fit. However, the vague point here is state exchange.

In a regular React application, everything is happening inside the browser in the same JavaScript runtime, allowing real-time bidirectional communication between Redux and React. Moving Redux to the back-end introduces physical segregation between the React root component and Redux Store. The black dashed line on the diagram above illustrates the physical segregation of those two. To get Redux to work as we expect it to, we must make the communication as seamless as it is in its native habitat.

The Challenge

The first thing that comes to my mind when I look at the border between the front-end and back-end is HTTP. But will it do the job here? To answer this question let's first figure out what problem we are trying to solve.

We need to establish real-time, bidirectional communication between the Redux Store and root node of each and every React front-end. It means that both the client and server should have the ability to push information equally.

HTTP vs WebSocket

This topic on its own deserves a separate article. To save some time and not lose the focus, I'll say that HTTP out of the box supports server-push approach with Server-Sent Events (SSE) and client JS has built-in support for it, thanks to HTML5. On top of it, HTTP/2 can utilize a single TCP connection to deliver multiple messages in both directions, making it a full-duplex, bidirectional connection.

However moving forward I chose WebSocket as a protocol that was specifically built for this sort of communication, it does not bring unnecessary data overhead, that HTTP brings (e.g. Headers). Additionally, WebSocket is a more generally known way of solving this sort of task.

Now all what is left is to connect right dots with right lines.

Client

As we discussed, we will take the root-node data distribution approach. This means that the root node will receive the whole state and propagate it all the way down through the props. It should happen every time the "push" event arrives from the server.

Now we also need to initiate state updates from the client. We decided on the delivery mechanism, but we did not decide on what we will deliver. Actually Redux already solved this problem for us. As we know Redux uses actions to operate on its state tree. There's no reason for us to change that, even though we increased the distance slightly. All we need to do is to define a dispatch(action) callback which will push actions back to the server. So that any component in the tree can push actions to the server (remember the green circle).

Server

To consume "push" events on the client we first need to produce them. Every time a new state is produced by the reducing function, the server must initiate a "push" event. And finally, we need to handle incoming actions from the client.

To push state we can use Redux listener callbacks, which will be executed on every attempt to change state, disregards whether it was changed or not. At any point in time, we can request a new state and utilize WebSocket to deliver it to the client.

Process actions is dead simple. Once we receive an action, we directly dispatch it with Redux Store.

Final Design

This is it. We have everything on its places, we have a way to deliver actions to the Redux Store as well as a subscription mechanism to update all front-ends on every state change.

The final design looks as following

What's next?

Optimization

You might think that sending state every time to all the clients is not the most efficient approach. And you are right. But is it a problem? Wether it is or not, it really depends how big is your state tree. If it is reasonably small, I would not bother. If it is big enough and you are worried about some clients' latency, you can decrease the data noise, e.g. by sending only state delta.

Redux everywhere

As another possible design iteration, nothing stops you from having Redux on the front-end if you feel like it is required, this will change your state distribution diagram to something like this

The state source of truth still stays on the server, but client-server communication happening between server-side Redux and client-side Redux and now client-side state propagation lays on the shoulders of the client-side Redux.

Conclusion

Redux on the backend is not a magical unicorn, not just a theory and we will prove it in practice.

This kind of architecture is not for the "daily use", but it is not just for fun either. It will work very well in most of the real-time applications, particularly for things like chat apps or online games.

It absolutely agnostic to the front-end complexity and can work well with simple state-waterfall applications as well as complex front-ends with Redux as a state manager.

Anyhow, it is time to get hands dirty and try discussed architecture in practice.

Server-side Redux. Part I. The Redux.

Valerii Udodov — Thu, 13 May 2021 09:58:26 +0000

The State Management Goes Wild

This is the first article of the series where we will try to find out if there's a place for the Redux on the other side of the fence.

Even though this series is base on the assumption that you are more or less familiar with the Redux, don't worry if not, as we will go over necessary concepts first. And this is what this article is about...

Once we are confident with the Redux as a React state manager, we will be exploring how we can use it as a back-end state management and state distribution tool and gradually build the conceptual design. Last, but not least we will get our hands dirty and build application with Redux on the back-end.

If you are super-comfortable with Redux, feel free to start with the desert.

Very brief History

Redux appeared as a proof of concept during preparation for the React Europe conference, back in 2015.

I was trying to make a proof of concept of Flux where I could change the logic. And it would let me time travel. And it would let me reapply the future actions on the code change.

Dan Abramov

Very soon Redux got huge popularity in the front-end community, it is simple, easy to follow library for the state management. Redux makes a lot of complicated tasks trivial.

State Management

To understand what Redux can bring to the table we'll start by looking at what pure React can offer first.

React doesn't come with the Redux out of the box, and there's a reason for that. Most of the time you probably won't need it. There is a React way of managing state distribution and state dependency. In React you can propagate state up to the top-level components and make it in charge of distribution and dependency management. The state flow is single-directional and easy to manage.

Think of the React application as of simple water-filter. Where the state is water, each layer is a component. We pure the water in the bottle, water passes through each layer consistently, each layer takes whatever it has to take and letting the water flow to the next layer.

I hope the idea is clear, but why and when do we need Redux?

You'll know when you need Flux. If you aren't sure if you need it, you don't need it.

-- Pete Hunt (one of the first React contributors)

We can apply the same rule to the Redux. If you aren't sure if you need it, you don't need it.

Once you have a lot of data moving here and there and top-level React component state is not enough to distribute it. It is time...

Redux allows you to move out the "state source of truth" from the top-level component into a separate object. And the only way to change the current state is to interact with this object. This object called Store.

Immutability

Understanding immutability is very important, for proceeding with the Redux. Because in Redux state is immutable 🌳.

The idea behind the immutable data is simple, you cannot modify it. Like natural numbers. 2 is a natural number and whatever you do, it won't change 2. You can operate on it and, let's say, add 3 to it, but the result will be another natural number, 5. 5 is another natural number.

Why immutable data is good? Because you can pass it around and not worry it will be changed in a way you don't expect it to. It becomes even handier in the distributed multi-threaded environment, but that's another discussion.

Immutable by convention

Immutable data is a key aspect of any Redux-based architecture. Even though it is a key aspect, there's no real enforcement, it is so-called immutability by convention. I think immutability by convention is not a thing… If an object can be mutated, it will be mutated, just a matter of time… I highly recommend stepping away from the immutability by convention once the data-state tracing becomes uncomfortable.

JavaScript has some data structures provided out of the box. There're an Object.freeze() and const which kinda allow you to have some immutability. Yet using them is not very efficient from the memory perspective, because every operation will require you to copy your data from one place to another. Quite expensive, taking into account the fact that every copy will require extra memory allocation, copying and garbage collection.

To keep things error-prone we'll need something that will enforce immutability and manage memory efficiently. The immutable.js does exactly that. It is a library with a collection of immutable data structures. Immutable JS uses persistent vectors to perform insertions, merges, etc. It removes necessity in copying and caching of the data.

Pure functions

Mathematical functions

The immutable data is a key aspect of the Redux design and we need to respect it whether we use it in a conventional manner or by enforcement.

But how do we deal with immutable data in a way that we can still benefit from it?

Let's get back to the natural numbers example, we agreed that natural numbers are immutable, and we tried to add 2 and 3, which resulted in 5. This can be written like 2 + 3 = 5. To make it more generic we can describe it as the mathematical function, like this f(a, b) = a + b. It is predictable, it does not introduce any side-effects, for 2 and 3 it will always return 5.

Pure functions are mathematical functions. And pure functions work very well with immutable data, there's even a whole programming paradigm that takes those two as its foundational platform, you might know it as functional programming.

We spoke about the state and its immutable nature in the Redux. We also spoke about the Store and how it secures a state from any unauthorised impact. And finally, we found that pure functions are a very convenient way to operate on immutable data, which allows keeping transparency and predictability in place.

Reducing functions

The only way Redux Store allows to operate on its state 🌳is with actions. Those are special "instruction" objects, very similar to what Commands are in CQRS or Events in Event Sourcing. They define an action/operation that intended to be applied to the state and carrying a necessary payload. Add an item to the basket is an action where the item you want to add is a payload.

Redux uses a special type of high-order functions to process actions, the reducing function. The reducing functions is not a new concept in the JavaScript, the array.reduce(reducerCallback, initialValue) function reduces an array to a single value. It uses a special user-defined reducer callback which is executed recursively.

(accumulator, currentValue) => nextAccumulator

Similarly, Redux Store will use a special user-defined reducer callback which will be executed synchronously when an action will be dispatched. As you might guess, reducer must be a pure function. It takes a state and an action and calculates the next state.

(state, action) => nextState

Interception and Subscription

Redux uses Middleware pattern to provide integration points before and after an action is dispatched. You can stack multiple middleware functions. You are in charge of whether the execution chain continues or not. You can control it with the next(action) function.

Another integration point is Redux Listeners, which located closer to reducer callback than middleware. Listener functions are executed one by one right after reducer. Listeners don't have any control over execution flow.

Keep in mind, it is simple

Redux doesn't force you, it empowers you by providing a framework. You can have multiple stores, mutate state, create side-effects in your reducing functions and finally, you don't have to use it as a state source of truth at all.

Redux is not rocket science 🚀, it is just a Flux pattern implementation and if we strip all the error checks, comments extension points from the createStore.ts it will fit into 20-30 lines of JavaScript code.

function createStore(reducer) {
    var state;
    var listeners = []

    function getState() {
        return state
    }

    function subscribe(listener) {
        listeners.push(listener)

        return function unsubscribe() {
            var index = listeners.indexOf(listener)
            listeners.splice(index, 1)
        }
    }

    function dispatch(action) {
        state = reducer(state, action)
        listeners.forEach(listener => listener())
    }

    dispatch({})

    return { dispatch, subscribe, getState }
}

Few more things are happening in the Redux and it slightly differs from the Flux, however, we won't go in too deep. We covered just enough to move forward to the next chapter and design the use-case for the Redux on the backend.