Ruby 3 has introduced a game-changing feature for concurrent programming with the release of Fiber::SchedulerInterface. This powerful tool allows developers to manage fibers, making it easier to handle context switching in I/O-bound tasks. In this article, we will dive into the world of fibers and socketry/async stack, exploring the powerful capabilities they offer on the sample of background jobs processor.

It’s going to be a rather big piece, so here is a quick plan of what’s going to be described:

• What’s Fiber?
• What’s so special about Fiber::SchedulerInterface?
• Different kinds of event selectors
• Socketry overview
• Jiggler. Fiber-based background job processor
• Jiggler core components
• Pre-emptive fiber scheduling
• Benchmarks
• Limitations
• Future

What is Fiber?

Fibers are primitives for implementing lightweight cooperative concurrency. Fibers exist within a thread and only one fiber per thread can run at a time. They use very little memory, so it is possible to create thousands of fibers without a huge memory footprint. Another important aspect is that threads are managed by the operating system’s scheduler, and fibers are scheduled and managed by developers.

First introduced in Ruby 1.9 (December 2007), it’s not a new concept. Despite being lightweight and providing more control, fibers didn’t gain wide community popularity, staying a rather rarely used feature. Perhaps, due to the fact that Ruby didn’t provide a simple out-of-the-box scheduling interface, or maybe because the community is heavily Rails-centric, thus it’s just easier for people to stick to threads as a more commonly used construct.

However, there are still several fiber-using libraries, which used to be pioneers and gained some popularity:

• Celluloid https://github.com/celluloid/celluloid — not maintained since 2016, but back at the times it was one of the main Ruby gems providing handy API to write concurrent Ruby code.
• Em-synchrony https://github.com/igrigorik/em-synchrony — a fibered implementation of EventMachine, latest commits happenned about 5 years ago.

When using fibers in older Ruby versions (from 1.9 until 3), developers had to keep track of all the fibers and manually manage them by calling the Fiber::yield, Fiber#resume and Fiber#transfermethods. This process can be complex, too verbose and error-prone.

Nowadays, with Ruby 3 the fibers management has become much simpler.

What’s so special about Fiber Scheduler?

Fiber::SchedulerInterface provides a set of hooks invoked when a blocking operation begins/ends.

Basically, Ruby standard I/O methods such as IO#wait_readable, IO#wait_writable, IO#read, IO#write,Kernel.sleep, etc., have been patched to yield to the scheduler if it‘s defined in the context of the current thread. And the scheduler, in turn, passes execution control to the other ready fibers.

This automatically makes all standard Ruby calls scheduler-friendly. However, there are still a lot of Ruby gems using C-extentions, which could perform I/O on their own bypassing Ruby’s native methods. For example, different kinds of DB-adapters. Fortunately, it’s relatively easy to implement a call to the scheduler from a C-extention, so the fiber-support across such gems gradually grows. It’s up to developers to check if a given gem with a built-in C-extention supports the scheduler and thus if it makes sense to use with fibers.

Different kinds of event selectors

An event selector is a Linux kernel feature that allows a program to monitor multiple file descriptor sources for events, such as input or output operations. In other words, that is a mechanism that among other things can notify a program whenever a specific non-blocking operation is complete.

For example, if the fiber was blocked because no data was available on the socket it reads from, it should be resumed once the data arrives. The scheduler should be notified that the non-blocking operation is complete by using one of the next strategies underneath:

• poll()/epoll() is the default mechanism for watching sockets to see if new data is available on almost all Linux systems.
• io_uring is a Linux kernel library that provides a high-performance interface for asynchronous I/O operations. It was introduced in Linux kernel version 5.1 and aims to address some of the limitations and scalability issues of the existing asynchronous I/O interface.
• kqueue() is used in OSX/FreeBSD.
• IO Completion Ports for Windows.

Most production systems would most likely use epoll() as it’s the most common approach for Linux systems, however it might worth giving a try to io_uring if it’s supported by the specific Fiber.scheduler and is available in the OS.

It worth mentioning that before the arrival of Fiber scheduler, the main library which took care of I/O events start/end detections was Nio4r https://github.com/socketry/nio4r . And it is still used in Action Cable, Puma, Async v1 and a lot of other libraries dealing with I/O.

Socketry overview

As of now, Socketry https://github.com/socketry is the most popular collection of the asynchronous libraries in the Ruby world.

Async https://github.com/socketry/async is the framework providing handy interfaces to make fiber-driven development even simpler. It has a built-in Fiber.scheduler with epoll/kqueue and io_uring support. It encapsulates all scheduler-related calls, so the users could easily spin up asynchronous tasks, see the example below:

Async do
  resources.each do |resource|
    Async do
      result = api_client.get(resource)
      DB.connection.save(result)
    rescue => err
      logger.error(err)
    end
  end
end

That’s it, as simple as that.

Jiggler. Background job processor implementation

Let’s re-evaluate when fibers could shine the most.

Usually, the systems manage all I/O waiting by allocating a separate OS thread for every request or worker. This approach is effective to some extent, but OS thread is relatively expensive to create and the context switches performed by the OS also don’t come for free. This leads to a lot of overhead. With fibers, it is possible to utilize non-blocking I/O to minimize this overhead.

When dealing with CPU-heavy tasks, breaking down the workload into smaller parts through the use of fibers will not bring benefits if the system lacks the resources to handle the workload. However, many Ruby processes spend a significant amount of time waiting for I/O operations, such as awaiting responses from API or database calls, or writing data to a file. This is the perfect usecase for fibers.

Given, that socketry/async provides all the required APIs to build a job-processor, then such projects simply had to start appearing.

It was very, very hard, but also it was easy © davie504

Jiggler https://github.com/tuwukee/jiggler

jiggler is inspired by sidekiqand althrough it doesn’t support as many features, it still implements a very similar paradigm, so it’s fair to compare these 2 in terms of performance, to clearly see all the benefits fibers and socketry/async can provide when compared with the pure thread-based approach.

Jiggler core components

Conceptually jiggler consists of two parts: the client and the server.
The client is responsible for pushing jobs into Redis and allows to read statistics, while the server reads jobs from Redis, processes them, and writes statistics.

The server consists of 3 parts: Manager, Poller, Monitor.

• Manager spins up and handles workers.
• Poller periodically fetches data for retries and scheduled jobs.
• Monitor periodically loads stats data into redis.

Pre-emptive fiber scheduling

One important catch here, is that we want Poller and Monitor to be guaranteed to work in their time, even if the workers perform some CPU-heavy tasks. We want to have up-to-date stats and stable polling. With threads we don’t care, as OS periodically switches threads without developer’s interventions, while the Fiber.scheduler waits for a command to switch context.

That’s called co-operative scheduling. Once started, a task within a co-operative scheduling system will continue to run until it relinquishes control. This is usually at its synchronisation point.

In a pre-emptive model tasks can be forcibly suspended.

There’s a great article by Wander Hillen explaining the problematics in the context of Ruby, highly recommend to read it:
https://www.wjwh.eu/posts/2021-02-07-ruby-preemptive-fiber.html

