DEV Community: Adam Warski

What is Dependency Injection?

Adam Warski — Tue, 13 Apr 2021 18:58:47 +0000

"Dependency Injection is just passing parameters", "Spring is necessary to do Dependency Injection properly", "Dependency Injection is a way to escape from functional programming": these are just some of the quotes circulating about Dependency Injection. As for a technical pattern, it seems quite controversial. Is there any substance in Dependency Injection (DI)? Is this something you should be using in your application? Or maybe using DI makes you a bad programmer?

These are all good questions! However, what's often missing from discussions is an accurate description of what Dependency Injection exactly is. A good, precise definition might stop many arguments before they begin.

The classic article by Martin Fowler is a good start, however it's quite dated and although quite long, does not give an exact definition. Moreover, our usage of Object Orientation (OO) has evolved since 2004, and is increasingly blended with Functional Programming (FP), hence an update might be in order. Popular answers on Stack Overflow and the Wikipedia entry provide reasonable benefits on why to consider using DI in an application, but fail to succinctly capture the main goals of the pattern, or as many critics of DI point out, describe nothing else than passing a parameter to a function.

Let's try to clear things up!

The classes and objects that we create and use in our applications tend to fall in two categories:

Service objects. These are "bags of methods" or "sets of functions", and are used to modularize the code base. Good examples of service objects might be UserRepository, EmailSender, ProfileManager, etc.
Data objects, either pure data or data combined with behavior ("proper" OO). Examples include Product, Invoice, UserVisitor, …

Both types of objects are created at different times in the application and used in different ways.

Service objects tend to be created once at the start of the application. They don't change during the execution of the program. In other words, service objects are the modules from which your application logic is composed. Services might depend on one another, forming a dependency graph. Moreover, specific implementations of services might be interchangeable, depending on configuration, environment, command-line options, etc.

The crucial property of the service/module graph is that it is created statically. Only when the graph of services is wired, the application is usually ready to serve user requests. Hence the service objects/modules are static and global, as well as typically stateless. They only contain methods, without any (mutable) data, except maybe for configuration and pre-computed values. There are exceptions as well, such as cache services.

Data objects, on the other hand, are created dynamically, either in response to user interaction, API invocation, scheduled tasks, etc. They usually have a short, local lifespan. They carry and manipulate the data that the application processes. They might combine data and behavior, or be pure, "thin", data structures.

Summing up, we have the following properties of service vs data objects:

static — dynamic
global — local
stateless — stateful

But we were supposed to talk about dependency injection, where is it then?

Dependency Injection is the process of creating the static, stateless graph of service objects, where each service is parametrised by its dependencies.

That's it! This definition has several implications:

First of all, a direct consequence is that DI doesn't mandate the use of any framework. It's perfectly feasible to do dependency injection "by hand", using just constructors. Whether doing manual dependency injection, compile-time dependency injection, or run-time DI, is an implementation detail.

Frameworks are of course allowed as well. For example, Spring is a DI framework, which uses annotations, xml and reflection to create the static service (component) graph, so it definitely matches the definition. Whether it make sense to sacrifice control over how you create objects and rely on runtime reflection is exchange for a little less code, is another debate.

Secondly, by requiring that the services are parametrised by their dependencies, we mandate inversion of control (IoC). This makes the dependencies interchangeable (e.g. for testing, or by configuration). Moreover, it's up to the wiring code (the code that creates the static object graph) to decide which specific implementation is used to satisfy a dependency; this responsibility is outside of the control of the service; the dependencies are provided externally by the DI process.
Dependency injection isn't just passing function parameters. Passing function parameters can be used to implement DI, but what matters here is why we are passing these parameters in the first place: to create the static graph of modules at the start of the application. Parameter passing is an implementation detail.
As I've also argued before, DI is different than other approaches for managing dependencies, such as the reader monad. The reader monad is a mechanism that is complementary to dependency injection, as it makes the dependencies explicit, while with DI the dependency graph is created upfront and hides the dependencies from normal method/function calls. Both mechanisms are useful for different purposes.
Finally, DI and FP are orthogonal, and DI is a perfectly valid and useful concept when doing Functional Programming. The functions that are used in FP also often need to be grouped in "modules", which is another way of saying that functions are grouped as methods into classes; they need to be parametrised by other sets of functions (other modules); and they need to be substituted depending on configuration, or in tests.

Nothing in the definition of DI forces us to use mutable data, side-effects, frameworks, impure functions etc.

To sum up, is DI machinery created to avoid FP constructs? No! It can use that machinery, for a clearly stated goal: creating the (usually static) module graph on application startup. It's not a mandatory part of every application: it's definitely viable to write good, readable code without it. But as the codebase grows, modularising the code and adding a startup step which wires all of the modules can improve the readability, explorability and maintainability of the project.

Starting with Scala 3 macros: a short tutorial

Adam Warski — Fri, 09 Apr 2021 13:58:17 +0000

Scala 3, also known by its development name Dotty, is expected to ship by the end of April 2021. One of its flagship features is principled metaprogramming. This includes macros — compile-time code generation.

Macros have been pioneered through an experimental API since Scala 2.10. Even though the API was experimental, macros have become a useful tool, leveraged by a number of libraries. Scala is a flexible and scalable language; still, macros allow to further reduce boilerplate code in a number of use-cases.

Given their popularity, it doesn't come as a surprise that the next major revision of the Scala language keeps metaprogramming capabilities, however in an improved form. The new approach is no longer experimental, and draws from the experiences from previous macros implementation.

At the code level, Scala 3 macros are unfortunately quite different from the previous version; however, this mostly affects library code, as that's where macros were predominantly used.

The scope of metaprogramming in Dotty / Scala 3 is also different from what we've seen in Scala 2. In some areas it is broader, in some — more constrained. For example, Scala 3 brings extensive inlining support. On the other hand, macro annotations are no longer there.

A simple macro

Let's see how we can start developing a simple macro for Scala 3! I did a similar tutorial for the Scala 2.10 macros, 8 years ago! Back then, we were writing a macro which improves on println-debugging.

Turns out, 8 years later, println-debugging is still one of the main debugging methods that I'm using. Quite often, we want to print some message and labeled values, for example:

println(
  s"Funds transferred, from = $from, to = $to, amount = $amount")

It would be nice if we didn't have to duplicate the names of the values used. Our goal is to write a macro which will automatically print the value labels. The syntax that we'd like to achieve is as follows:

debug("Funds transferred", from, to, amount)

Why do we need a macro here? We need to access the abstract syntax tree (AST) of our code, so that we can find out what the names are. Let's see how we can implement the macro step-by-step. All of the code is available on GitHub.

Project setup