Jiggler solves this problem by forcing the scheduler to switch between fibers in case their execution takes more time than a given threshold value. It introduces a dedicated thread, which encapsulates the scheduler management. The dedicated thread adds some overhead, yet it’s compensated with the achieved time execution control.

CONTEXT_SWITCHER_THRESHOLD = 0.5

def patch_scheduler
  @switcher = Thread.new(Fiber.scheduler) do |scheduler|
    loop do
      sleep(CONTEXT_SWITCHER_THRESHOLD)
      switch = scheduler.context_switch
      next if switch.nil?
      next if Process.clock_gettime(Process::CLOCK_MONOTONIC) - switch < CONTEXT_SWITCHER_THRESHOLD

      Process.kill('URG', Process.pid)
    end
  end

  Signal.trap('URG') do
    next Fiber.scheduler.context_switch!(nil) unless Async::Task.current?
    Async::Task.current.yield
  end

  Fiber.scheduler.instance_eval do
    def context_switch
      @context_switch
    end

    def context_switch!(value = Process.clock_gettime(Process::CLOCK_MONOTONIC))
      @context_switch = value
    end

    def block(...)
      context_switch!(nil)
      super
    end

    def kernel_sleep(...)
      context_switch!(nil)
      super
    end

    def resume(fiber, *args)
      context_switch!
      super
    end
  end
end

Benchmarks

The latest benchmarks are available on the jiggler README page.
As of now, it beats sidekiq in all benchmarks when it comes to the execution of the code aware of Fiber scheduler hooks.

It depends on the payload, but on the given samples it usually saves 10–20% of memory with the same concurrency settings. For the speed — it shows rather good results with File IO, but the difference is not so impressive with net/http or PG requests.

But don’t forget, that when using fibers — the concurrency can be set to higher values. Technically the overhead of spawning workers is expected to be low. So it’s possible to test it with 50, or 100, or even more workers against a specific payload, in case there is indeed a lot of I/O going on. The limitation is rather in the connection pool (when the workers are doing some DB queries) or in the external services accepting the requests (in case of network requests).

Limitations

Developers should be careful when using C-extentions within fibers. socketry/async doesn’t support JRuby as of now, so MRI is the only way. No support for Windows users as well.

When running the benchmarks with OSX (M1 processor) — they weren’t as good both natively and in Docker. Why? I don’t know for sure, and the investigations from my side is still ongoing (more like it stands still, but I hope to find out one day anyway).

I tried to test directly socketry/async against native Ruby threads, and against Polyphony (https://github.com/digital-fabric/polyphony — another interesting framework for fibers), and Polyphony actually works great on OSX M1. So the problem might be in kqueue() support implementation within socketry/async Fiber scheduler, but I didn’t get anywhere further than that, and it might be a false lead.

Future

It’s fun building jiggler, I learn a lot. I have a lot of plans and ideas for this lib but not so much free time to actually work on it. As of now, the gem is already available in RC version.

One idea would be to try to implement brpoplpush per queue in dedicated reader classes (instead of brpop for all queues in each worker), thus granting at-least-once worker execution (currently it’s at-most-once, same as free version of sidekiq). Another idea might be to test PG as a backend instead of Redis. Wait, what? Yes! It will add A LOT of overhead, but this approach will also grant out-of-the-box reliability. Great opportunities lie ahead of us!

Thanks for reading!

Rails ActiveSupport time methods are slow. Let’s take beginnig_of_month as an example and look at the benchmarks comparing it with a pure Ruby implementation (Rails 6.1.4, Ruby 2.6.6):

time = Time.now.utc
n = 1_000_000

Benchmark.bm do |x|
  x.report do
    n.times do
      time.beginning_of_month
    end
  end
  x.report do
    n.times do 
      Time.utc(time.year, time.month)
    end
  end
end

user       system     total    real
5.256222   0.012179   5.268401 (  5.280565)
0.614967   0.004348   0.619315 (  0.620292)

The difference in performance is quite noticeable, ActiveSupport is almost 9 times slower. The same situation appears with other ActiveSupport methods, such as beginnig_of_day, beginning_of_quarter , end_of_month , etc. which are not so easily replaceable with quick pure Ruby versions.

So, why does ActiveSupport take so much time?
First of all, the problem persists for both DateTime::Calculations and Date::Calculations modules, though they are affected in varying degrees.
Internally ActiveSupport adds a lot of complexity, checks multiple options, handles timezones and conversions, and thus causes performance degradation. Yet it can be avoided by relying on native Ruby solutions where it makes sense.

I’ve run into the ActiveSupport date methods performance issue while trying to speed up a code iterating through a huge collection of entities with dates in their attributes. The entities were aggregated and modified depending on the result of beginning_of_quarter and end_of_quartermethods. And it turned out that a significant improvement could be achieved by simply using a cache. Classic.

Here goes a class wrapping the dates cache implementation. Be careful, It’ll help only in case the date range is limited, and the dates are repeated within the given loop.

class MemoizedDates
  attr_accessor :cache
  MDate = Struct.new(:beginning_of_quarter, :end_of_quarter)

  def initialize
    @cache = {}
  end

  # handles cache misses
  def find(date)
    cache[date] || memoize(date)
  end

  private

  def memoize(date)
    cache[date] = MDate.new(
      date.beginning_of_quarter,
      date.end_of_quarter
    )
  end
end

### sample usage

memoized_dates = MemoizedDates.new
collection.each do |entry|
  date = memoized_dates.find(entry.date)
  if date.beginning_of_quarter > n
    # do stuff
  end
end

### benchmark

time = Time.now.utc
memoized_cache = MemoizedDates.new
n = 1_000_000

Benchmark.bm do |x|
  x.report do
    n.times do
      rand_date = time - rand(1000).days

      rand_date.beginning_of_quarter
      rand_date.end_of_quarter
    end
  end
  x.report do
    n.times do
      rand_date = time - rand(1000).days
      mem_date = memoized_cache.find(rand_date)

      mem_date.beginning_of_quarter
      mem_date.end_of_quarter
    end
  end
end

user        system    total     real
39.541243   0.210272  39.751515 ( 39.920949)
10.769937   0.065638  10.835575 ( 10.891969)

Happy coding!

Since the team was quite small, we could easily consent on new practices, apply creative approaches, devote time to refactoring whenever we felt that a tech debt grows. It was so handy and convenient for me that I got used to the idea that this is it. This is the way people do things. This is the life of an ordinary ruby developer.

But the good cannot last forever and I was transferred to another project for a few months. And I must admit, it affected me quite sobering.

The new application was a pretty old monolith with a huge amount of legacy code. The team consisted of more than 20 developers, and this does not include QAs, PMs, POs, BIs, etc. They are all good people with a solid tech knowledge. They had a fine idea of the system as a whole. Yet when it came down to the details — nobody knew anything. I mean, nobody really knew why this or that specific decision was made. Why this service is stored in this directory, while a similar one is stored elsewhere. Why the same problem is solved by 3 different classes in different places. No naming conventions. Chaotic folders structure, while some services are stored in the /lib dir, the others are defined as nested classes, some are placed together with models, others are in the /services dir. Crazy after_save callbacks with external API calls right in the AR models. The Gemfile included dozens of gems, some of them were not even used in the app. Business logic smeared evenly on models, controllers, views, services, helpers, with significant interspersed in JQuery based scripts. Lots of heavy DB requests on each page with extra joins and unnecessary data load. Multiple package managers and significant frontend build times. And much more. Or, in other words, everyone knew the answer to any of these, and the answer to any question was: it’s like this because it’s legacy.

But that’s not bad, after all these are classic problems of many legacy apps. Everyone agreed that the technical debt is huge and it needs to be addressed at some point. Yet the main c-level technical guys were mostly focused on new contracts and implementing new parts of the system. The usual day-to-day tech debt was placed under the responsibility of the whole team. The team has a few team leads and so they should deal with it somehow. Yet it didn’t help and in this direction there was nearly no work at all (well, except some cosmetic minor improvements, but that doesn’t count). One of the main reasons why we didn’t do anything — first, we should agree on what to do, what to start from, and what’s the way we’d like to stick to, to standardize our approaches. And in such a big team it’s nearly impossible to agree on anything. There always was some kind of push back to any idea, and even in case a suggestion is minor and everyone does not mind, there was no active support (only ActiveSupport was there hehe) and all proposals inevitably drowned at the bottom of JIRA backlog.

In any case, it is a very rewarding experience to plunge into for a short while. I made a lot of conclusions for myself. And one of them is that it’s much easier to prevent the system from chaotic crawling into random and sometimes mind-blowing code constructions than to try to reorganize it at the later stages. And the other one, is that some developers could all their lives work in this fusion-style-chaotic systems, and never even see that there is another way to work on a production application. I’ve seen the “another way”, so I’m a lucky one (yay).

With this being said, now I’d like to share the way how I personally like to organize code in a Rails app.

Let’s start from the classic confrontation of /app vs /lib folder.

The /app folder contains all the stuff that belong to the business logic. We’ll get back to it later.

The /lib folder, in theory, should contain the code that later could be packaged as gems. But in the real world I usually do not know in advance, which part of the app’s code is going to be good enough to be decoupled to become a gem. So this problem is solved by the fact that I store nothing in the /lib folder. Okay, okay, almost nothing.

So, in my case, /lib folder contains rake tasks and another subfolder called developer. This one is rather specific, and not all apps need this. It stores certain media and text files which I’m using in dev-env to conveniently test different kinds of processing.

All the other folders contain configuration, database schema, migrations, logs, tests, basically all the stuff that allows the application to run but not the application itself.

Now let’s take a closer look at the /app folder itself.

Lately, a lot of developers tend to call any class which is not an AR model a service and simply throw it into /services dir, no matter what the class actually does. I‘d rather not do it. In my case services are only these classes which are making API calls. For example, S3Service or IBMWatsonService, or OpenWeatherService, you got the idea.

All the other helper classes or modules are usually can be classified as some kind of design patterns. The most common patterns I use are decorators, forms, query objects, commands, and strategies. They are stored in dedicated folders and can be re-used between f.e. controllers and sidekiq jobs.

Btw, talking about the sidekiq jobs. In my case they are rather sophisticated and the most complex processing logic is extracted to /processes folder and is stored in classes like CaptionExtractionProcess , or SyncRecordsProcess, etc., so they can be easily tested and re-used between different jobs.

All that implies that there’re almost no “fat” in models and controllers.

And yeah, it’s not completely fair to compare these 2 applications and their processes. The first one is a part of a service-oriented system, originally designed in a way that small dedicated teams can work independently. And the other one is a monolith with huge codebase in a combination with a big team without well-established processes (on their way to apply agile practices). With that being said, I personally came to a conclusion that huge monoliths are evil. Moderate-size monoliths are ok though, but this’s a topic for another story.

A few samples to make it a bit less abstract.
Here’s a query object:

This’s a simplified strategy code sample together with the InputProcessor class, which selects the strategy depending on the type of input.

All of the above is my personal opinion and it’s not the only “right” way to organize the code. If you’re happy with your style and it works for you, then cool ;) Feel free to share your opinion in the comments or reach me at Twitter.
Cheers!

First of all, the official Docker documentation is great https://docs.docker.com/ and even provides a step by step manual for Rails https://docs.docker.com/compose/rails/. You do not actually need this article in case you’ve read it all, but modern engineers are short on time, so here goes a quick and a bit simplified Rails instruction for Puma + PG + Webpack combination.

Let’s say your Gemfile looks more or less like this.

After you’ve installed Docker you’ll need to add only 2 files to your app’s root dir: Dockerfile and docker-compose.yml.

A quick overview of what’s going on in this file.
Firstly, we’re using a prebuilt Docker image with the desired Ruby version.

FROM ruby:2.6.5-slim-stretch

Then all packages required for PostgreSQL, NodeJS, Yarn, and for a few gems with C-extensions (like nokogiri) are being installed.

RUN apt-get update && apt-get install -y \
  curl \
  build-essential \
  libpq-dev &&\
  curl -sL https://deb.nodesource.com/setup_10.x | bash - && \
  curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add - && \
  echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list && \
  apt-get update && apt-get install -y nodejs yarn

The rest of the file is pretty obvious, so we can move directly to docker-compose.yml.

We’re all set now. Here’re a few useful commands to run in the console.

docker-compose build
docker-compose run web bundle install
docker-compose run web yarn install
docker-compose run web rake db:create
docker-compose run web rake db:migrate
docker-compose up
docker-compose down

Yep, it’s that easy.

“Premature optimization is the root of all evil.” — Donald Knuth

However, as it usually happens with famous quotes, in the full context the meaning slightly changes.

“Programmers waste enormous amounts of time thinking about, or worrying about, the speed of noncritical parts of their programs, and these attempts at efficiency actually have a strong negative impact when debugging and maintenance are considered. We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil. Yet we should not pass up our opportunities in that critical 3%.” — Donald Knuth

The real question is how to detect in advance which optimizations will be critical for a specific program. Depending on endless circumstances and conditions it can be absolutely anything.

Still, we can try to distinguish the most common pitfalls at least for web applications. There are already a lot of fine sources with recommendations for frontend performance (f.e. this checklist) including such bits of advice as minified HTML, CSS, and JS, lazy loading, images optimizations, non-blocking JS calls, etc, which are easy to implement and guarantee a performance boost. In this article, I’d like to try combining a similar checklist but for the backend performance. Backend is more tricky in terms of general recommendations so each advice should be carefully checked in the context of your specific application before blindly applying all the practices.

I’ll group the advice in 4 categories— Data, CPU & IO, Metrics, and Scaling. Databases have entire books written devoted solely to performance tuning, so in this article we’ll be focusing on the way how the app interacts with data which let’s assume is already stored within a perfectly tuned database.

Data

Store the required data in memory

IO operations are increasing latency, so storing the required and/or commonly used data in memory boosts the performance. To minimize the tolls on crashes use persistent in-memory storages so the data can be at least partially restored on the process restart.
But keep in mind, that sometimes cache invalidation may cost a lot, so use it wisely.

Construct a colocated data model

Ideally, the related data should be located on the same host (and be stored in memory). All the data necessary to service a specific request should be available locally without extra lookups.