Each project starts with a build; same here, we'll be using sbt (version 1.5.0), but any other tool which supports Scala3/Dotty can be used as well.

The only property that we need to specify in build.sbt is the Scala version:

scalaVersion := "3.0.0-RC1"

Once we have that, we can import the project into IntelliJ or Metals.

Hello, world!

We'll be working with two source files. First, Debug.scala is going to be where the debug macro will be implemented. Second, Test.scala will be where we'll be testing the code we've written. We need two separate files, as these need to be compiled separately by the compiler: we can't use code-generating code (the macro) before it has been compiled itself!

Let's start with an even simpler task: writing code which will generate a println("Hello, world!") when invoked. This is quite trivial:

object Debug:
  inline def hello(): Unit = println("Hello, world!")

object Test extends App:
  import Debug._
  hello()

Did we actually write a macro? Not really. Instead, we've taken advantage of a new Scala 3 / Dotty metaprogramming feature: inlining. Notice that the hello method is prefixed with the inline modifier. This instructs the compiler (and it's not only a suggestion — but a requirement), that upon compilation, the method body should be inlined at the call-site.

Hence, when we compile the above and inspect the bytecode, we won't see a hello() invocation in our Test application. Instead, the bytecode will contain directly println("Hello, world!").

In a way, inlining as described above is a way to do static metaprogramming — the code is generated, but basing on statically available information, without any computation. Let's see how we can take it one step further, and do some dynamic metaprogramming.

Single-parameter debug

Our goal will now be to write a debugSingle method, which will expand a debugSingle(x) call into:

println("Value of x is " + x)

Inlining is no longer enough. We need to access the name (or code fragment) that is passed to our method — not its value. We start out similarly as before, with a method that should be inlined:

inline def debugSingle(expr: Any): Unit = ???

That's the method that the user will invoke. However, the implementation will need to operate on a representation of the parameter which gives access to information available at compile-time: the textual representation of the code, to generate the label.

Note that this is quite different from the run-time representation; at compile-time, we manipulate trees corresponding to expressions. At run-time, we manipulate values to which the expressions are evaluated.