Use data types which can be stored sequentially

With massive cache usage, memory access can become a bottleneck. Prefer flat arrays instead of linked lists when possible.

Fewer DB requests

For the cases when you must retrieve the data from the database it’s better when it can be done within a single query.

Fewer SQL JOINs

Multiple JOINs can dramatically degrade query performance. When a query requires 3 and more JOINs then it’s a good reason to think about database tables denormalization.

Don’t store more data than you really need

Unnecessary data slows down performance. It doesn’t necessarily mean to blindly truncate all the data, just be smarter on deciding on what and where should be stored. For instance, session data can be stored in cookies instead of a table. Btw, cookies shouldn’t be too heavy either.

RAM

Have as much RAM as you need (within reasonable limits of hardware, OS, and funds).

CPU & IO

Threads number should be close to a number of cores

In a perfect case, threads should be running in parallel, each pinned to its own core, with a minimum amount of context switches.

Batch writes

Instead of doing single writes group your data and do batch writes wherever that’s possible.

Use async and non-blocking operations

Locks are overhead. Each time lock is used the app should go down by the OS stack. Prefer async operations wherever it makes sense and does not complicate the codebase too much.

Parallelize operations

In order to reduce the overall processing time.

Use thread pulls with a fixed number of workers

This implies that there’s a queue to drag a work from, which substantially increases throughput. Thread per connection/worker usually leads to a case when you have more threads than cores meaning your system tries to do too much at once.

Compress the data on a disk

IO operations are usually time-consuming. Data compressing can cost some CPU cycles but will help to effectively increase IO throughput.

Compress the data being sent over the network

It decreases transfer time and increases throughput. The CPU time cost of the compression and decompression is usually trivial. The overall efficiency of a system using compressed network transmissions is almost always higher than sending data uncompressed.

Keepalive connections

Minimizes the costs of connection open/close operations. Especially valuable for the cases of frequent requests.

Data streaming

You can save some CPU and memory if you stream the data to the external services directly instead of combining a full file in advance (e.g. firstly writing data to a disk and then reading it and post the data to the network).

Operating systems limitations

On Linux, if you have more than approximately 1000 files per directory then performance will start to degrade. You can split them up, and store the files in nested directories. Popular databases (MySQL, PostgreSQL, etc) store tables in files, so too many tables can affect performance from an OS perspective as well.

Metrics

Little’s law

Using this law we can determine how many app instances do we need to cover the application load. A theorem by John Little states that:

L = λ * W

In the context of a web application, L is the number of app instances (e.g. threads/processes with an app copy), λ is the average requests rate (e.g. 10 requests per second), W is the average response time (e.g. 0.3 seconds).

10 * 0.3 = 3 (3 is the number of app instances we need)

It’s not the most accurate prediction, but at least it’s an easy way to approximately estimate required app instances for given load requirements. Using the same formula we can calculate the theoretical maximum throughput. It also helps to realize that the page load time is quite important when it comes to surviving traffic peaks.
Keep in mind, that in real life these are not isolated units, and with increasing load on the database, cache, network, the numbers won’t be changing strictly proportional. In other words, if DB is the bottleneck, then the increase of app instances number won’t increase throughput.

Know your requirements

You should know in advance the expected traffic on your web site and plan the app infrastructure accordingly.

Use monitoring tools

Automatically detect spikes in CPU and RAM. During the application’s lifespan pages tend to grow up in size and their load time tends to slow down. It’s a good practice to measure this, set boundary values (e.g. the max page load time is 200ms and the max page size is 100KB, except for the data from CDN), and take action when it starts to get out of control.

Automated testing is essential

Use integration and unit tests for daily agile development. Use performance testing to ensure your application will perform well under the expected workload.

Aggregate your logs

Aggregate and store logs in a central location for easy access. Keeping the logs explicit but not extremely verbose is a separate art form.

Timeouts

Put timeouts on all out-of-process calls and pick a default timeout for everything.

Scaling

Use CDNs

Guarantees faster load times for users, can be quickly scaled in case of traffic spikes.

Prefer eventual consistency if possible

Eventually consistent data storage systems use asynchronous processes to update remote replicas. If BASE (Basically Available Soft-State Eventually Consistent) is sufficient for your data, then you can easily achieve scalability and availability from a distributed data storage system.

Autoscaling

Setup auto-scaling based on the data from your monitoring tools. DDOS attacks may cause extra scale up operations, so set smart rules to make sure if a scale-up is necessary.

Service discovery

A central server (or servers) that maintain a global view of addresses and clients that connect to the central server to update and retrieve addresses. It’s a must-have for a dynamic system with autoscaling in place anyways.

Containers

Containers make it easier to manage deployments and service discoveries.

Decentralize services

Embrace self-service wherever possible, allowing services to be independently deployable and backward compatible. Prefer choreography over orchestration with smart endpoints to ensure that you’re keeping things cohesive with associated logic and data within service boundaries.

Instead of a conclusion

Resources

Donald Knuth book “Computer Programming as an Art”
https://github.com/futurice/backend-best-practices
http://khaidoan.wikidot.com/performance-tuning-backend
https://github.com/binhnguyennus/awesome-scalability
Piotr Murach talk “It is correct, but is it fast?”

It’s complicated by the fact that engineers usually interpret SOLID principles in a slightly different way, and moreover, each one (me included) has their own ideas of the cases where and when the best object-oriented design practices do not make sense to be applied. After all, the principles aren’t strict rules, they are simply the guidelines.

I have faced with the complexity and versatility of a decision which is the most convenient design solution not so long ago myself. I was attending a job interview and I was asked to refactor a piece of code similar to this one:

My very first idea was to implement a decorator class and to move all the logic related to the credit there. In this way, we could decorate the class only in those places where this business logic is required, achieving lousy coupling, skinny models, etc, etc.

But although this was accepted as a possible option, the interviewer pointed out that the usage of the decorated class requires too much code on the “client-side”. And suggested the next solution.

The “client-side” usage appears to be more elegant. And this led us to quite an interesting conversation.

Int — With the CreditHandler implemented as the above we can treat the credit attribute as an object and benefit from the OOP perspective.
Me — This solution does not benefit from the OOP perspective. It breaks SOLID principles, namely Dependency Inversion. Dependence on abstraction, not a specific implementation. Dependencies need to be passed either through the constructor or through the property, we shouldn’t hard-code classes into each other.
Int — Well, you can go for a dependency injection. And implement it as

Agency.new(credit_handler: CreditHandler) 
def credit; @credit ||= credit_handler.new(self); end

Int — It does not change the essence. Looks like overengineering and premature optimization for me. The original proposed implementation indeed breaks SOLID, but those 5 are the design principles, it does not break the OOP rules itself (4 of them). In my opinion, follow SOLID means not to apply the practices immediately, but to apply them when necessary; that is, as soon as it becomes necessary to use different flows for the credit attribute in the example.

And it made me think. How does one make a decision what is an overengineering and what is a reasonable solution? Should the engineers follow the best practices from the beginning? Or it is an overcomplication and it’s best to apply only a limited set of recommendations? How do I make those decisions and how often I follow the best practices? How often I don’t? And, gradually, it led me to a realization, that I’m, as a Ruby on Rails developer, break the SOLID recommendations every single day! Well, at least some of them. And it’s while trying hard to follow the best practices whenever I see an opportunity. If you’re a Ruby developer then most likely you break the guidelines on a daily basis too.

Let’s list the SOLID principles to take a closer look at them before we’ll try to understand when and how do we violate them:

• S — Single responsibility principle (SRP). A class should have only one reason to change.
• O — Open/closed principle (OCP). Software entities should be open for extension, but closed for modification
• L — Liskov substitution principle (LSP). If S is a subtype of T, then objects of type T in a program may be replaced with objects of type S without altering any of the desirable properties of that program.
• I — Interface segregation principle (ISP). No client should be forced to depend on methods it does not use.
• D — Dependency inversion principle (DIP). High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend on details. Details should depend on abstractions.

SRP

That principle is often being misinterpreted.
Almost every Ruby on Rails developer at least once said something like: “Ah, single responsibility principle? Yeah, ActiveRecord breaks this one, it has way too many responsibilities”. Active Record indeed is an example of a God-object anti-pattern, it knows too much and does too much. But it has nothing to do with SRP from SOLID.
The problem lays in the interpretation of “reason” word from “A class should have only one reason to change.”. Developers tend to think that each meaningful function of an object is some kind of a “reason”, while SRP itself refers to the business layer of things.
ActiveRecord is responsible for validations, database adapters, caching, combining SQL queries, and many other things, but from a business logic perspective, ActiveRecord’s User model is responsible only for storing users in a database correctly.
Let’s take a look at the next example to make it a bit more clear.

There are several types of employees and several types of payments. From the business point of view, the private method calculate has to handle too much — it calculates salaries and benefits for lawyers, managers, and accountants.
Let’s say at some point the logic of calculation of benefits for lawyers specifically should be changed, while the rest of the calculations should stay the same. Can you imagine how much confusion and possible errors can potentially bring this kind of business requirement? Ouch.
Shortly speaking, in most cases the business domain stays behind the violation of SRP.

OCP

The Ruby itself has a very vague concept of a “closed”. And while everything is open for extension, everything is open for modification as well.
I used to think that it’s out of my concerns as long as I do not directly monkey-patch other classes. But let’s take a closer look at the next example.

In the example, the actual result is that the classes in the namespace are being replaced by Rspec’s mocks and by this — modified. I’m a happy user of Rspec and it simplifies my life dramatically. But the fact is each time I’m using its mocks I’m modifying the upper class in the hierarchy by the lower one, which is supposed to depend on the upper one and is supposed only to extend it without any modifications.
I’m not saying we must stop using Rspec, the gem is absolutely great and perfectly fits for testing needs, I just need to admit that it violates the OCP in SOLID.

LSP

LSP aims to ensure that the inheritance is used correctly. This principle stands out from others within this article, as it has nothing special in terms of the Ruby world. No common misusages, no misconceptions, seems like at least LSP is usually respected among Rubyists. You can read more about LSP on this article, I have nothing to add.

ISP

The ISP states that a client should not be forced to depend on methods that it does not use. Interfaces Segregation is considered to be a problem of a programming language, not an architecture. Ruby together with all other dynamically typed languages cannot violate ISP at any mean.

DIP

This is the one which started this article. High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend on details. Details should depend on abstractions. That’s the principle which is violated the most in Ruby on Rails community. And also Sinatra community. And well, I think in many other Ruby communities independently of a framework they use, web-centered or not.
Let’s take a look at the next example.

UsersController — a high-level class depends on multiple low-level classes — User, UserCustomersPortalsQuery, AuthService.

The band of UsersController and User model is not such a bad thing though. The abuse of Dependency Injection is considered to be an anti-pattern itself. Some classes meant to be coupled, and in most cases UsersController does not make sense without User model. But we all can agree that the coupling of the controller with the AuthService does not feel so right.

In the enterprise world of .NET, this problem is usually solved by applying Inversion of Control and Dependency Injection patterns.
IoC implies that within your application there is an explicit point of a request entry, where you can explicitly call a constructor for a specific controller and explicitly pass all the classes it needs through Dependency Injection.

As a benefit — developers can easily substitute dependencies by other classes in the IoC. And by this, for example, easily replace the real classes with mocks in the test env.

It’s quite fun, as in the Ruby world we usually do not substitute real classes with mocks via DI. We’re already using Rspec and mocking the actual classes by the violation of OCP.

Just in order to help to get a very basic idea of what IoC looks like here’s a bit of ASP.NET MVC code. The example is quick and simple, and hopefully can be understood by people with zero experience in .NET (like me).

Controllers are not the root of all evil. I’m sure more or less the same violation of DIP can be found in, for example, ActiveJob classes.

Conclusion

It should be mentioned, that Bob Martin himself noted that the recommendations are not so strict in dynamic languages.

Violation of DIP helps to write code fast. Violation of OCP allows to reliably test the code. Although, the realization of mocks is tricky and as I can imagine is quite hard to maintain. Anyway, from some point of view, it proves that it’s possible to write maintainable software without a strict following of SOLID.

Yet, I believe that Ruby developers should stick more to the object-oriented design practices. Use Dependency Injection more often and write maintainable easy-extendable loose-couped code. It simplifies life a lot when properly handled. Cheers.

This story is published in Noteworthy, where 10,000+ readers come every day to learn about the people & ideas shaping the products we love.

Follow our publication to see more product & design stories featured by the Journal team.

The log itself was pretty noisy and was painful to read and analyze it with the naked eye.

At some point it was decided to switch to a centralized log management tool (Splunk in our case) in order to allow our support team to search/filter log entries on their own and in a more convenient way than less. Therefore we had to standardize all the log entries. The desired log entry format looks like

timestamp={time} level={severity} source_class={class_name} user_id={email} message={log_message} tag=#{tag}

Moreover there’s also a standard Rails log output which needs to be casted to this uniform format as well. There’re plenty of gems which do logs formatting, but after a quick investigation it turned out that it’s easy to adjust Rails logging without external libraries. And none of the gems was offering the required log format out-of-the-box anyway.

First of all, we’ll need a dedicated log formatter class, which has to respond to call(severity, time, progname, msg) method with this exact signature. severity stands for the level of message ‘importance’. time and msg arguments are more or less obvious, and progname is the name of the program which uses the logger class, it’s usually used by gems with built-in logging (Ruby docs).

Now let’s “plug” it into Rails. It was decided to keep default Rails TaggedLogging wrapper.

Yeah, that’s easy! Now our brand new log formatter is in place. Except it still misses some of desired attributes, i.e. source_class and user_id, they’re a bit trickier to implement, but let’s do it.

Our app has multiple event processing classes and it’d be neat to show within the log entry which of them produce this exact output. There’re a few possible options: manually add a class name to the logger message wherever we need it, or detect the caller class automatically on the fly. The second one sounds fun, so I decided to give it a shot first.

Ruby’s Kernel includes caller method which returns the current execution stack represented as an array of strings with files/methods names (Ruby Docs). It’s troublesome to build source_class detection based on this method solely. Still, we can achieve the same in an easier and a more performant way — by using binding_of_caller gem. It’s written in C and does exactly what we need — detects the class name flawlessly.