The mechanism to convert between the compile-time and run-time representations is called quoting & splicing. When we quote a value (by prepending the expression with'), we get back the abstract syntax tree (AST; a value of type Expr[_]), representing the expression:

'expr: Expr[Any]

In case of Scala macros, the AST is our code represented as data, which we can inspect. Expr is the root type; each Scala construct corresponds to a subclass of this type. As these can be nested (e.g. an If expression has child expressions), our code can be represented as a tree.

When we splice a value using ${ }, we go back to the run-time land:

${anotherExpr: Expr[Any]}: Any

You can think of quoting as a function T => Expr[T], transforming code into an abstract syntax tree which can be manipulated at compile-time. Dually, splicing is a function Expr[T] => T, transforming an abstract syntax tree into code that will be compiled and evaluated at run-time, into a value of the given type.

A crucial property that is enforced by the compiler is the phase consistency principle. It makes sure that you can only access the AST during compile time (at run-time, this information is no longer available!), and that you are not trying to access the value of an expression when a macro is being invoked (as the values are only available at run-time).

The implementation of the debugSingle macro will operate on abstract syntax trees. Hence, its signature is:

def debugSingleImpl(expr: Expr[Any])(using Quotes): Expr[Unit]

Notice the **using** QuoteContext value: it is provided implicitly by the compiler, and allows e.g. to report error messages that might occur during macro invocation.

The debugSingleImpl method takes an AST representing the expression that's been passed in as a parameter. This can be a simple value reference (x), or anything more complex (e.g. x+y*2). It returns an AST — code represented as data, of type Expr[Unit]— which when evaluated, returns a unit (a side-effect).

Here's the implementation:

def debugSingleImpl(expr: Expr[Any])(using Quotes) = 
  '{ println("Value of " + ${Expr(expr.show)} + " is " + $expr) }

The outer operation is quoting ('{ ... }): converting code it contains (of any type T) to a value of type Expr[T]; that is, an abstract syntax tree — representing the code as data. For example, '{ println("Hello, world!") } would return a value of type Expr[Unit] (Unit as that's the type returned by println), which represents the AST corresponding to the invocation of println.

However, inside the code for which we are generating the AST, we want to embed some expressions, represented as data: the string literal corresponding to the name of the value (the label), and the expression which computes the value.

This first is done using expr.show. This will be evaluated at compile-time, and converts the AST of expr into a String: the textual representation of the code. We create an AST fragment — an expression which represents a constant string with the given value using Expr(expr.show), and finally we splice (embed) it into the code that we are generating.

The second is done by splicing the (unchanged) AST of expr into the generated code. Any code that is passed as a parameter to debugSingleImpl, will end up unchanged in the generated code. For example, calling debugSingle(x+y) will generate, at compile-time, the following:

println("Value of " + "x.+(y)" + " is " + (x+y))

One final task remains: calling debugSingleImpl from debugSingle. To do that, we need to quote the expr so that the AST is passed to the macro implementation (we can access that since the method is inlined), and splice the result, converting the AST back into code that will be compiled:

inline def debugSingle(expr: Any): Unit = ${debugSingleImpl('expr)}

Are we done? Not quite. We need to require that the compiler will inline any usages of the expr parameter, instead of creating a temporary value with its value; that would spoil our labels! This is done by adding inline to the parameter as well. Here's the whole implementation:

inline def debugSingle(inline expr: Any): Unit = 
  ${debugSingleImpl('expr)} 

private def debugSingleImpl(expr: Expr[Any])(
  using Quotes): Expr[Unit] = 
  '{ println("Value of " + ${Expr(expr.show)} + " is " + $expr) }

Multi-parameter debug

We can now improve our implementation so that it works with multiple parameters. Additionally, if a parameter is a string literal, we'd like to simply include it in the output, without the label.

First, let's define the user-facing method. We'll use varargs so that it can be called with multiple parameters:

inline def debug(inline exprs: Any*): Unit = ${debugImpl('exprs)}

The idea is the same: we have an inlined method which splices the result of a computation involving code represented as ASTs.

This follows the definition from the Dotty docs: a macro is an inline function that contains a splice operation outside an enclosing quote.

Varargs are represented as a sequence, hence the signature of the macro implementation is:

def debugImpl(exprs: Expr[Seq[Any]])(using Quotes): Expr[Unit]

In the implementation itself, we first have to inspect the passed exprs tree and verify if it corresponds to multiple parameters passed as varargs. This can be done with pattern matching, using the Varargs extractor provided by the Scala 3 standard library. As a result, we get a sequence of trees (from Expr[Seq[Any]], we get Seq[Expr[Any]]):

val stringExps: Seq[Expr[String]] = exprs match 
  case Varargs(es) => // macro implementation called with varargs
  case e => // macro implementation called with other parameters

If the extraction is successful, we map each expression corresponding to subsequent parameters, using pattern matching again. This time, we inspect the underlying term tree, to check if it corresponds to a constant value (such as a constant string literal).

If so, we return an expression containing that constant (as a string). Otherwise, we convert the expression to a string containing the label and value:

case Varargs(es) => 
  es.map { e =>
    e.asTerm match {
      case Literal(c: Constant) => Expr(c.value.toString)
      case _ => showWithValue(e)
    }
  }

Why one time do we have to match on expressions, and the other on terms? Varargs is a special construct used to handle this type of parameters. In all other cases, if we want to inspect the shape of the code that was passed in (the Abstract Syntax Tree), we'll have to match on the expression's term — as above.

And we're almost done; the last step is converting the stringExps: Seq[Expr[String]] to an Expr[String] by generating code which will concatenate all of the strings. Two string expressions can be concatenated by splicing both expressions, combining them as any other two strings, and quoting the result. More generally:

val concatenatedStringsExp = stringExps
  .reduceOption((e1, e2) => '{$e1 + ", " + $e2})
  .getOrElse('{""})

And so we arrive at our final implementation:

inline def debug(inline exprs: Any*): Unit = ${debugImpl('exprs)}

private def debugImpl(exprs: Expr[Seq[Any]])(using Quotes): Expr[Unit] = 
  def showWithValue(e: Expr[_]): Expr[String] = 
    '{${Expr(e.show)} + " = " + $e}

  val stringExps: Seq[Expr[String]] = exprs match 
    case Varargs(es) => 
      es.map { e =>
        e.asTerm match {
          case Literal(c: Constant) => Expr(c.value.toString)
          case _ => showWithValue(e)
        }
      }
    case e => List(showWithValue(e))

  val concatenatedStringsExp = stringExps
    .reduceOption((e1, e2) => '{$e1 + ", " + $e2})
    .getOrElse('{""})

  '{println($concatenatedStringsExp)}

What's next

We've just scratched the surface of metaprogramming capabilities in Scala 3 / Dotty. First of all, inlining (the "static" metaprogramming variant) has quite a lot of interesting features, as described in Dotty docs:

recursive inline methods
specialized inline methods
using conditionals & matches in inlined methods
selective summoning (conditional logic depending on available implicits)

Macros also have other features which we haven't covered, such as quoting & splicing types, summoning implicits in macros and more extensive pattern matching involving quoted patterns. Finally, there's multi-stage programming support, which enables constructing code at run-time.

As mentioned before, all of the code presented here is available on GitHub. Have fun exploring Scala 3 / Dotty!

3 reasons to adopt Event Sourcing

Adam Warski — Thu, 01 Apr 2021 12:42:17 +0000

Event Sourcing is everywhere. Almost every architectural problem in an IT system can be solved using Event Sourcing. Is that true? Of course not! Still, the pattern is proving to be very useful in a number of situations. When to consider using event sourcing? What are the scenarios, where this pattern works best?

There's a couple of great articles on the basics of event sourcing, such as the introduction on MSDN, another one by Martin Fowler, or the documentation of Akka Persistence and EventStore. Event sourcing is a rich pattern, and as you might see, each article might focus on a different use-case.

In this article, we'll first briefly introduce Event Sourcing, and then take a look at three possible use-cases, which might prompt adopting Event Sourcing in your system.

What is Event Sourcing?

An event is a fact, which describes a state change that occurred to some entity. Notice the past tense! An event is something that already happened. As such, it cannot be modified — events, just like facts, are immutable.

In a system which is based on event sourcing, the primary source of truth is the stream of events. All state is derived from this stream. This includes the "current" state of entities, which is often the basis on which the system's business logic operates.

A good introduction connecting the concepts of event sourcing, stream processing, CEP and reactive can be found in Martin Kleppmann's article.

For any entity, its current state can be derived by folding — or in other words, applying — all events relating to this entity, starting with some initial "empty" state.

A rare event: tapirs jumping over a stream, by Zofia Warska (illustrations are very loosely related to the article)

Implementing event sourcing might make sense globally in a system, but quite probably you'll want to use it selectively. Event sourcing can peacefully co-exists with other methods of handling state in a system; it's not a binary, all-or-nothing choice.

1. Performance

Performance might be the most-cited and well-publicised use-case for Event Sourcing. While it is true that this pattern might help in designing a high-performance system, nothing comes for free. There are still challenges that lie ahead, and tradeoffs to be made!

This might be exemplified by the fact that there are "event-sourcing rescue projects" as well:

Jimmy Bogard 🍻

@jbogard

every Event Sourcing rescue project i've been on was also promised these things and found them not to be true (for their scenario)

16:12 PM - 23 Jan 2020

Remember though, that "rescue projects" usually have a couple of problems, and give a skewed picture of a technology. Reality is not that harsh!

In a system under heavy load, event sourcing can be useful thanks to two of its characteristics: separating read and write models, and natural sharding. Let's look at both of these.

1.1. Separating read and write models

Not only each system is different, but individual functionalities/endpoints in a system might see radically different usage characteristics. In a system which receives a lot of traffic, you might see a lot of writes, as compared to reads. Or, only relatively few writes, but a lot of reads; or, you might see one component of the system to be used much more often than others.

To properly deal with performance requirements, while maintaining sane operational costs, we might need to scale the components of the system independently. Again, depending on the traffic pattern, we might want to scale only the write-part. Or, we might want to scale only reads. Finally, we might want to scale only a small fraction of the overall read functionality that the system enables.

We might also want to scale both reads & writes. The good thing is that with event sourcing, we can again do so independently, using different approaches. It's this freedom when it comes to deciding what to scale and how, which makes event sourcing so useful to implement performance-related requirements.

How might this look in practice? As our primary source of truth is the stream of events, a write operation can be made as simple as appending an event to a log-like database. This might be Kafka, EventStore, Cassandra, or even SQL with a good archiving and sharding strategy: each technology has its pros and cons. An append is typically a very fast operation, comparing to e.g. typical usage of a relational database, which has to deal with locks, transactions, read and write clients etc. Hence, the system might have good overall performance.

For a more in-depth view on why writes in a database often used for event sourcing — Apache Cassandra — are so fast, take a look at Andrzej Ludwikowski's article "Cassandra writes in depth".

To implement and scale reads, we can create various views of the event stream; this is also called read models or projections. Some views might store data in a relational database, so that it can be accessed using SQL. Other views might analyse the data and feed it to Spark, Hadoop, Kafka or any other data analytics framework. Finally, read models which will be under heavy load might be created in multiple copies (to balance traffic), using either in-memory or NoSQL storage.

Some tips on implementing read models when using Akka Persistence can be found in another article by Andrzej. Also, check out our reactive event sourcing training!

One formalisation of the above architecture is CQRS (Command Query Responsibility Segregation; see also the much more comprehensive e-book by Greg Young). This pattern is often used in combination with event sourcing, to implement high-performance systems. The reactive movement is also closely related, as event sourcing might directly implement the message-passing paradigm, and is one way of building responsive, resilient and elastic systems.

A surprising event, by Zofia Warska

Where's the catch, then? Well, there's a couple of catches, in fact. First of all, in a distributed setting, appending data to a log isn't that easy. First, you need to make your log distributed. Again, Kafka/Cassandra/EventStore make this possible, however, whenever you start dealing with distributed data, you‘re introducing new operational and implementation complexity.

Second, you might encounter eventual consistency. Data that you write doesn't have to be immediately available when read, as it first needs to be written to the read models. A write is considered successful when it's appended to the log, not when all read models get updated. This flexibility in implementing the data views also brings its challenges, ranging from user experience, through request deduplication, to ensuring data consistency on the business logic level.

1.2. Natural sharding of data by grouping events by entities

A related technique, which can be used in systems with high data volume or a large number of entities, for which state has to be stored, is a combination of event sourcing and the actor model. This approach is the basis e.g. of Akka persistence.

Each actor in such a system stores data for a single entity. The data is stored in-memory. Any updates to the actor's state arrive as events. These events are persisted in a database (which might also be distributed, e.g. Cassandra), and then the actor updates its internal state based on the data in the event.

Hence, the actor's state can be entirely reconstructed from the events relating to that single entity. The longer the event history, the more costly this might be, that's why it's usually desired to also store actor-state snapshots for fast recovery and migration of actor/entity state.

What makes this architecture fast? First of all, all reads are done from memory (assuming the actor for a particular entity is materialised). Second, all writes are simple append operations. Thirdly, it's trivial to shard the data in the system, taking the entity id as the shard key.

That is, the only data routing requirement is that all events for a single entity should be directed to a single node in the cluster. We thus need a coordinator which knows which actors/entities are assigned to which nodes, and that's it! These coordinators can be clustered as well, to remove a single point of failure. That way, we can implement a data storage and processing system which scales horizontally — just by adding more computing power. You don't always need such as setup, but when you do, event sourcing might be a good choice!

1.3. Turning the database inside-out

The implications of an event-first approach when designing data storage system has been studied in depth by Martin Kleppmann. A good reference in that area is his book, "Designing data intensive applications".

A recommended read! https://dataintensive.net

In a traditional database, internally the transactional (e.g. write-ahead) logs are already based on events. However, what a relational database gives us, is a projection of the events so that it's possible to conveniently work with the "current" state of the entities using SQL.

Martin's core idea of "turning the database inside-out" is to work with this log of events directly; this way we can scale writes to the log, and create projections as necessary. While this approach is more scalable and more performant, it also removes all of the goodness that relational databases give us: SQL and ACID transactions. Also, it's not that new, as Martin himself notes:

Martin Kleppmann

@martinkl

Such a powerful idea; keeps getting reinvented under different names (event sourcing; lambda/kappa architecture; database inside-out/unbundled; state machine replication; etc). twitter.com/neil_conway/st…

07:33 AM - 11 May 2018

Neil Conway @neil_conway
Reflecting on the fact that I've built some flavor of the "immutable, append-only log + materialized views" pattern into every non-trivial software project I've built since 2006.

This "inside-out" approach might also be a good candidate for an intra-microservice, asynchronous communication pattern. By making the events (and their schema) public, each microservice can arbitrarily use the data emitted by others.

We get very loose coupling, without the need for an upfront design of e.g. an HTTP API, with pre-determined data projections that are made available. Opinions differ, however. As Oliver Libutzki notes in his article, while Domain Events (more on this later) can be used for communication between services/bounded contexts, event sourcing should be kept as a service-local implementation detail.

2. Data modelling

When looking from a data modelling perspective, event sourcing shows other benefits. Designing a system where the stream of events is the central source of truth forces you to think differently about the flow of the data through the application.

In CRUD applications based on relational databases, various forms of "events" are often added as an after-thought. As we implement our applications, we discover that otherwise separate components must be notified of a change that took place somewhere else in the system. Or, we need to update an external system to keep it in sync with our data, but for performance reasons we do it in the background. If you've worked on business applications before, the above probably sounds familiar!

Event sourcing reverses the relationship between data and events. Events no longer are secondary, derived from the changing reference data. It's the events that drive all of the business logic, and it's the read models that are derived from the event stream. Greg Young explains it in a somewhat simplified form:

Greg Young

@gregyoung

want to learn event sourcing?

f(state, event) => state

18:37 PM - 17 Mar 2013

The consequences of this change are much more far-reaching than only data modelling. The whole structure of an application written using event sourcing might be different, ranging from code organisation, through defining boundaries of modules, ending in extracting whole microservices, which might process a data stream independently.

Think of a simple shopping system, where you can buy socks. In a traditional system, you would have a /buy/socks API endpoint. Upon invocation, this would update the SOCKS inventory table, perform an insert to the order table, send an email and perform another API call to the fulfillment service. However, each modification of the process, however trivial, involves changing this core logic.

With event sourcing, we start thinking a bit differently. We no longer have an incoming request that arrives at our system, and database tables to be updated. Instead, we are dealing with a UserBoughtSocks event (or with a command, that creates the event).

It's something that already happened (the user clicked the big green "Buy" button), and now we must deal with it. We might have synchronous event listeners which verify, that we actually have the socks in stock. We might have asynchronous event listeners, which send emails, create other events for the fulfillment service, or aggregate metrics.

If we start thinking in terms of immutable events, that already happened, instead of thinking in terms of requests and mutable database tables, we'll soon discover that our code takes a much different shape. We'll see that individual functionalities become more loosely coupled, as they are driven by incoming events, not by a central request controller. We might also see workflows that start emerging, probably somehow mirroring the business process that is happening behind the scenes.

Stream, by Hanna Fałkowska

Event sourcing gives us a new degree of flexibility, thanks to the separation of the action from effect (see this interview with Martin Kelppmann). We have flexibility in reacting to events happening in other parts of the system; we also have the flexibility of creating multiple read models.

We are no longer constrained by a one-size-fits-all data model. We can create many redundant read models, duplicating data as needed (the event stream is always the primary source of truth anyway), aggregating and indexing data as required by a particular functionality. Here, event sourcing is truly liberating.

Moreover, existing read models can be recreated and new read models can be created retrospectively, taking into account all the data that is available in the event stream — taking advantage of full information. However, make sure to test such scenarios as well!

Udi Dahan

@udidahan

This has been one of my main complaints around the "just replay the event stream" solution presented to many things in the event-sourcing community. twitter.com/tjaskula/statu…

09:11 AM - 21 Aug 2019

Tomasz Jaskuλa @tjaskula
The hard part is to figure out what actions that user took on those false event streams are actually relevant and how to keep them in rewriting process.

No discussion of data modelling can be complete without a mention of DDD (Domain Driven Design). And indeed, event sourcing fits like a glove. The central concepts of DDD is that of an aggregate: defined sets of data, which capture an important business concept.

When modelling a system, one natural way is to define the aggregates together with the aggregate events. Such an event captures a single step of a business process, or one transition in a workflow, or part of the aggregate's lifecycle.

Defining the (many) aggregates is a discovery process, necessarily involving the business! This is done together with sketching interactions that occur between them through events; following this methodology, we might soon discover the bounded contexts of our system. Event Storming is a related technique (not only through its name!): both a workshop format and design approach for modelling complex business domains.

Where's the catch? When modelling data, designing a system and most importantly evolving a system, it's important to retain a clear view of the interactions between various components. The liberty of reacting to events might need to be constrained.

With event sourcing we get looser coupling of components, but that might also end up as a tangled mess of hard-to-follow relationships. The business logic might get decentralised. Keep in mind, that while sending an email is a concern that is probably completely separate from updating the inventory service, quite often business logic is a series of steps, that need to be done in sequence: that's just the nature of the world. Don't try to hide the fact by artificially creating multiple events.

You might also look at other patterns, that try to address the above mentioned issue and that are being used in DDD. One is the Saga pattern, both in the choreography and orchestration variants. Another is context mapping, which helps to identify relationships between bounded contexts.

The interactions between aggregates and events, where events are produced and where they are consumed can't always be expressed only in code. Other means of conveying information might be needed here: diagrams, drawings, conventions. Self-documenting code is good, but documentation is sometimes still needed.

Putting both the specific DDD techniques, and the potential modelling problems aside, I think the "Data Modelling" section is best summarised by Jessica Kerr:

Event Sourcing gives you a complete, consistent model of the slice of the world modeled by your software. That's pretty attractive.

3. Auditing

Data auditing is the process of storing historical data, or capturing the changes performed to a dataset, along with metadata such as timestamps or user identifiers. Thanks to a data audit we can find out who made a particular change, when, and in some cases where or how.

The need for a data audit may come from a couple of sources. First, this might a regulatory requirement. If we are dealing with, for example, a financial application, we might be required to store all historical data for a certain period of time.

Audits might also be a security-related feature available for users. Every time you can browse through your recent actions, such as logins, profile changes, settings updates, you are in fact browsing an audit of your actions.

Finally, audit data might prove to be very valuable for analytics. It can help in understanding how a system is being used, what are the most common behaviours, taking into account both the timeline and quantity of actions.

There's a couple of approaches to implementing a data audit, and event sourcing provides one elegant way. Looking at the event stream from another angle, it's in fact the audit trail of our application. The audit is not an after-thought that's added to the system in the last few sprints; the audit drives the application.

Beyond all of that for me, the focus tends to be on the current state based model when the system is really event centric. This may sound like a nitpicky issue but I find teams doing this look at events with less importance than those who use events as storage as well as the latter only use events they are extremely event centric.
Greg Young, "Why use Event Sourcing?"

We've seen above that event sourcing can change the way we think about data modelling, as well as our approach to system design, going as low level as impacting code organisation. The same is true for data audits; the roles get reversed comparing to other solutions. It's the audit trail from which all other data are derived.

One immediate gain from such a situation is that it's impossible to forget to audit a specific operation, as no operation can happen in an event-sourced system without an event being written to the event log. That way, we make sure that no information is being lost. That's quite a good trait, given that we all work in Information Technology (IT)!

It's worth keeping in mind that the event stream itself stores only "raw data". Making this data useful will most probably involve some kind of transformation. If it's a requirement to present a user's security audit trail in an application, we should probably create a projection (a read model) which will store the appropriate data, and index them in a form that's useful for the audit view. Same for security or analytical audits.

Another benefit of a fully-audited/event-sourced system surface when we are faced with the need to debug a problem. Not only we have additional information on exactly what changed and when, we can also re-create the system state at any point in time, by replaying events up to the problematic one. This might prove valuable when trying to reproduce an issue.

A stream flowing through a valley full of sunshine, by Zofia Warska

What kind of problems we might expect when using event sourcing for data auditing? First of all, we'll never be able to track everything. There's always decisions to be made, as to what should be captured as an event. Any changes to the data, that have been performed by the user result in an obvious event.

How about page views? That's probably too fine-grained. We would quickly run into problems with our data storage running out of space. An audit trail shouldn't be used to perform website traffic analysis. However, we might want to capture the fact that a user has viewed some sensitive data. The answers here are very application-specific.

Another group of problems relates to deleting data. Either because we want to be nice to our users, or because we want to comply with privacy regulation in the EU and US, we might need to implement a feature of removing all data for a particular user. This is in obvious contradiction with the immutability of the event stream. In addition, some systems of storing a distributed log make it hard or impossible to modify data that is already written.

There are several solutions: using log compaction, periodically rewriting the event stream, or using encryption keys which are "forgotten" when a user requires their data to be deleted. Again, there are no universal solutions, and each use-case might require slightly different approach.

Finally, in the introduction we said that we can apply event-sourcing selectively, only where this is truly needed. When implementing an audit trail using events, this stops being true; event sourcing is becoming much more "viral" as all places that require capturing the audit need to use event sourcing.

If you're interested in other approaches to data auditing, check out our whitepaper on the subject!

Where to store the data

Event sourcing is often discussed in combination with NoSQL databases and messaging systems, such as EventStore, Cassandra and Kafka. But does event sourcing mandate the use of these storage systems? Is it necessary to introduce the high operational cost of a distributed or "NoSQL" database, just to use event sourcing? No!

Event sourcing can as well be implemented on top of a traditional, relational database. It's just as good for low-volume, internal applications, as well as for high-performance, mission-critical systems (however, the reasons for introducing event sourcing would be radically different).

The datastore options range from using relational databases both for events and the read model (and leveraging transactions in the process! See here for an example implementation using Scala), all the way to fully distributed databases and separate read&write models.

Summary

Above we've presented three common scenarios, where using event sourcing might be beneficial. Nothing comes for free! As with any other technology, it's easy to make mistakes when implementing event sourcing.

Hence whether you are looking at event sourcing from the perspective of performance, data modelling or data auditing, keep in mind the tradeoffs that will need to be made.

However, a lot of factors speak in favour of the pattern:

the ability to scale reads and writes independently
natural sharding of data
the liberty of creating arbitrary, tailored read models
data-centric approach do system modelling
loose coupling of business logic
audit-driven applications

In other words, event sourcing might be your gateway to a flexible, no-information-lost, unconstrained, but audited future!

Shelly: under the hood

Adam Warski — Thu, 25 Mar 2021 19:36:50 +0000

Shelly — a programming language for drawing — is one of our side-projects that we work on in-between other engagements.

It features the challenge mode, where through a series of step-by-step tutorials you can learn both the Shelly language, as well as the basics of programming. There's also the creative mode, where you can draw whatever you like, and share it with others as an image, code (to allow modifications), or as a custom challenge — can others reproduce your painting?

https://shelly.dev/p/adamw/47fc197c3154

Shelly delivers the well-known concept of turtle graphics in a modern package, with a friendly interface, instant drawing, rich sharing options, and gamification. You write the program, and Shelly the turtle immediately reflects the new code on the canvas — live programming!

The Shelly language is a mix between Logo and more modern programming languages. Due to its educational character, it's kept simple: we've got expressions, named functions, loops, conditionals, recursion, and that's about it! Still, even using these basic constructs, you can create some really interesting images.

https://shelly.dev/p/adamw/27e55b6e028d

You might be wondering: what's under the hood? What kind of technologies can one use to build such a live-coding environment?

Shelly itself is built with TypeScript. The types bring some sanity to the otherwise untyped JavaScript/browser domain, integrating nicely with the whole rest of the ecosystem.

For the skeleton of the application, we've made a popular choice, that is React. Nothing non-standard, though as the application has grown, we've seen that our reliance on Context API to manage state has reached its limits. That's why we're considering porting that aspect to Redux.

https://shelly.dev/p/adamw/608a6168c983

Second, we've got the editor. Here, we are using the Monaco Editor, which is the editor that's also used in VisualStudio Code. To configure the editor for a custom language, you have to provide the keywords, symbols, operators and configure the tokenizer. We also get auto-complete out-of-the-box — you just need to provide the completion function, which can be context-sensitive or not.

Monaco also gives us the possibility to manage errors (underlying them and showing glyphs) and provides contextual editor extensions. In Shelly, this is used to show a palette of available colors and pen patterns, whenever the user writes pen or fill. Try it!

https://shelly.dev/p/adamw/992d937596c3

Monaco has quite good documentation, though sometimes you'll end up digging through GitHub looking for usage examples to see how to best configure the parser, provide styling or manage the web workers.

Let's move to the canvas. Here, the main job is done by Konva, which provides us with a simple and performant layer on top of the raw HTML canvas element. Shelly uses a rather basic subset of Konva, as Shelly's drawings are composed mainly of lines, arches, basic figures, and SVG patterns (hearts, stars, cars, etc.). One aspect that was especially challenging, however, was properly handling the zoom & pan, using both on-screen controls and the mouse wheel.

https://shelly.dev/p/adamw/62d98bc06139

What about the drawing/programming language itself? Even though it's quite simple, we still need a tokenizer and an interpreter. We've chosen ANTLR to define the grammar, with antlr4ts as the target. That is, when running the ANTLR tool, the input is a file containing the grammar definition, and as the output, we get TypeScript files that handle the parsing of arbitrary text into an AST (Abstract Syntax Tree).

However, we are not using the ANTLR-defined AST directly when doing the interpretation (that is, actually running the program), but we're translating it to yet another representation, which is more flexible in the result type — and we need that flexibility to implement arbitrary-depth recursion. Here, we've used trampolining, thanks to which you can loop and loop without blowing the browser's JS stack.

https://shelly.dev/p/adamw/f08a8c07a102

The downside of using ANTLR with the TypeScript backend is that the resulting package is quite large — which means a large download, and a longer wait for the initial page load. That's why we might consider writing a parser by hand in the future, which won't have any third-party dependencies.

Shelly's frontend is built using webpack, tested with jest and playwright, and deployed using Netlify. The whole process of connecting a GitHub repository, configuring CI, pull request previews, custom domains, and, finally, the production build is really painless. And makes the development so much easier!

https://shelly.dev/p/adamw/b896560155c3

Finally, on the backend, we've got a simple Scala-based application, deployed on Heroku. The database is PostgreSQL, but the application is not a straightforward CRUD as you might expect, but instead uses SQL-based, transactional event sourcing. Probably overkill, but — if we ever want to create a new view basing on the events (which include e.g. program creation in creative mode, or solving a challenge) — for sure we'll have the data available!

And that's it. Give Shelly a try, solve the challenges or create a drawing in creative mode. Then, let us know what you think, what you'd improve, change or add!

Never write a UserService again

Adam Warski — Mon, 22 Mar 2021 15:40:36 +0000

Recently at our semi-regular architecture discussion group, we've been looking at the Auth0 service: what it is, how it works and when it might be a good idea to use it.

I'd like to focus on the last aspect, using Auth0 as a case-study for the more general problem of when to use external services in our microservices mix, and when to roll your own.

On one hand, it's totally reasonable not to write yet another UserService which handles user authentication and authorization. It's been done before, and we all like to reuse code. On the other, using an external service requires us to let go of the otherwise total control we have over our system.

It's a tradeoff. How to decide, when to use one option or the other?

Auth0

Before diving into tradeoffs, let's make a very quick introduction to Auth0, which we'll use as our running example.

Auth0 is a service which manages identities of the system's users, providing both authentication and authorization.

Users can be authenticated in a variety of ways:

using traditional username/password
through various social identity providers (Google, Facebook, Twitter, … )
passwordless, with login links sent by e-mail
multi-factor (such as push, e-mail or voice notifications, one-time passwords)

Auth0 can manage the database of the users for you, or you can connect your own datastore. There's a number of integration options available, calling in either directly to the DB instance, or through an API. If the built-in options are not sufficient, you can always provide integration code yourself (in JavaScript).

For authorization, Auth0 offers role-based access control (again, with roles & permissions stored in Auth0's database, or externally), as well as extension points to provide your own mechanisms (through rules, hooks and extensions).

You have the option to use Auth0-hosted login screens (a component that is very important for the end-user experience), which can be themed so that they match your site; or you can roll your own, and just call Auth0 APIs.

Finally, Auth0 uses the OAuth2 standard for authorization, and the identity layer conforms to OpenID Connect (see also this introduction to the standards).

What does that mean? OAuth2 defines a number of flows, which should be used depending on the type of the client (if the client's execution environment can be trusted or not), whether the client is an end-user or a machine, and what kind of session we want to establish (one-off, temporary or long-running).

Auth0 endpoints behave as specified by OAuth2, hence we know what to expect when interacting with them. Which OAuth2 flow to use depends on the concrete use case, which can be such as:

regular web app, with a server-side component
single-page-app, with client-side sessions only
mobile apps
machine-to-machine (service-to-service)
single-sign-on (SSO)

OAuth2 relies on signed tokens being passed between interested parties. The tokens that Auth0 creates are JWT tokens, hence in an almost-human readable JSON format. That's yet another standard, which you can encounter when implementing the security layer of your application.

Finally, what are the alternatives to Auth0? It's not the only service implementing such functionality. Other options that you might want to check out if you are surveying the authentication landscape are:

as-a-service: Okta, Amazon Cognito, onelogin, PingIdentity, FusionAuth
self-hosted: KeyCloak, Gluu, FreeIPA

External microservices

Modern systems are typically composed of multiple services of various sizes. Deployments vary, from Kubernetes on one end, through Heroku and bare metal on the other. However and wherever the services are deployed, they usually communicate using HTTP APIs, or at least offer the possibility to communicate with them this way.

Hence, replacing one of the (micro)services with an external API shouldn't create huge changes in the system architecture. Still, there's a number of factors to consider when deciding "if" and choosing "which" service to bet on.

Replaceability

The absolute first thing to consider is how easy it is to replace a potential external microservice. Nobody likes vendor lock-in: integrating too much with an external provider, we are then forced to use their services for better or worse, as the cost of switching is too high or would cause too much disruption.

Hence, we need to check whether the APIs that the service exposes conform to open, or at least "emergent" standards — and if these open standards are really used throughout the industry. Does the competition support the same standards as well? That is, what would it take to switch to another vendor?

How does Auth0 score in replaceability? On the plus sides, we've got the OAuth2 and OpenID Connect standards, which are not only a codified specification, but they are indeed used across the industry. Basing your authentication flows on OAuth2 will ensure that you will be able to switch both to other identity service vendors, or to roll your own: there's a lot of OAuth2-supporting open-source projects (and a couple of close-source ones probably as well).

However, it's not all roses. Auth0 does extend or adjust the standard slightly. For example to implement role-based access control, the permissions calculated from user roles are returned in the permissions claim of the access tokens, which are non-standard. While adding custom claims is something the standard does allow of course, in the event of migration, you'd need to replicate that functionality.

Another point where you might encounter some vendor lock-in are the SDKs. Auth0 provides a rich set of libraries which allow interacting with the service from a number of programming languages, both to perform client or server-side authentication, parse access tokens and interact with the Auth0 management API. That's a very useful feature when developing applications: however, you should be aware that using them might tie you to the Auth0 service itself. If you were to create your own user service, you might have to amend the code to use a different or custom SDK.

Security

Since we are delegating some part of the system's data and functionality to an external provider, security should be one of our main concerns. Looking through the company blog, documentation and regulatory compliance (GDPR/CCPA/CalOPPA/…) should provide some initial background into how seriously a given service takes security.

Further, we might want to investigate previous incidents (if any). If there were security incidents, this doesn't yet eliminate the service — we should check how the incident was handled, if a post-mortem was published, how transparent the company was about things that went wrong, and what are the conclusions for the future.

Even the presence of a simple status dashboard gives some insight into how the company communicates with their users.

Auth0 is in a special position, as their service itself deals with security, so in this case, security of the service is double important. Take a look at their compliance and status pages.

Latency

When services are deployed together, they usually enjoy the benefits of communicating within a local or almost-local network. This changes when you use an external service. If it's being used a lot, what is the additional price per request that you have to pay for using the service?

And the price I'm talking about here is not measured in USD, but in milliseconds — every additional millisecond of latency might directly translate to user happiness (and we end up with USD again). Using an external service might mean an additional network hop or multiple hops — e.g. if the service looks up data in our database, at our datacenter, through an extension point.

Hence, does the external service provider offer endpoints in various regions? Quite often we have US and EU-based servers, but what about other continents — what if we want to deploy the rest of our services in Australia, Asia, Africa or non-US America?

You might also want to check if the external service is deployed on the infrastructure of a specific cloud provider. If it's e.g. AWS, you'll get great connectivity when hosting your services in the same AWS region, but probably worse when using a different region or GCP/Azure.

In case of Auth0, all of their public infrastructure is hosted on AWS. They offer four regions: US, US-2, EU and AU. It's also worth noting that you can choose a private cloud deployment option (which of course is more expensive).

Extensibility

External microservices put a focus on making the most common use cases easy to configure and pleasant to use, so that they can attract the widest possible audience (it's a business which has to make a profit, after all).

This might mean that, like many web frameworks in popular programming languages, bootstraping a project is rapid and leads to a very effective initial iteration. Even implementing 90% of the required functionality might be a breeze. However, the pain and hacking starts when we are left with the remaining non-standard 10%.

That's where extensibility of the external service comes into play. What are the available extension points? Can you plug-in into each step in the lifecycle of a managed data entity or into each step of a request? What are the constraints on the integrations?

Looking at Auth0, there are rules, which run after a user is authenticated. There are also hooks, which run at pre-defined extension points; some of them run synchronously, some asynchronously. Finally, there are extensions, which allow to integrate with third-party applications such as logging services (which is an important aspect as well!).

As already mentioned, the custom extension code is written using JavaScript, and can interact with any API, and use one of the many available libraries.

We've successfuly started using Auth0 at SoftwareMill and the available extension points have been sufficient so far. But more projects and more production experience is needed to verify if anything important is missing.

Cost

In the end, it all boils down to costs. For systems with low or medium traffic, using an external service will almost always be way cheaper than the cost of developing a custom implementation.

It's worth noting, however, that usage costs (which are typically sized proportionally to the number of users or API requests) are not the only cost associated with using an external service. There's still development costs, which include:

configuring the service
integrating the system's codebase with the service

Depending on the quality of the documentation, the UX of the administration panel, and automation options (see also below), this might require smaller or larger amounts of training. Same with integration costs — a good SDK which matches the ecosystem (both language and libraries) that you are using to develop the rest of the system will save a lot of development time. However, as already mentioned, it might also tighten vendor lock-in.

In case of Auth0, pricing is something you'll have to calculate for your use-case yourself, I'll refrain from giving any advice here. As for the development costs when using the service — OAuth2 and OpenID are both non-trivial standards to understand, and they take time to learn. However, this knowledge is largely vendor-independent. Getting to know Auth0 concepts still takes some time (the distinction between tenants, apps, etc. for example), but given solid background in open authentication standards, this shouldn't be too challenging.

Automation

When initially setting up the service, we'll probably be happy with a nice-looking administration UI, clicking around exploring the various options and discovering the features.

However later, as we dig deeper and start developing our system, integrating with the given external service more seriously, clicking in the UI will stop being fun and become frustrating instead. Moreover, if we are configuring multiple environments, doing this manually will not only be a waste of time, but also very error-prone.

That's why it's crucial that a service exposes all of their features through an API. AWS got this right, and even went a step further: the UI sometimes gives only some of the functionality, that is available when using the API programmatically. And that's the right approach. Having a well-documented configuration API is a must. If there are ready-to-use SDKs ready in popular programming languages, even better.

But that's only one aspect of automation. Another is infrastructure-as-code tools, such as Terraform, Ansible or Chef. Using these we can describe the target configuration of the external system, which is typically stored in one or multiple files. These files can then be part of our version control system, and the configuration can be partially dynamic, depending e.g. on the target environment. A separate tool-dependent process then applies the configuration to the external service, adjusting the "current" state with the "desired" state.

Auth0 exposes a comprehensive management API, so everything looks good on this front. It also allows connecting a git repository storing configuration, which is automatically applied on push. The configuration files in the repository must follow a pre-defined structure. Finally, there's a Terraform Auth0 provider, which can be used to fully manage Auth0 configuration.

Testing

Let's not forget about testing! Since we are externalising part of our system, we will no longer be able to run everything on our laptop. But that ship might have sailed long ago, if our system is truly composed of a non-trivial amount of microservices. We'll need service stubs for local development anyway.

That said, we'll still need to configure the external system in a couple of copies, to setup production/staging/development environments. As mentioned above, automation is crucial here. The external service should make it easy enough to quickly and dynamically create a fresh copy.

Summing up

As we move towards fine-grained single-responsibility microservices, it's increasingly feasible to use an external service for the "standard" parts of each system.

We're commonly doing this with logging, using services such as Loggly or DataDog. We're using managed databases, be it on AWS, Heroku or database-vendor-specific solutions. We're storing binaries on S3. Externalising user authentication and authorization might be a good candidate as well.

There still might be cases where developing your own UserService will be a better option — if you have very non-standard requirements, need to replace an existing API, or due to legal/regulatory requirements. However, chances are high that for quite a lot of systems using an external service will be the most cost-efficient and future-proof solution.

Structured concurrency and pure functions

Adam Warski — Fri, 19 Mar 2021 10:08:00 +0000

A function or a method is pure, if:

it has no side effects
the returned value depends only on the provided arguments

We will be most interested in the first property, that is lack of side effects. An example of a side effect is anything that changes the "state of the world", such as modifying a global variable or performing any kind of I/O.

Pure functions are widely described, see for example the article on Wikipedia, a blog post using Java, or Haskell docs page.

Purity doesn't have to be a binary property, though. There are some side effects that we care more about than others. For example, logging isn't often counted as a side effect (even though it performs I/O), and hence a function which makes some computations and performs logging might be still considered pure.

Structured concurrency is a property of concurrent programs, where (following the definition by Martin Sústrik) the lifetimes of concurrent functions are cleanly nested. That is, if a function foo starts running a function bar in the background (bar runs concurrently to foo), then bar must finish before foo completes.

This ensures that the scopes of functions running concurrently are cleanly nested. This might seem like a reasonable property, however concurrent code is rarely written in that style in practice. Computations, in the forms of threads, fibers, coroutines or processes — depending on the language and framework used — are started in the background and left running without supervision or joining.

Nathaniel J. Smith makes a successful comparison between goto and go (which here stands for unconstrained forking of concurrent computations) in his blog "Notes on structured concurrency, or: Go statement considered harmful". The article provides an alternative introduction to structured concurrency; by avoiding goto we make sure we can read and try to understand the source code without arbitrary jumps. Similarly, by avoiding go we can avoid even worse kid of jumping: to multiple locations at once, again making the code easier to read.

Another way of looking at the structured concurrency property is that lifetimes of concurrently running functions must follow the syntactic layout of the program. Hence the name: the scope of concurrency follows the structure of the code.

Do the two properties described above relate? Yes! Starting a thread and leaving it running after the function completes is a side-effect. Not only we change the state of the world by creating a new thread, the thread itself must perform some state-changing actions to do any meaningful work (if all it did was running a pure function, it wouldn't make sense to start it at all). That's all under the assumption that the lifetime of the thread exceeds the lifetime of the function call.

What structured concurrency specifies is that this cannot happen: thread-related side effects are not permitted. Any threads that are started by the function, must complete before the function completes. In other words:

A function that satisfies the structured concurrency property is a function that is pure wrt threading side-effects.

That way, threading becomes an implementation detail of the function. It's the responsibility of the function to decide whether threads must be started (either for performance, or to implement its logic), and it's also its responsibility to ensure that these threads to terminate (by waiting for them to complete, or interrupting them).

A pure function might still use side-effecting logic internally, such as using mutable state for performance, but it cannot mutate anything that's global. Similarly, a threading-pure function might create concurrent threads of execution internally, but they cannot be left running after the function completes.

Other side effects might happen in a threading-pure function; it doesn't have to be pure wrt to all kinds of side effects.

What if the function at hand returns a Future or a Promise: that is, a value representing a computation running in the background, that will eventually yield a result? Can such functions be structurally concurrent?

They might be, but we need to adjust our definition a bit; requiring that a function returning a Future doesn't leave any concurrent threads running after it completes, would defeat the purpose of using Futures in the first place.

Hence, a Futue-returning function will satisfy the structural concurrency property as long as the returned future will complete only once all other futures/promises created by the function are complete as well (successfully or with an error).

Again, this translates to the fact that no threads of execution are left running in the background, but this time when the computation returned by the function completes. In the same way, we can extend the definition of threading-purity.

What about functional effects, that is various forms of IOs? Unlike Futures, such values are descriptions of computations (not running computations), which might have side-effects once interpreted. That is, IOs are lazy, while Futures are eager.

By a similar extension to the one we've done before, a function returning an IO is structurally concurrent if the computation that is described by the value doesn't leave any threads running as a side-effect (once it is complete). This makes the described computation "self-contained".

Structured concurrency is a promising concept, which provides a great tool for writing correct concurrent programs and reading them afterwards. It's being implemented in Java (see project Loom), Kotlin, Scala, Python, C and other languages.

Pure functions are the basic building block of Functional Programming (FP). That's where FP takes its power from; code which uses pure functions is easier to read, follow and understand.

Structured concurrency, seen as a specialisation of function purity to the domain of threading, is one more example of this property. It's easier to understand and write correct code where threads can't exceed the lifetime of the function in which they are started.

Which might make you wonder: maybe the same applies to other side effects, such as I/O or global state? That's what the FP community has been saying for a long time, and depending on the complexity of the problem at hand, indeed avoiding such side effects in functions might be beneficial to the maintainability and long-term evolution of a codebase.