STACK_LEVEL is 7 as it goes through 6 methods in the logger stack before it gets into the log formatter.

Sadly, the gem’s author asks to not use it in production applications. Well ok, since we’re mostly interested in our internal classes output analysis we can go for explicit argument passing.

I didn’t want to monkey patch Logger class to make it accept additional arguments or to create a separate logger. Hooray due to dynamic typing it’s not necessary. We can use the next logger calls notation:

logger.info('Info message')

# or

logger.info(message: 'Info message', source_class: class_name, user_id: user.email)

It’s still the same single first method argument, but in the first example it’s a string, and in the second one — a hash. All we need to do is to allow the log formatter to work with hashes and to manually add source_class and/or user_id values to logger calls in the app wherever we need them to be in place.
The next log formatter version:

That could be enough in case we don’t use ActiveSupport::TaggedLogging. But we do, and this module casts all messages to string concatenating it with the tags. We have to add support for hash messages as well.

And that’s it, now let’s check it on a few examples.
Progname:

logger.info('MyApp') { 'Received a new package' }

=> timestamp='2018-09-03 19:50:39 +0000' level=INFO progname='MyApp' message='Received a new package'

Message as a hash:

logger.info(message: 'Message', user_id: 'admin@example.com', foo: 'Bar')

=> timestamp='2018-09-03 19:54:56 +0000' level=INFO message='Message' user_id='admin@example.com' foo='Bar'

Tagged logs:

logger.tagged('Records') do
  logger.debug message: 'Finding records...', 
               source_class: 'ClassName'
end

=> timestamp='2018-09-03 20:04:49 +0000' level=DEBUG message='Finding records...' source_class='ClassName' tag='[Records]'

Regular log message:

logger.warn('Warning')

=> timestamp='2018-09-03 20:09:19 +0000' level=WARN message='Warning'

Thanks for reading!
If you have any questions or feedback please feel free to reach me on twitter. Cheers!

In this part we‘ll add a forgot my password feature and an ability to edit user roles via the admin panel.

Acceptance criteria:
 — User should be able to restore their password via theforgot my password feature. Once User submits their email, they should receive a secure link via mail with reset password instructions.
 — On the password reset User should be logged out from all devices. User will have to enter their new password to log back in.
 — Admin should have an ability to edit all user roles except for their own (poka-yoke).
 — As User role is stored in the access token’s payload, once user’s role is edited — access token must be flushed, so the user will have to make a new refresh request in order to receive the access token with an updated payload.

The Backend

As we’re building an API-first application let’s start with the backend as usual. I’d propose to use a classic approach for password resets with unique password reset tokens which are used for generating reset password links.
1. Generate a rails migration.

$  rails g migration add_reset_password_fields

The migration itself:

2. Now we can add reset password token generation methods to the User model. After the password is reset we should clean up the tokens, so the same token couldn’t be used twice.

Now we’re ready to build the password resets controller. The desired flow is as follows: User submits their email (first endpoint), then gets a secure link which leads them to enter-new-password page (second endpoint), and then User enters the data and hits submit (third endpoint). So, we’d need to implement 3 actions within the controller.

3. Implement POST /password_resets endpoint. This endpoint sends mails so we’ll need to build a mailer class as well.

Password reset link goes within the mailer template.

The action itself.

Note, that even if a user is not found we should return a successful response anyway so an attacker will not be able to check whether certain email addresses are registered in the system.

4. Implement GET /reset_passwords/:token/edit . The action itself verifies if a specific reset password token is valid.

Custom exception is added as well. Let’s add a handler for this type of exceptions to the application controller.

5. Implement PATCH /reset_passwords/:token

Right after the password reset we clean up the tokens in the update action.
The routes.

And specs to ensure it works.

All of it implements the first AC on the backend. Now we can implement the second one.
6. An attentive reader might remember that the session in the application is represented with 2 tokens — access and refresh. They both are stored in redis (partly, for access token only its UID is persisted), so obviously, to flush the session we must delete the tokens from the redis. But first, we should link a user to their sessions to know exactly which sessions to flush. To be able to do that we can use namespaces which can group the sessions by their user (or any other common attributes).
Firstly, let’s add a namespace with user ID to all places in the app where we are operating over sessions, specifically signin , signup and refresh controllers.

namespace: "user_#{user.id}" attribute is added to the session declaration.

7. With this being done we can flush all sessions which share a common namespace.

8. Let’s move on to the next AC and allow Admins to edit user roles. We should keep in mind that while both Admins and Managers are allowed to view users, only Admins should have a permission to edit them (that’s controlled by the allowed_aud method). Also there’s a check in update action validating that Admins shouldn’t be able to modify their own role.
To fulfill the fourth AC we’re using flush_namespaced_access_tokens, it will keep the refresh token and remove the access only, which makes user’s locally stored access tokens invalid and user will have to perform a new refresh request.

Here‘re the specs.

API is ready and we can start to work on the frontend.

The Frontend

Foreword: JS code in this article is simple and straightforward, there‘re endless possibilities of refactoring (removing code-duplicates, using store instead of making API requests on each page load, etc), but all those improvements will lead me to a material for a separate article and I’m too lazy for this, so here goes the most naive JS implementation possible.

1. First, let’s build ForgotPassword component and add navigation links.

Update routes.

And add router links to Signin/Signup components.

Here’s the view.

2. ResetPassword.vue component — the one to which leads the link from the reset password email. The component on load sends a GET request to the reset passwords endpoint to verify that the token from URL is correct.

Routes.

Visualisation (all views are pretty similar, but still)

3. Now, when JS client users are able to reset their passwords, let’s add the ability to edit roles. We’ll create a separate Edit components for users in admin space. It also prevents non-admins from accessing users edit page and prohibits admins to modify their own roles.
To implement this check let’s add currentUserId as a getter to the Vue store.

The edit component contains a label with the selected user’s email and a select box with available roles list.

Routes.

The view.

4. We have the component, but there’s no way to navigate to it through the app yet. Let’s add links to the users edit view visible only for Admins.

The view (all links are available for Admin, except for the link to their own profile)

5. And the last, but not least. In this JS client we’re storing current user’s info in the local storage. So even in case access token is reseted after refresh on the server and the app automatically requests a new access token — it still doesn’t update user’s info within the store. Let’s fix that and request user info after refresh to surely be up to date with new user’s roles.

And that’s pretty much it, now the AC are met and we are set!

The application code can be found on GitHub.
Thanks for reading! It was fun making this series of articles.
If you have any questions or feedback please feel free to reach me on twitter. Cheers!

This time we’re going to extend the functionality and add a few more features.

Acceptance criteria:
 — User model should allow 3 types of roles: Admin, Manager and User (default).
— Admins and Managers should have an access to an admin panel.
 — Within the admin panel Admins and Managers should be able to view the list of all app users.
 — Within the admin panel only Admin users should be able to view a todo list of a selected user.

The application itself can be found on GitHub.

The Backend

1. First, we’ll specify allowed roles list within User model.

2. Add a role attribute to User model

$ rails generate migration add_role_to_users role:string

3. Set user role as the default value within the db migration.

4. Run rake db:migrate

5. Now we can add roles to the tokens payload. The general downside of using HTTP-only cookies as a token store — we cannot read the token’s payload on the frontend. We still can read the payload on the backend though, when receiving auth token from the web clients and thus prevent some db hits, as we can fetch and validate the authorization data from the token itself.
JWT standard provides a set of standard claims that can be used for token verification:

iss — Issuer. Identifies principal that issued the JWT.
sub — Subject. Identifies the subject of the JWT.
aud — Audience. Identifies the recipients that the JWT is intended for. This one can be used to specify the set of accepted roles.
exp — Expiration time.
nbf — Not before. Identifies the time on which the JWT will start to be accepted for processing.
iat — Issued at. Identifies the time at which the JWT was issued.
jti — JWT ID. Case sensitive unique identifier of the token even among different issuers.

If we’re talking about role-granted permissions verification, although we can use totally custom keys in the payload f.e. role key and verify it via Pundit , ActionPolicy or any other authorization solution, in this tutorial I’d like to show how to work with the standard JWT claims. But just for the sake of the interest later in the article I’ll show really quick the Pundit way as well.
Let’s update signin and signup controllers and extended the payload to include aud claim with the user’s role — payload = { user_id: user.id, aud: [user.role] }.

4. As the frontend cannot read the data from the payload, we must pass user data explicitly from the backend. Let’s build a separate endpoint for this matter (in real life I’d use a serializer in the controller, but I’m too lazy to build it within this example).

And a simple spec to ensure it works.

5. Now we can add users controller to the admin space of the API. We must specify token_claims method in order to let JWT know which claims we’d like to verify. On default it checks only the expiration claim. We’re going to add list of allowed roles — Admin and Manager, and verify them within aud claim.
The extremely cool part of it — all the authorization flow is performed without a single database query.

With the roles support we should handle 403 errors within the application controller.

Specs. Btw, those are demonstration specs, no need to test auth on each controller within the application.

6. And the last one — todos controller, only users with Admin role are allowed to view todos.

Specs.

The Frontend

1. Let’s add Vuex and Vuex-Persistedstate in order to manage the SPA state in a more convenient way.

$ npm install vuex --save
$ npm install vuex-persistedstate

2. Now we should fetch and store current user within the Vue store. Once we have the store, we can go ahead and move all the auth data to the store as well for the sake of consistance. But first, let’s create the store.

$ tree src
src
├── App.vue
├── backend
│   └── axios
│       └── index.js
├── components
│   ├── Signin.vue
│   ├── Signup.vue
│   └── todos
│       └── List.vue
├── main.js
├── router
│   └── index.js
└── store.js

3. Update routers to use the data from the store.

4. Now let’s add current user fetching to Signin/Signup components and adjust the rest of the code to use the data from the store.

5. Extract sign out link into a header component and add a link to the admin space, visible to Admins and Managers only.
To achieve it we’ll add isAdmin and isManager getters to the store. Vue allows to use more agile solutions to manage roles and permissions, but as it’s not the main goal of the article we’ll not focus on it too much.

$ tree src/components

src/components
├── AppHeader.vue
├── Signin.vue
├── Signup.vue
└── todos
   └── List.vue

Phew, a lot of work is done and all is to be able to show a tiny Admin link in the header for the specific users.

6. The link itself isn’t even pointing anywhere, so let’s fix that and add admin space component with users list.

$ tree src/components

src/components
├── AppHeader.vue
├── Signin.vue
├── Signup.vue
├── admin
│   └── users
│       └── List.vue
└── todos
   └── List.vue

And while we’re here let’s also add Home link to the header.

Yay, a fresh admin component is here. Note, the right column with todos icon is visible for Admin users only.

7. And finally, the last one component — todos per user.

$ tree src/components/admin

src/components/admin
└── users
   ├── List.vue
   └── todos
      └── List.vue

Visualisation.

And done! All acceptance criteria are fulfilled.
Here are few fancy gifs showing interactions with the app on behalf of users with different roles.

Admin

Visiting todos page, creating a new todo and deleting it, then visiting admin space, viewing the list of users and their todos.

Manager

Visiting todos page, creating a new todo and deleting it, then visiting admin space, viewing the list of users.

User

Visiting todos page, creating a new todo, then editing this todo and deleting it.

And as being promised, here’s a quick sample of Pundit policy using JWT payload for authorization. In the example we’re replacing pundit_user with the payload hash.
Payload is customizable, so it can contain specific permissions like { can_view_secret_resource: true}, which otherwise would require heavy db queries.

In the next part, hopefully final, I’ll show how to edit user roles and reset forgotten passwords, how to properly reset tokens and sessions in case of a role change or user deletion.
Thanks for reading!

UPD: 3rd Part of the series.

We’ll start with building an API-first REST-ful Rails backend. API-first means that the same API endpoints can be used by different Web/JS clients, mobile applications, 3rd party APIs, and ideally all of them should use a unified auth flow and JWT is a good fit for this goal. While in this article we’ll consider the creation of a single VueJS client, the API itself can be easily adapted to be reused by other API-consumers.

Tools for the backend:
Rails 5.2.0,
Ruby 2.4.4,
gem bcrypt 1.3.12,
gem jwt_sessions 2.1.0,
gem redis 4.0.1,
gem rack-cors 1.0.2

We are not tied up with this exact versions, I’m simply listing the ones I have installed on my local environment. Now, let’s build the classic todo app.

The Backend

1. Create a rails app rails new silver-octo-invention --api -T. The fancy project name is auto-generated by GitHub.-T option excludes Minitest, the default testing framework. We’ll be using RSpec .
2. Adjust Gemfile to look somewhat like this

3. Run bundle install

4. Run rails generate rspec:install . This command generates

.rspec
spec/spec_helper.rb
spec/rails_helper.rb

5. Now, let’s create the User model. We’ll start with the minimum required model fields rails g model user email:string password_digest:string

6. Add null: false settings to the migration strings.

7. Run rails db:migrate

8. Add has_secure_password method call to the User model.

9. Now, let’s create todos. Run rails g model todo title:string user:references && rails db:migrate

10. Let’s build the controllers. First, we’ll need to include JWTSessions::RailsAuthorization into ApplicationController. The module provides authorization actions which will protect secure endpoints.

11. We’ll need exception handlings for unauthorized requests, so let’s add it right away.

12. By the way, in order to use JWT we need to specify the initial configuration. JWTSessions gem by default it uses HS256 algorithm, and it needs an encryption key provided.
Also, on default the gem uses redis as a token store, so you’ll need a working redis-server instance. However, there’s a possibility to select memory as a token store (can be useful in test env). More info about specific settings can be found in the README.

13. Now, let’s create a signup endpoint. With token-based sessions and SPA we have 2 most common options of where to store the tokens on the client — cookies and localStorage. It’s up to developer to decide where they are going to store the tokens. While making the decision, keep in mind — cookies are vulnerable to CSRF and localStorage is vulnerable to XSS attacks. CSRF vulnerability is solvable - I usually prefer http-only cookies as the most secure token store.
jwt_sessions gem itself provides the set of tokens — access, refresh, and CSRF for the cases when cookies are chosen as the token store. With this being said, let’s use cookies together with the CSRF token provided by the gem (the gem automatically manages the CSRF validations when JWT is passed by request cookies).
The session within the gem is represented as a pair of tokens — access and refresh. Access token has a short life span (default 1 hour), and refresh has a relatively long life span (2 weeks). Expiration times are configurable. Refresh token is used to renew the access once it’s expired.
While it makes sense to pass refresh token to external API services or mobile applications — JS clients are usually not secure enough to store the precious refresh token. It’s up to developer to decide which info to pass or not to pass to JS. The jwt_sessions gem provides the possibility to issue a new access token by passing the old expired one, so we can avoid passing the refresh token to JS client. As both refresh and access tokens are linked to each other it will be easy to detect if the access has been stolen from the JS client and flush the leaked session (2 users —the original user and the attacker eventually will have 2 different access tokens pointing to the same refresh token).
Now for real, let’s create the signup endpoint. The endpoint must create users, assemble the JWT payload, and pass it via cookies with the response as well as the CSRF token via response body.

Specs to ensure the signup works.

14. Now we can build a sign in controller.

And specs for signin.

15. Here goes the refresh endpoint. As we’re building an endpoint for web client — we’ll be renewing a new access with the old expired one. Later we can create a separate set of endpoints to be used by other API-consumers (mobile/etc) which will operate via refresh tokens, but for this case we’re not going to risk it and to show the refresh token to the cruel outer world.
We’re expecting only expired access tokens to be used for refresh, so within the refresh_by_access_payload method a block is passed with unauth exception. Optionally, within the block we can notify the support team, flush the session or skip the block and ignore this kind of activity.
JWT library automatically checks expiration claims, and to avoid the exception for an expired access token we’ll be using claimless_payload method.

Refresh specs:

16. Almost there. This is the time to build the todos controller.

To make it work we’ll also need current_user, so let’s add it.
After the token is authorized we can dig into the payload and fetch whatever we decided to store within. In our case it’s user_id .

Generic todos specs:

17. We’re almost set with the API, it’s possible to sign up, to sign in, to refresh an access_token and to manage todos. But while we’re here, let’s also add ability to log out.

18. To allow JS client to send requests to the API we’ll need to set up CORS.

Routes configuration:

The Frontend

In this guide we’ll develop a stand alone front end application.

Tools for the frontend:

Node.js
Node.js Version Manager — NWM
Node.js Package Manager — NPM
VueJS CLI
Axios

$ node -v
v10.4.1
$ npm -v
6.1.0

1. Install the Vue CLI.

$ npm install --global vue-cli

2. Initialize the application.

$ vue init webpack todos-vue

This command is going to ask us a couple of questions.

? Project name todos-vue
? Project description Todos Vue.js application
? Author Yulia Oletskaya <yulia.oletskaya@gmail.com>
? Vue build standalone
? Install vue-router? Yes
? Use ESLint to lint your code? Yes
? Pick an ESLint preset Standard
? Set up unit tests Yes
? Pick a test runner karma
? Setup e2e tests with Nightwatch? No
? Should we run `npm install` for you after the project has been created? (recommended) npm

3. Start the application

$ cd todos-vue
$ npm run dev

And now it’s live on http://localhost:8080

4. Delete auto-generated HelloWorld component and create a new Signin.vue . The app directory should look similar to this one.

$ tree . -I "node_modules"
.
├── README.md
├── build
│   ├── build.js
│   ├── check-versions.js
│   ├── logo.png
│   ├── utils.js
│   ├── vue-loader.conf.js
│   ├── webpack.base.conf.js
│   ├── webpack.dev.conf.js
│   ├── webpack.prod.conf.js
│   └── webpack.test.conf.js
├── config
│   ├── dev.env.js
│   ├── index.js
│   ├── prod.env.js
│   └── test.env.js
├── index.html
├── package-lock.json
├── package.json
├── src
│   ├── App.vue
│   ├── assets
│   │   └── logo.png
│   ├── components
│   │   └── Signin.vue
│   ├── main.js
│   └── router
│       └── index.js
├── static
└── test
   └── unit
      ├── index.js
      ├── karma.conf.js
      └── specs
         └── Signin.spec.js

5. Let’s add stylesheet links to /index.html

6. Install axios within todos-vue dir.

$ npm install --save axios vue-axios

Prepare configuration files.

$ tree src/backend

src/backend
└── axios
   └── index.js

Define configuration and make Vue use the axios config.

7. Build Signin component. We are receiving cookies with an access token from the server response and they will be handled by the browser. In the response body we’ll receive CSRF. The CSRF token can be stored right in the localStorage, as we don’t really care even in case it’ll be stolen by a sudden XSS attack.

Visualisation:

8. To manage all the access/refresh auth we’ll need to build a custom wrapper for axios. The desired flow is following:

• JWT is stored within the HTTP-only cookie;
• For all requests except OPTIONS and GET we must add CSRF token to the request headers;
• Once JWT is expired the next API request with this cookie returns 401;
• At this step we should handle Unauthorized response code and make a refresh request with the expired access token for a new cookie;
• If the request is successful we must retry the original request, otherwise throw up the 401;

Actually, we’ll need to build even 2 axios wrappers. First one will use interceptors to handle 401s (secure axios instance) and the second one won’t have any special retry listeners (plain axios instance), but will perform refresh and retry requests — it’s needed in order to avoid endless loops.
As you might be noticed we’re already using the plain one on Signin as we do not need to retry requests on failed signins/signups:

this.$http.plain.post(‘/signin’, { email: this.email, password: this.password })

The router configuration:

As the cookie is HTTP-only it’s not easy to detect by JS if it’s present or not. Instead, we’ll be using a simple signedIn flag. Some people might say that the flag can be easily changed in the browser console and so unlogged user will have an access to “secure” URLs. Indeed, the flag can be modified manually. But since it’s only used to prevent redirects to login page, it doesn’t break security anyhow as in case of an attempt to retrieve/update a secure resource without a valid cookie, user will be redirected to the login page anyway.

9. Now, let’s build Signup component. It’s very similar to Signin.

A bit of visual representation

10. Finally, we can build a todos component. The implementation is pretty naive, the main goal here is to demonstrate the auth flow with basic CRUD.

$ tree src/components

src/components
├── Signin.vue
├── Signup.vue
└── todos
   └── List.vue

Routes.

Visualisation.

Fancy trash icon appears on hover, it’s important, and requires an additional screenshot.

11. And the last thing — sign out button. Let’s do this.

Visualisation

Wohoo, that’s it, now we have a completely functional secure CRUD VueJS SPA application.

Thanks for reading!
The application itself is available on GitHub.
I plan to continue the series, add admin panel, user roles, extend usage of JWT claims, add permissions to the payload - stay tuned.
UPD:
The 2nd part of the series.
The 3rd part of the series.

📝 Read this story later in Journal.

🗞 Wake up every Sunday morning to the week’s most noteworthy Tech stories, opinions, and news waiting in your inbox: Get the noteworthy newsletter >