DEV Community: Rafael Nunes

Improving Time To First Byte and Web Vitals

Rafael Nunes — Tue, 07 Sep 2021 00:47:11 +0000

In this post we will cover quite a few different concepts I recently explored that influence the page speed, how they relate to Core Web Vitals and how to improve them!

Let's start by agreeing on some terminologies and concepts that will be often referred on this post!

Time To First Byte (TTFB)

TTFB measures the duration from the user or client making an HTTP request to the first byte of the page being received by the client's browser.
https://en.wikipedia.org/wiki/Time_to_first_byte

This measure is used to indicate the responsiveness of the resource, our websites, our servers and so forth. This is often displayed in milliseconds (ms) in the tools, and the rule of thumb recommended by several players in the industry is 200ms!

This concept alone is important enough to look for improvements that will impact our customer's experience. However, it becomes better when we correlate it with another customer-focused metric, the Largest Contentful Paint.

Web Vitals

The Core Web Vitals (CWV) initiated is meant to help us quantify the experience of our sites and find improvements that will result in a better customer experience. Besides providing metrics to look after and improve, these factors are now considered a ranking signal for the Google Search algorithm.

From the CWV metrics, we will be focusing on Largest Contentful Paint (LCP). If you are interested in knowing more about these metrics, check the Web Vitals page.

LCP metric reports the render time of the largest image or text block visible within the viewport relative to when the page started loading.
https://web.dev/lcp/

The time it takes to render our website's largest image or text block depends on how fast we deliver our pages and how fast they download any additional assets that make it.

So knowing that TTFB measures the responsiveness of our websites, then the LCP is probably the most important metric we can influence from those of CWV. And that is why we are going to focus on improving TTFB in this post.

The element associated with LCP on spotify.com.

Now we know what these concepts are and how to interpret them, let's see how to measure them!

Measuring where the time is spent

Before jumping on ways to improve metrics, we need to understand the current state of our applications and where the bottlenecks are.

Knowing how to measure changes is the most important step to get confidence out of our initiatives.

It is possible to track TTFB on;

Devtools, on previewing time breakdown that highlights the value for every resource requested by the browser, including the website itself. That is present in every modern browser.
cURL, on your terminal, can tell you the TTFB of any request. There are plenty of gists on how to do it.
Using other tools/sites like Bytecheck or KeyCDN.
Application Performance Monitoring (APMs) can also help us track this from within our clients (CSR) and servers (SSR).

There are also a few ways you can track LCP;

Lighthouse is available on Chrome or as a standalone app on wed.dev and generates a report about Performance that tells you the LCP of the page inspected.
Other websites like WebPageTest will review your website and provide useful and detailed reports on areas of improvement.
Some tools, like Calibre, help us automate and track progress over time.
Application Performance Monitoring (APMs) can also help us track this from our clients and servers #2!

The problem can be anywhere in between our routing infrastructure to the application code! Thankfully these tools help us understand better where the issues lay.

My advice here is to start small and start early. Pick the tool we are currently more familiar with, or the one we find easier to start and then move on until we reached its limits!

Let's talk improvements now!

Improving TTFB for websites

CDNs are an excellent way to speed up the responsiveness of your pages, assets, etc. That is especially true when serving assets that do not change so often or rarely change. We should aim to have CDN caches on top of our fonts, images, data payloads, and entire pages (when possible).

This directly impacts several customer experience factors, more evident on LCP, as the customer will be downloading our pages much faster than if they had to reach the server.

Photo by NASA on Unsplash

Next is the data source closer to the server and the server closer to the customer!

Caching strategies are ineffective when the requests are unique or too distributed to a point CDNs will not get many hits. This scenario increases the importance of;

Having our server as close to the customer as possible, distributing our sites globally when possible.
Having our data stores as close as possible to the servers. If our pages fetch data from databases or APIs to render (CSR or SSR), then let's ensure these resources are in the same region as our servers.

Both of these strategies avoid round-trips between regions and avoid adding a lot of latency to the requests.

Improving TTFB of the assets in your websites

Occasionally we can also observe a good time spent on the "pre-transfer" phase. The DNS resolution/Handshake/SSL is part of the initial setup of a request lifecycle, and they can take a considered portion of the time of the request.

Web request time breakdown considering HTTP + TCP + TLS as per Timing web requests.

Anecdotally I often observe around 200ms spent on this phase on various sites and their respective resources.

The following rel values for the link tags are good ways to speed up your TTFB on our websites.

DNS prefetching; adding this rel to a link tag pointing to the domain you will download the resource will make the browser attempt resolving the domain before that resource is requested on the page. Effectively saving time when you actually need the resource. Example; <link rel="dns-prefetch" href="[https://fonts.googleapis.com/](https://fonts.googleapis.com/)">.
Preconnect; adding this rel to a link tag results in the DNS resolution, and also the TCP handshake, connection establishment (on HTTPS). Example; <link rel="preconnect" href="[https://fonts.googleapis.com/](https://fonts.googleapis.com/)" crossorigin>.
Preload; adding this rel to a link tag results in the browser fetching the asset while looking at that tag in the head of our documents. This will make the resources available sooner and avoid blocking or delaying the rendering! Example<link rel="preload" href="style.css" as="style">.

⚠️ Utilising DNS-prefetch or preconnect against the same website domain is ineffective because that would already be resolved and cached by the browser. So target other domains!

⚠️ Because these are all tags included in the head of our documents, if we are already preloading assets under a DNS, we are less likely to have the compounding effect of using preload+prefetch+preconnect.

⚠️ Do not preload too many assets; otherwise, we can make things worse than before! Any preloaded asset will compete for bandwidth with other resources of ours pages.

💡 Consider using both preconnect and prefetching together so while one will save time on the resolution, the other will save time on the handshake.

💡 Consider using preload for assets above the fold only to optimise LCP, for example, hero images or fonts. Additionally, consider using prefetch and preconnect for resources that live in other domains and will be requested later in the page lifecycle.

Improving TTFB on server

Reviewing the connections between the servers and other data sources (databases, APIs, ...) is important because the pre-transfer phase can take a long time there too!

This can positively impact all requests on the servers and not only initial page loads.

Request breakdown when fetching extra resources from a data source on the server

The most impactful advice regarding TTFB is to utilise keep-alive when possible.

Keep-alive is a property of an HTTP connection that maintains a connection alive after being established and used for the first time. Subsequent requests to the same destination will reuse that connection as opposed to creating new ones every time.
This is commonly supported by HTTP clients in the vast majority of frameworks and languages. For instance, in Node.js, we could do it by doing const agent = new https.Agent({ keepAlive: true });.

I hope we can see now how we can save time spent on pre-transfer protocols on every request **when utilising this.

⚠️ Worth pointing out that maintaining keep-alive connections on the server can impact load balancing and memory consumption, so there are valid reasons to keep it disabled. It requires testing!

When using HTTP/2, this will probably be handled for us when utilizing their clients, and it is even more powerful.

The impact

TL: DR; The higher your TTFB, the higher the LCP will be! However, I could not find a linear correlation between TTFB and LCP in my endeavours on page performance. For instance, in some experiments, I noticed:

A small delay in the request time, 50ms to 200ms, did not clearly affect the LCP.
A longer delay, 1s to 2s, correlated to an increase of the LCP time, but not by the same values, maybe from 0.5 to 1 second?

My personal conclusion is that chasing up improvements of < 200ms is less likely to improve LCP scores individually, but if that is an improvement on the TTFB of your website, then it is awesome!

The point is not to get fixated on the metrics! Depending on your website and infrastructure, different initiatives can yield many different results!

Ensuring we review our websites and APIs from first principles is important to identify potential improvements and deliver better customer experiences!

I hope this was useful, and I see you next time 👋

Related readings

How to store raw values with Rails.cache

Rafael Nunes — Mon, 25 Jan 2021 10:36:56 +0000

I was using the Rails cache and Redis and I quickly overflew the memory storage so I went on a small quest to better understand the Rails cache implementation. I thought it worths writing a bit about it.

TLDR; use your cache client directly or pass the raw option as true to the Rails.cache methods.

Rails provides a comprehensive and easy to use interface for caching, that is the Cache-Store. It provides a common interface to any of the standard cache implementations that Rails provides out of the box, from the in-memory cache to file, Memcached and Redis.

The cache implementation is very convenient because that allows us to store from HTML partials to Models and complex classes. The best part is that it abstracts the whole serialization so you always end up with workable entities without needing to worry about a thing.



> game = Game.last
 => #<Game id: 1, name: "Pokemon", created_at: "2021-01-14 12:10:59.872271000 +0000", updated_at: "2021-01-14 12:10:59.872271000 +0000">
> Rails.cache.write('pokemon', game)
 => "OK"
> pokemon = Rails.cache.read('pokemon')
 => #<Game id: 1, name: "Pokemon", created_at: "2021-01-14 12:10:59.872271000 +0000", updated_at: "2021-01-14 12:10:59.872271000 +0000">
> pokemon.name
 => "Pokemon"

In the example above we load a record from the Games table then we cache that entity using the Rails.cache.write method. When retrieving the cache entry with its key we end up with the same model class we were using before, and we can even call its methods and attributes as expected. That's super cool, isn't it!? But how does Rails do it?



# https://github.com/rails/rails/blob/291a3d2ef29a3842d1156ada7526f4ee60dd2b59/activesupport/lib/active_support/cache.rb#L598-L600
def serialize_entry(entry)
  @coder.dump(entry)
end

The answer is in the snippet above from the cache-store implementation, and what the @coder instance holds, it holds an instance of the Marshal library.

The marshaling library converts collections of Ruby objects into a byte stream, allowing them to be stored outside the currently active script. This data may subsequently be read and the original objects reconstituted.

Before reading or writing any record the cache-store will serialize the entry by default, and it will use the Marshal library to do so. In that way, the magic is done for us and we can read and write any Ruby object 🥳!

Simple objects storage cost

Let’s now set this learning for a moment and analyze another example. Imagine we want to store a boolean.



> Rails.cache.write('yes', true)
 => "OK"
> Rails.cache.fetch('yes')
 => true

Rails is able to store it and retrieve without any issues.

That said, we would expect the value stored in the cache to be stringified version of the boolean, right? To confirm that let’s connect directly to the storage and inspect the values there.

— In my case, I’m using Redis as the cache so I just instantiate a new instance of its client to connect directly to it.

After getting the yes value it is clear than we have much more than “true”.



> redis = Redis.new
 => #<Redis client v4.1.4 for redis://127.0.0.0:6379/0>
> redis.get('yes')
 => "\\u0004\\bo: ActiveSupport::Cache::Entry\\t:\\v@valueT:\\r@version0:\\u0010@created_atf\\u00161609929749.567886:\\u0010@expires_at0"

What ends up being stored is the serialized version of an ActiveSupport::Cache::Entry instance. The Entry class is an abstraction that implements expiration, compression and versioning of any cache record. Through this class, Rails can implement these features independently from the actual storage used behind it.

The cache entry class encapsulates whatever value we store in the cache by default. Leveraging the Marshal lib the Rails cache is capable of storing any simple/complex object while offering the cache features. That is great!

In our previous example, the serialized version of the cache entry is a String of 100 chars instead to of a 4 chars String — true. That is an extra 96 chars for storing the same information.

While for the most cases that is totally fine, what if you really need to care about the amount of the stored data?

To understand the impact of these extra chars let’s elaborate more on our example.

short detour: Redis is implemented in C and it probably needs a few extra bytes to maintain our String value which is an array of chars underneath. But let’s not consider it since that’s the same extra bytes to all String values.

Knowing we need 1B to store 1 char, in C, we can conclude we would need 100B to store the serialized version of Entry cache store.

Now for 1 million records with the value true we would need 100MB (1M * 100B). This example is “simple” and 100MB may not sound a lot but if you need to store a little bit more than a boolean, if you are using the in-memory store, or if you have limited space in Redis that can start hurting.

The Alternatives

The direct alternative I could think about was to use the Redis client directly instead of using the Rails.cache abstraction.



> redis.set('no', false)
 => "OK"
> redis.get('no')
 => "false"

It should work as expected and we are no longer utilizing the extra space for that value 🙌🏽. We are left then with the job to parse that object back to a boolean value.

Another alternative that I found after looking at the Redis cache store implementation on GitHub was to pass down the raw option.



> Rails.cache.write('yes', true, raw: true)
 => "OK"
> redis.get("yes")
 => "true"
> Rails.cache.read('yes', raw: true)
 => "true"

This option is only mentioned in the Memcached part of the docs, but that is at least also supported on Redis cache store implementation as it overrides the default serialize_entry method [1]. Similar to utilizing the Redis client directly we will need to parse the resulting string back to a boolean manually. Even though we lose the Entry features that is not a big deal if you are using Redis or Memcached since they provide most of these features out of the box.

Conclusions

Thanks a lot if you got this far!

The level of caution that this post brings to the usage of Rails cache is, most of the times, not required. However, if you ever want to cache millions of simple objects knowing some of these details can make a difference!

See you next time!

N+1 & Eager loading & Beyond

Rafael Nunes — Tue, 01 Dec 2020 01:30:55 +0000

The N+1 problem is one of the most common issues when our applications grow. That is frequently associated with ORMs because their abstractions can hide the resulting queries executed. However, it's not limited to them since we can always manually fetch data in a manner that will culminate in that problem.

Imagine we have Match, and we want to report the last 100 matches with their duration. In an ORM like ActiveRecord that could look like this:

Match.last(100).map do |match|
  Report.call(duration: match.duration)
end

Now imagine that for every Match played we have an associated Game. So besides the match itself, we want to report the game name, for example.

Match.last(100).map do |match|
  Report.call(duration: match.duration, game_name: match.game.name)
end

So even though Game is in another table that is tied to Match via the association, so Active Record will make use of lazy loading to load the required data for us. Lazy loading is handy because you can easily query related data on demand.

SELECT * FROM matches ORDER BY matches.id DESC LIMIT 100;

SELECT * FROM games WHERE games.match_id = 100;
SELECT * FROM games WHERE games.match_id = 99;
# 98 queries later...
SELECT * FROM games WHERE games.match_id = 1;

However, the problem that was introduced here is hidden in the queries level. Because we are lazy loading the games on every loop iteration that will lead to a new SQL query to the database every time. The resulting number of queries would be 1 for the matches + 100 for loading games = 101 queries —boom that's our N+1.

Eager Loading

Eager loading is another strategy to prevent N+1. The strategy consists in loading upfront any data of interest so whenever you need to access that data it would already be available in memory.

Match.includes(:game).last(100).map do |match|
  Report.call(duration: match.duration, game_name: match.game.name)
end

The code uses the includes query method to indicate what relationships we need to query alongside the Matches one, it does so by leveraging the relationship between Matches and Games. Active Record will ensure that all of the specified associations are loaded using the minimum possible number of queries. It could do a join and or an additional SQL, but no lazy load anymore.

SELECT * FROM matches ORDER BY matches.id DESC LIMIT 100;
SELECT * FROM games WHERE games.match_id IN (100..1);

Preventing lazy loading 🙅‍♂️

One alternative is to stop working with Models and transforming them into hashes, or other in-memory only entities. Having that, we can safely operate without worrying about dispatching queries, but the trade-off is that we lose that rich API and we need to re-expose any functionality attached to the Model.

Another alternative is to use tools that help us to track and identify the N+1 issues early in the process. Packages like bullet alert us when we should add eager loading to queries or when you should cache, for example. We the tools work for us but we are still reactive to alerts (on prod or dev environments).

Rails 6.1 was released with strict loading and that introduces an optional strict mode for models to prevent lazy load!

class Match < ApplicationRecord
  # attrs...
  has_one: :game, strict_loading: true
end

class Game < ApplicationRecord
  # attrs...
end

Match.first.game.name
# => ActiveRecord::StrictLoadingViolationError Exception: Match is marked as strict_loading and Game cannot be lazily loaded.

We can set up the strict_loading at the application level, the model level or association level. If we ever try to lazy load the association we will get an error 🎉 . That is great because we are proactive and we cannot create lazy queries in the first place!

Pros and Cons

The clear benefit is that we avoid flooding the data source with individual queries for every relationship inside the loop. That reduces the risk of the calls, the load in the data sources and generally ends up being more performant.

The caveat is that these single queries to all records and its relationships are not much more expensive than the ones we run on every loop iteration. So if you need to load everything at some point, then eager loading should be adequate.

Of course, that comes with a memory cost to load everything upfront. And ultimately if you in our code you end up not using all the data queried that you're loading then you might be wasting memory and slowing down some queries.

Beyond relational Eager Loading 🚀

Sometimes we need to load data that is not explicitly related in the database, that can be fetched from other data source (APIs, cache, DBs, ...) so we cannot leverage frameworks’ features like the one from ActiveRecord. However, it is possible to implement eager loading by ourselves or use other patterns that avoid N+1 in similar manners, like data-loaders.

If your process is very data-intensive or is not a web request-response you might need to look into further alternatives. We could consider caching, denormalising the data, preprocessing data, batch vs streaming processing, etc. These are all big topics that deserve much more elaboration than this post aims to do. If you are interested in these topics, I recommend Designing Data-Intensive applications which cover these topics in a great manner.

In summary, whatever implementation the principle is still the same: use abstractions to query all necessary data with the minimum amount of queries possible.

I might explore more of these topics later, but for now, this is it, see you later 👋

Reflections of five years doing Hacktoberfest

Rafael Nunes — Mon, 16 Nov 2020 02:26:04 +0000

The event has grown and I with it. I was thinking about that and decided to share some thoughts... I might change my mind later.

Five or four years ago, I had little engagement with open source and collaborating with the community in general. Despite my genuine interest in giving back, I knew little about practical ways of doing it.

Then I heard about Hacktoberfest for the first time. The idea of going beyond using and sharing open source, and actually to collaborate sounded nice, in addition to that, we would get rewards, looks great!

I am going to be open (puns intended), and I admit that the shirt was appealing to me. We can argue whether or not that's "cheap" from me, but we should agree to the fact that with the right incentives, we all get more traction.

The event over the years

The event changed the goal number of PRs a couple of times, 3 to 4, 4 to 5... I also saw multiple in-person meetups spawning so people could work together, sense of community growing! And in this year's edition, you could even plant a tree instead of getting a T-shirt you can still donate it 🌲.

Imho, they did the most meaningful change was done this year, and it came for good: the new rules. The increasing success and the lack of quality checks of the contributions laid the path to the maintainer's burden. The problem only got more significant, and the organisers acknowledged it.

The PRs now only count towards the goal if maintainers opted-in to participate by classifying their projects with the hacktoberfest topic, or if they labelled it with the specific hacktboer label, or if they approved it.

That's great at various levels, and I hope we all will see more and get a more mature format over the upcoming years.

My contributions over the years

I started by collaborating with open projects from the uni I went and research groups I was part of previously. That was sufficient to achieve that first year, but that had very little to do the broader development community.

The following years I tried to fill that gap, I contributed to the open design systems as the one from the company I was working. In addition to that, I tried to find issues related to technologies I was interested in or that I used. For example, I found some nice issues about converting React Native components out off React.createClass and removing TimerMixin, SubscribableMixin from React Native components.

⭐️ Trying to find issues that relate with you interest is a great strategy. I struggled in the beginning because I was looking for any repos, on any languages, etc. I soon realised that if I searched for something related to my skills/interests, I would be able to collaborate much more.

Another example, when I was looking into functional programming with Radma, it made sense to me to collaborate on radmda-adjunct utility functions. And when I was having fun using Gatsby, I was happy to know they were translating the docs to pt-BR, and I could jump into that.

This year

Early this year Blitz appeared with a very appealing to me with its focus on productivity, simplicity and conventions to the React world. Having worked both Ruby and JS, I always felt we were messing something like Rails for JS. Naturally, I wanted this to succeed, so I tried to collaborate with it whenever I could. Although I have not worked on any big project, I was able to chip away some issues throughout the whole year.

At the beginning of this October, the dependabot updated a gem called better_errors, and some projects I use on work started to fail. Despite unblocking my team reverting the version, I took a step further to try to find the issue, and I managed to push a fix for it. I was not very bad, after all!

Lastly, I found a great project called rubyforgood, which is a collection of open projects dedicated to making the world gooder! How cool is that? Despite my contribution to that not even counting towards the event goal, I think I found something much more valuable, and I hope I can do way more for it soon.

None of the examples above would be possible if I have not gradually been more involved with the community and comfortable with jumping around open codebases. It gets more doable with time.

Some observations

I learned a lot just by exploring different codebases and navigating the issues, but of course, tackling some of them and pushing the code changes required. All that helped me to be much more comfortable with new codebases, different stacks/paradigms, mental models, etc. And learn the way people solve various problems.

Another good thing that I thought the event created was a sense of belonging. For sure, a shirt might not be much of a big deal for a lot of people, but I soon realised that it created a sense of community for a bunch of others.

The event gradually brought every part of the community closer, and I think that is great. I started to watch various repositories, communities discussions, innovations and to filter way the desire to try re-write my apps every time a new thing popped up.

I believe there is much more space for learning and evolution on all sides of the event, and just time and practice will allow us to develop a better community as a whole.

Final thoughts

The most challenging part is to start. So if you are new to it, then start small, because small issues and small PRs will lay the path for you to get comfortable. Try to find topics that relate to your interests/skills. Share your achievements. I'm bad at this, but I feel nice when others celebrate my accomplishments with me.

Fail fast and learn quickly. Try to hold your fear of failing, the more you fail, the more you learn as well. Ultimately you get used to taking risks and learn much faster.

Let's support our community, both maintainers and users in a healthy way 🙌. Let's keep this wheel rolling. There is still much left to be done, and do not wait for another hacktoberfest to start doing it!

Lastly, be open and stay safe. See you soon 👋

Circuitbox: How to Circuit Breaker in Ruby

Rafael Nunes — Wed, 24 Jun 2020 12:05:03 +0000

A few years ago, I made a post called Hystrix: from creating resilient applications to monitoring metrics where I talked about avoiding catastrophes with circuit breakers in Java and monitoring our applications using Prometheus and Grafana.

This post focused on using Circuitbox, a Ruby gem for creating circuit breakers.

If you are not keen to read now then you can watch the video version of this post with extended examples that is available below.

Service to service communication

When building some service, it is not uncommon that we would do remote calls to APIs to perform some action. These points of connection to external services turn to be points of failure on our applications.

Downstream services help us to achieve our goals, but the more critical is that service, the more significant the impact of its failure will generate and propagate in the platform.

If any external API stops working, would your application still operate?

Circuit Breakers ⚡️

Circuit Breaker is a software design pattern that proposes the monitoring of the remote calls failures, so when it reaches a certain threshold, it "opens the circuit" forwarding all the calls to an elegant and alternative flux. Handling the error gracefully and/or providing a default behaviour for the feature in case of failure.

The pattern states a time window on what it will request that service again to check its health. When the downstream API start responding accordingly under the same thresholds, then the circuit will close and enable the main flow again.

The intention behind circuit breakers is to avoid pursuing a failure service if we already know that it is unstable and not reliable at the moment. We then can decide what to do and keep our systems operating or partially operating.

Some use cases

Fail fast: We don't wait for a timeout if we know it won't result in success.

Partially fail: When we have an option to continue with a different response from the ideal.

Best effort: We try to call the other service, but we don't care about the result, eg. Non-critical analytics.

Hands-on 🙌

What would that look to use a circuit breaker in Ruby?

The following exercise code is available on GitHub at circuitbox-example. There we have a node server and a Rails application. The node server will be the downstream service consumed by our main Rails application.

Simulating a failure ⚠️

To simulate a downstream service, we have the target-server, an express server with only the index route (/). We will be querying it from our main application.

app.get("/", function (req, res) {
  const delay = req.query.speed === "fast"  ? 50 : 200;

  setTimeout(function () {
    res.sendStatus(200);
  }, delay);
});

To facilitate our experiments, we are going to pass in the query string a parameter called speed. We'll use that parameter to simulate a slow or a fast network response.

Whenever it receives speed as fast, then the server will delay the answer by 50ms. If it gets anything else, it will delay the reply by 200ms.

The consumer 💻

In our Rails application, I've created an index route as well. It will have the same parameter as target-server that will be passed down to the remote call.

We are going to perform ten calls in sequence to our downstream service and return all the answers at once. The following code will do the work for us:

def index
  speed = params[:speed]

  answers = Array(0..9).map do |i|
    sleep(1)
    puts "Request number #{i+1}"
    HTTP.get("http://localhost:4000/?speed=#{speed}").status
  end

  render json: answers
end

We take the speed parameter, and then we map through an array of size ten doing a call for every element passing down our query param. We delay every call by 1 second on purpose, so later we can tweak the circuit configuration and see different results. Finally, we render the answers array with all the responses from our API.

The app is hitting the express server, that looks great! 🚀. Even though the requests are "slow" they are successful as we have not set any timeouts.

Changing the remote call to HTTP.timeout(0.1).get will set the timeout as 100ms and then we should see an error as the API is delaying the response by 200ms.

And voila ✨ we got our exception!
Let's keep that HTTP::TimeoutError in a note because we are going to need it later.

Adding the Circuitbox 📦

Circuitbox, a Ruby gem for creating circuit breakers.

"It wraps calls to external services and monitors for failures in one minute intervals. Once more than 10 requests have been made with a 50% failure rate, Circuitbox stops sending requests to that failing service for one minute. That helps your application gracefully degrade."

We can add that in our Gemfile as follows:

gem 'circuitbox', '~> 1.1', '>= 1.1.1'

To utilise the circuit breaker, we need to instantiate a new Circuitbox class passing at least two arguments: the server/action name and an array of exceptions.

The exceptions collection is there for counting failures, so if we get an error that is not on that collection, it will not count towards the circuit threshold. Do you remember that HTTP::TimeoutError? We are going to use it now 😁.

class TargetClient
  def initialize(speed:)
    @speed = speed
    @circuit = ::Circuitbox.circuit(:target_server, exceptions: [HTTP::TimeoutError])
  end

  attr_reader :speed, :circuit

  def call
    circuit.run(circuitbox_exceptions: false) do
      HTTP.timeout(0.1).get("http://localhost:4000/?speed=#{speed}").status
    end
  end
end

We can create a TargetClient class that will encapsulate that logic of creating the circuit breaker and making the request. On initialise, it receives and saves the speed parameter and creates the circuit assigning the target_server name and the exception we want to track.

def index
  speed = params[:speed]

  answers = Array(0..9).map do |i|
    sleep(1)
    puts "Request number #{i+1}"
    TargetClient.new(speed: speed).call
  end

  render json: answers
end

By default, the circuit will return nil for failed requests and open circuits. Then if we hit the endpoint again with speed=slow, we should expect all the answers to be nil, but no exception is thrown.

And that is what happens 🥳! Because we gave a name to the circuit, the gem can track down the requests across all the instances of it. Another cool thing it does by default is to log the status of the call and whether or not the circuit is open.

The first message indicates that we are making the request. The second one exposes the status of the request (as a failure in this case). Although all the applications failed, the circuit remained closed because we are no hitting the threshold necessary to open it.

Tweaking configs ⚙️

Circuitbox provides a set of configuration we can change to fine-tune its shape and make that fit in our needs. Some of them are:

sleep_window: seconds the circuit stays open once it has passed the error threshold. Defaults to 300.
time_window: length of the interval (in seconds) over which it calculates the error rate. Defaults to 60.
volume_threshold: number of requests within time_window seconds before it calculates error rates. Defaults to 10.
error_threshold: exceeding this rate will open the circuit (checked on failures). Defaults to 50%.

Knowing that default configuration, we can conclude that the circuit will open if within 60 seconds we get at least 10 requests and 50% of them fail. For the sake of the exercise, we can rearrange that numbers so we can force the circuit to open and see the results.

@circuit = ::Circuitbox.circuit(
  :target_server,
  exceptions: [HTTP::TimeoutError],
  time_window: 5,
  volume_threshold: 5,
)

Making both the time_window and the volume_threshold to 5 will lead to open the circuit when we get at least 5 requests during 5 seconds, and 50% of them fail. We then can try again hitting our app with /?speed=slow.

These are the logs after executing it again. If we were to look at the actual response of the Rails app, we would not notice anything different; the answers would be all nil again. However, there is some cool stuff going on under the hood.

We are still passing the slow as a parameter, and as a result, all requests should fail. After the 5th request, the gem calculates the error rate, and we get above the 50% threshold of failure. Therefore the circuit opens, and we stop querying the API and just default to the nil answer. That's why it stops logging the querying message and its status.

Watching it recover 📈

The beauty of using circuit breakers is that we avoid pursuing a failure service if we already know that it is unstable, but beyond that, we check back to see if it recovered already.

Let's now tweak our inputs to force the instability and then force a fast response.

To simulate the API recovered, we are going to change the speed parameter passed down. So we start with whatever we get from the query string, but after some requests, we change that to be fast. For example:

answers = Array(0..9).map do |i|
  sleep(1)
  puts "Request number #{i+1}"
  speed = 'fast' if i > 3
  TargetClient.new(speed: speed).call
end

In the app side of things we are keeping time_window as 5 seconds, so the interval observed is the same. However, let's decrease volume_threshold to 2, so we need to get at least 2 requests to calculate the error rate. Finally, let's override sleep_window to be 2 seconds (which by default. waits 300 seconds).

So whit a shortersleep_window we should expect the circuit will get back to the API sooner. That new configuration should look like the following:

@circuit = ::Circuitbox.circuit(
  :target_server,
  exceptions: [HTTP::TimeoutError],
  time_window: 5,
  volume_threshold: 2,
  sleep_window: 2
)

After calling our endpoint again, we get null on every answer besides the last one.

We can break down the flux of our requests as:

The first 4 requests happen within the 5 seconds window, the gem realises we hit our threshold. Therefore, it opens the circuit.
Our next attempt to request the API will pass speed=fast as we set to do that if i > 3.
Because the circuit is open all efforts during the sleep_window will be short-circuited and return null immediately.
After some time the sleep_window ceases and closes the circuit. That makes the following request to reach the API again, and as we passedspeed=fast so the request will succeed.

The actual logs tell us that story.

And that is awesome 🥳! We were able to simulate the whole process of querying an API in a bad state, opening the circuit and querying it back once everything is good!

Conclusions 🌯

A circuit breaker is a pattern that helps us to avoid catastrophes. We manage to make our applications to fail gracefully, and therefore they end up being more resilient. It helped me in past experiences on Java and Ruby projects, but there are many implementations on GitHub for different languages as well.

I'm curious about your thoughts, how do you all avoid catastrophes? Have you ever tried circuit breakers?

How I avoid the side project frustration

Rafael Nunes — Mon, 15 Jun 2020 12:24:13 +0000

I just don't do them anymore.

Okay, seriously now...

How many repositories of unfinished side projects do you have? I have a lot of them. There is no secret sauce in this post, but I realised that some methods that I already know could push me to be more productive and happy. So I'm sharing them here. 🤗

From excitement to frustration

Many times I get excited about new technologies and get in that hacker mood, I cannot rest until I try that out. Maybe I am looking into practice some skill that will be useful in the future. Or that project might be just for fun!

No matter what the trigger is, we may get motivated about an idea and want to turn that into a real thing. However, it is not extraordinary to get frustrated about that. That is very common it and happens to me quite often.

I was frustrated about the side project frustration 🤣. I started thinking more and more about that, and I decided to focus on the problems behind that occurring so often to me. Then I managed to narrow down and classify some of the issues that contribute to that feeling.

The friction of setting up a new project

We create a repository, install the dependencies, play around with the configs, then we have to wrap up for the day, never to come back to it. Or worse, we go back to it only to find out all that initial excitement was gone and we would not even know the next step anyway.

Setting up a new project is time-consuming, and I dropped various projects at this stage.

Hard to quickly get feedback on something

Given that I would have everything set up, another painful part was sharing progress with someone. How do I deploy my project? Everybody is using JAMStack now... or maybe AWS... I used Heroku before... Damn, I just wanted to show that to a friend. 😕

Sharing work in progress can be overwhelming, indeed, from choosing the "right" option to configuring everything properly. There is a lot to cover.

The undefined scope

Most of the times, I start the project without much of a plan. Frequently I would find myself doing a lot at the same time (frontend, backend, hosting) without a clear strategy and boundaries around it. So I always felt I was not getting any closer to the "end".

The point is: there is no "end" unless you define it.

Speeding up the setup and feedback loop

When I have a short time to try out something I do not want to bother that much about the settings and the infrastructure unless those are the targets of my study. I'll be probably interested in application code.

One thing that is helping me a lot is to use CodeSandBox more and more. Whenever I have an idea that I can try out by creating a sandbox, I do. I open up a new tab in the browser, select a template and start coding.

The app is fantastic, and you can choose from a wide variety of templates from GraphQL Apollo Server to Svelte. It optimises my time, so I get to focus on coding. I've been way more productive that way. 😊

I do not lose time creating the repository, installing dependencies, opening an editor, tweaking configs. It's all already there in a minute.
I can share the sandbox links with anyone 🎉. There is both the editor and the app view available to share. I got rid off thinking about deploying.

Plus it has a lot of other benefits:

Connect to GitHub and create a repository from the sandbox.
Deploy to Netlify and Vercel.
Invite others to edit a sandbox live with you.

If your side project cannot live in a Codesandbox, you can still leverage tools and services. Maybe there are boilerplates that you could use. You may expose your localhost application with Ngrok. Perhaps deploy to Heroku using its cli. You can even deploy to Netlify or Vercel using their GitHub integrations. And many more.

Defining the undefined scope

Done is better than perfect. Although it may sound a bit cliche, it is true. Getting something working helps you to build a sense of fulfilment, happiness, and why not relief about achieving the goal.

If I'm working on something in the sandbox or not, it does not matter. I realised I needed to plan to get more things done. Then I started to figure out the necessary work and set specific objectives.

In my method, I write down small enough pieces of work that I could tackle at once. They may require half an hour, an hour, or more, as long as I can understand the time they might take it's okay. That way, whenever I have spare time to work on something, I try to pick the piece of work that fits.

It's not always easy to understand the chunks of work, and that is precisely why it is so important to plan. You have the opportunity to search first, look for tutorials, read docs, and you get to learn before doing it!

I've been using a todo-list at the moment (on Notion), and the best part is that it is working! The way you decide to organise that list is always up to you. You may use a Trello board, notepads, post-its in your workstation, or even nothing at all if that's not your style. Find the tool that you are comfortable using, and that can do the job.

It all narrows down to planning. Although it may sound too much for a side project, if you can spend some time thinking about it before doing it, you will probably be more productive.

I've noticed some improvements after applying these techniques:

I'm happier because I'm always moving forward.
I know things that I could do in 10min if I want to.
I have a clear picture of all projects in progress and their next steps.
I got to practice more breaking things down into smaller units of work.
I now realise ahead of time if the project is what I actually want to do.

Conclusions

Being more intentional in planning and using tools that I am comfortable with is what is making the difference to me. The way I look and approach my side projects is different now. The techniques I use to tackle them can help you too, but you may find your unique routines as well! 🥳

So, what are your big frustrations with side projects? How are you overcoming them? Thoughts, ideas and suggestions are always welcome.

Cover by Matt Duncan on Unsplash

Loading a directory as a tree structure in Node

Rafael Nunes — Mon, 08 Jun 2020 11:36:08 +0000

Hey you all 👋! This article is the first follow up on JSCity series. If you haven't read it yet, feel free to check it out in the post bellow:

JSCity visualizing JavaScript code

Rafael Nunes ・ May 31 '20

#react #reactthreefiber #threejs #visualization

In this post we will explore:

Loading directories using node APIs.
Building a tree structure that represents the directories loaded.
Test driven development to define the expectations around the output before implementing the code.

While in the MVP of JSCity all the processing happens in the browser (file upload, code parsing, visualization), for the second version I'm aiming to create modular packages, with the intention of increasing re-usability of these modules for future versions.

In this post, we'll be building the module that loads a local directory into a well-defined structure. The objective is to be able to export it as function of a package later.

I took this opportunity to use Typescript, but you can achieve the same goal with vanilla JavaScript.

Defining the structure

Directories in operating systems are displayed and represented in a hierarchical tree structure. The tree data structure is widely used to represent and traverse data efficiently.

The elements in a tree are called nodes and edges. A node contains some piece information, in our case information about the file or directory. In the following image, the arrows between the nodes are what we call edges.

Nodes without children are often called leaf nodes and the highest node in a tree is called the root node.

There are multiple well known algorithms to traverse a tree. These will facilitate the process of building the city. So how can we make that directory tree in node?

The node file system API allows us to read any directory with fs.readdirSync, for example. It returns the array of strings representing the subfolders and files of that folder.



console.log(fs.readdirSync(initialPath));
// [ 'example.js', 'utils' ]

We can then leverage this to build our own tree structure!

I did find node-directory-tree package that does that for us. Despite that, I believe it is a good exercise to build the tree by ourselves.

To represent a node I decided to create the TreeNode class. The properties of a TreeNode are the path in the file system and an array of TreeNode (representing the sub-directories and files). When TreeNode is a file the children array will remain empty just like the leaf nodes we learned before.



class TreeNode {
  public path: string;
  public children: Array<TreeNode>;

  constructor(path: string) {
    this.path = path;
    this.children = [];
  }
}

That's a good enough first version of our tree nodes. Let's keep going.

Defining the root node

Now let's create some tests!

I will use a folder called fixtures as the input of our tests. That folder contains just some example files.

So given an initial path, we want it to return the root node representing that directory. We want to assert that the root contains the expected properties.



describe('buildTree', () => {
  const initialPath = path.join(__dirname, 'fixtures');

  it('should return root node', () => {
    const rootNode = buildTree(initialPath);
    expect(rootNode).not.toBeNull();
    expect(rootNode).toHaveProperty('path', initialPath);
    expect(rootNode).toHaveProperty('children');
  });
});

For now this test will fail, but that's expected. We still need to build the function mentioned in the code above.

The buildTree function receives a path as input and returns the tree structure for that directory.



function buildTree(rootPath: string) {
  return new TreeNode(rootPath);
}

That is enough to get our first test to pass ✅🎉

Reading the folder and its children

We can see that the buildTree function does not really build the full tree structure yet. That's our next step. The fixtures folder used by our test looks like the following.



fixtures
├── example.js
└── utils
   └── sum.js

The output of the function should represent the following tree.

We can assert that the root, in our case fixtures, has two children: utils folder and example.js file.



it('should return root node with its exact 2 children', () => {
  const rootNode = buildTree(initialPath);
  expect(rootNode.children.length).toEqual(2);

  const childrenPath = rootNode.children.map(child => child.path);
  expect(childrenPath.includes(`${initialPath}/utils`)).toEqual(true);
  expect(childrenPath.includes(`${initialPath}/example.js`)).toEqual(true);
});

We can also assert that utils folder has the sum.js file inside of it.



it('should add utils node with its children inside root', () => {
  const rootNode = buildTree(initialPath);
  const utils = rootNode.children.find(
    child => child.path === `${initialPath}/utils`
  );

  expect(utils).not.toBeNull();
  expect(utils?.children.length).toEqual(1);
  expect(utils?.children[0]?.path).toEqual(`${initialPath}/utils/sum.js`);
});

And of course, they are going to fail at this point.

Building the tree

We now need to extend buildTree so it builds the entire tree, not only the root node.

The Depth-first search aka DFS algorithm is a well-known technique to traverse a tree. In the iterative DFS algorithm we will need to use a Stack, which has the first-in-last-out (FILO) approach.

With DFS, our step by step looks like this:

We first add the root to the stack.
We loop while the stack is not empty (that means we still have nodes to visit).
We pop an item from the stack to be our new currentNode.
We use fs.readdirSync(currentNode.path) to get the node's sub-directories and files.
For each one of them, we create a node and add it to the currentNode.children array. If it's a directory we also push it in the stack to visit it later.

In the end, we've visited all the directories, files and sub-directories and built our tree. The implementation looks like the this:



function buildTree(rootPath: string) {
  const root = new TreeNode(rootPath);

  const stack = [root];

  while (stack.length) {
    const currentNode = stack.pop();

    if (currentNode) {
      const children = fs.readdirSync(currentNode.path);

      for (let child of children) {
        const childPath = `${currentNode.path}/${child}`;
        const childNode = new TreeNode(childPath);
        currentNode.children.push(childNode);

        if (fs.statSync(childNode.path).isDirectory()) {
          stack.push(childNode);
        }
      }
    }
  }

  return root;
}

We used fs.readdirSync as before to discover the children of a folder. We also used fs.statSync to read the stats of the current path, it allows us to ask whether or not that child I'm looking at is a directory.

Green tests, yay 🙌, we have solved the problem of building the tree structure! When we log our root we are able to see its properties.



TreeNode {

  path: 'test/fixtures',

  children: [

    TreeNode {

      path: 'test/fixtures/example.js',

      children: []

    },

    TreeNode {

      path: 'test/fixtures/utils',

      children: [Array]

    }

  ]

}

What's next?

We got the desired output, but there is more we could do. For example, we can add a filter to exclude files of certain extension from our tree. I'll do that since I want to visualize .js files only.

There is also the possibility of adding properties like type, extension, size (...) to our TreeNode.

The next chapter will leverage this newly created structure to parse every JavaScript file in it and compute metrics about the code!

Was this post useful to you? I'm always keen to hear suggestions and comments. 👋

JSCity visualizing JavaScript code

Rafael Nunes — Sun, 31 May 2020 12:53:37 +0000

This is the very first article that talks about the idea, motivation and the mvp of JSCity.

I learned a lot while doing it and hopefully you will also find something interesting to take out of it as well.

react-three-fiber

So, late last year I started creating JSCity. The ultimate goal was to visualize JavaScript projects as cities. But why?

It all started when I saw the following tweet by Paul Henschel.

// Detect dark theme var iframe = document.getElementById('tweet-1184586883520761856-965'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1184586883520761856&theme=dark" }

My reaction was: "Wow! That's really cool and it's built with React, how?!"

The answer was react-three-fiber. I was amazed by the project 🤯. It is a React reconciler for Threejs, and I got really curious to see what it does.

On one side there is React, a very popular and robust library to build UIs. Because of its declarative nature React is really good for a lot of things and the community is always pushing the ecosystem forward.

On the other side, there is Threejs, the most popular 3D library for JavaScript with a very powerful and rich API.

Although it is very possible to combine them together the Threejs imperative nature makes that a non-trivial work. For example, synchronizing React state with the 3D canvas can be painful.

Now let's take checkout this sandbox. Feel free to play around with it.

react-three-fiber builds the bridge between the composable and declarative React nature and the powerful API from Threejs.

A lot of initial setup and complexity is abstracted. However, the main part is that it exposes a very good API, handy hooks and maps objects from Threejs to React components.

Now we can leverage of the best of these two different universes.

Matching an intention with an idea

I immediately wanted to try it. But what should I do?

I made a few examples using react-three-fiber on CodeSandbox, but I wanted to continually explore and build something bigger.

I've used Threejs in the past to build a project called SwiftCity (no longer maintained) - a visualizer of Swift code. Then it clicked 💡! I can bring that same idea of visualizing code as cities, but this time applying to JavaScript universe.

I would also be able to explore some other interesting topics like react-three-fiber, ASTs, babel, etc.

Besides, 3D things are so cool, right?

JSCity

So JSCity idea came to visualize JavaScript code as cities. My intention was to build a demo to get a sense of how that would look like.

Explaining "The City Metaphor"

To summarize, the idea behind City Metaphor is to analyze and view software systems as cities. The key point is to explore and understand the complexity of a system by mapping the source code to a city.

The concepts

Before rushing to implement the MVP we have to define how to translate JavaScript code into a city. For example, cities have buildings, right? And also blocks. So here are the building blocks that I've chosen for our city:

What piece of code does a building represent?
How do we define the dimensions of a building (width, height and length) ?
How do we show the code hierarchy as areas of a city?

Azures City Topology from Visualizing Software Systems as Cities

The buildings in the city

In the original metaphor, a building was mapped to represent a Java class. However, various elements can own a lot of responsibilities in JavaScript.

For instance, the buildings could be Functions, Classes, Objects, etc. Beyond that, functions might appear as IFFEs, arrow functions, closures, function expressions and more.

I decided then to only consider simple function definitions and its clojures for the purpose of the demo.

Dimensions

Several metrics can be taken to define the measurements of a building. I decided that the building height would be given by the number of lines of code of the analyzed function. The width and length then would be defined by the amount of calls to other functions inside the examined function.

Topology

The city topology is mapped to elements of the system hierarchy.

Since there are no packages, namespaces or anything equivalent in JavaScript, the mapping will limit to the following levels: the project, directories and the files.

function sum(a, b) {
  return a + b
}

function calculate(a,b) {
  function log(text) {
    console.log(text)
  }
  log(sum(a, b));
  log(minus(a, b));
  log(times(a, b));
}

function minus(a, b) {
  return a - b
}

function times(a, b) {
  return a * b
}

The code above would look something like this:

Function definitions that belong to a file will appear inside the file limits. In the image above, the light grey area represents a file and its functions are the buildings.

Function declarations that are declared inside another function (clojures) will have their own block stacked on top of the building that represents their parent function. We can see that the largest building represents a function that has a clojure inside of it.

Building the MVP

Even having previous experience with the concept and knowing more or less what I would need to build, I still wanted to keep it minimal at first.

I will not go into implementations details here. But do not worry! The next posts will be really focused on exploring every part.

In summary, the steps that I took were:

Created functions where I could read the content of a JavaScript file and parse it to get its AST. For that I've used babel-parser.
Coded something to navigate the AST and collect the necessary data from the functions. Instead of using tools like babel-traverse for this, I actually implemented it myself (and I regret it 😅)!
Implemented an algorithm to create the city grid and place the buildings in the right place from scratch. Although I still have the code from SwiftCity, I can barely understand it anymore 😬.
Used react-three-fiber to read the city definition and to render the city.
Used Reactto build the app and handle the input file that would be imported.

The first version

I made it in the end 🎉! The live version is available at JSCity and the code is on GitHub as well.

// Detect dark theme var iframe = document.getElementById('tweet-1202165153866715136-242'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1202165153866715136&theme=dark" }

There is a lot that this first version does not cope with. For example, as I opt in to just consider function definitions a lot of modern JavaScript code will not be represented. One example is functions defined using the the arrow notation.

Some conclusions

I got inspired and could not rest until trying out react-three-fiber. All because of a tweet. And that is a lesson to me:

Share your work whatever that is. It may inspire someone.

My initial intention was to focus on experimenting with 3D through react-three-fiber, but what ended up happening was me spending most of the time trying to get a good enough city creation algorithm... That was hard! Another lesson here was:

Choose a project that will let you focus on what you want to learn.

Nonetheless, it was really fun to build it: I got to play around with other nice tools like babel-parser.

What is next?

I got it working. Now I want to make it better.

The code is very limited and fragile at the moment. I want to extend JSCity and be able to load a directory and build the entire city from that.

From now on I will be diving deep into each part of the implementation one at the time. I'll be sharing it through posts and I hope some of these things are interesting to someone else too!

Let me know what do you think about the idea. Thoughts, suggestions and comments are always welcome. See you in the next chapter.

Feature Flag approach with GraphQL and React 🕹

Rafael Nunes — Mon, 25 May 2020 03:51:35 +0000

Feature flag (or feature toggle, feature switch…) comes with different shapes and implementations, however, is a well known and powerful technique for allowing teams to modify system behaviour without changing code.

The idea is to be able to enable or disable features during execution time without any deploy. That is a powerful tool with various implementations across different languages, the applications are many: A/B testing, toggle app configuration, delivery new features gradually, etc.

Storage

While having feature flags is very handy they introduce complexity starting by the management of the flags. That is one of the reasons why you will find managed services like Optimizely, Rollout, and others. In addition to the feature, they offer a lot more like analytics, and targeting.

It does not mean that you need a third-party app or integration to start using feature flags. In fact, every tool and approach should be considered depending on what do you need at the implementation moment.

You may opt-in for a managed service or manage your own feature flags in your own database as well.

API

So once you have decided how to manage the flags we need to expose them in our GraphQL API. The objective is always to strive for making your schema self contained and easy to understand, ideally, it should not reflect the way it is stored in the database (although it can).

We want to expose the features available for some user, app or instance. A query that provides that information could look like the following:

type Query {
  enabledFeatures: [Feature!]!
}

type Feature {
  name: String!
}

In the schema above, we are defining two important units in our domain, they are:

Feature and enabledFeatures. Feature is a representation of the feature you want to switch on and off and it only contains a name at the moment.
enabledFeatures is a query that returns an array of Feature.

We only return the features enabled so whoever is consuming the API does not need to know the entire set of features. The lack of some feature in the array means that the feature is not visible/available.

Note: In the backend, you can identify the user through headers such as Authorization and filter features for that user. Or filter based in any other information in the request, for example, User Agent.

You can see this schema being served live on this API sandbox. I'm using Apollo Server in the example.

Querying

Having the contract defined we are now able to fetch features. You can play around on the playground built in the sandbox example.

query {
  enabledFeatures {
    name
  }
}

In the React application, I will be using Apollo Client as I'm familiar with the API, but it does not matter the library you use. You can follow along with the implementation of this client sandbox.

A component that queries all the features would look like the following:

const QUERY = gql`
  query {
    enabledFeatures {
      name
    }
  }
`;

function BasicQuery() {
  const { loading, error, data } = useQuery(QUERY);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error :</p>;

  return (
    <div>
      <h2>List of features:</h2>
      <ul>
        {data.enabledFeatures.map(feature => (
          <li key={feature.name}>
            <p>{feature.name}</p>
          </li>
        ))}
      </ul>
    </div>
  );
}

Having that is a good start point, right know you already have a way to query all the features and you can make use of it to dynamically turn something on and off. So let's make that.

useFeatureFlag

I want to guard a component so every time the user hit that part of the code we only render it if the feature is enabled. To avoid writing this logic over and over again I'm going to build a hook (previously I've used render props, but you can also make it a HOC component, you can work with whatever suits you prefer). The hook gets a feature name it checks if that is enabled and returns the status to the caller.

function useFeature(name) {
  const { loading, error, data } = useQuery(QUERY);

  let feature = {
    loading,
    error,
  };

  if (!data) return feature;

  const enabled = data.enabledFeatures.some(feature => feature.name === name);
  feature.enabled = enabled;

  return feature;
}

That hook uses the same query we used before and it will return whether or not the passed name is present in the list of features, as well as loading and error state if you want to handle the intermediate states. We can now use it in any component to switch the render output depending on it.

const Feature3 = () => {
  const name = 'feature3';
  const feature = useFeatureFlag(name);

  if (feature.loading || feature.enabled === undefined) {
    return <p>Loading {name}...</p>;
  }

  if (feature.error) return <p>Error :</p>;

  if (feature.enabled) {
    return <h2>{name} is enabled.</h2>;
  }

  return <h2>{name} is disabled.</h2>;
};

If we have only feature1 and feature2 enabled when querying feature3 we should see the disabled message. Similarly, if we query feature2 or feature1 we should see the enabled message.

Caching and better UX

Although our useFeatureFlag is enough to define if a feature is enabled, it queries enabledFeatures when the component is mounted. Depending on the application and the goal of your flag it can decrease the user experience because the user will have to wait for the query to finish.

Thankfully Apollo Client comes by default with an in-memory cache implementation! Knowing that we deduce the useFeatureFlag will be slower only on its first execution. After that, the result will be cached. However, we can go further and cache it ahead of time.

We can implement a pretty similar component to the BasicQuery what would follow the same principles as useFeatureFlag, but it is not concerned about any specific feature. It is only worried about querying them and rendering the children.

function FeatureFlags({ children }) {
  const { loading, error } = useQuery(QUERY);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error :</p>;

  return <React.Fragment>{children}</React.Fragment>;
}

You may customize the way you render by ignoring the loading state or error, depending on your needs.

It works like context providers and you could indeed use the context API to create a provider to share its features and consume them with hooks. But this approach may be good enough as well.

FeatureFlags could be placed in the top of your component tree or would wrap a portion of your App that can be controlled by the feature flags.

const App = () => (
  <ApolloProvider client={client}>
    <FeatureFlags>
      <div className="App">
        <h1>Hello Feature Flag</h1>
        <section>
          <BasicQuery />
        </section>
        <section>
          <Feature2 />
        </section>
        <section>
          <Feature3 />
        </section>
      </div>
    </FeatureFlags>
  </ApolloProvider>
);

This approach is not sophisticated, however already have some advantages like saving network calls being fired on every useFeatureFlag. Which also avoids the pending state in every guarded component. The trade-off here is to slow down the overall load in favour of the later dependants rendering way faster.

The cache consistency can be a problem if we change the feature in the backend, but the user already cached the queries. For working around that you may extend the hook to receive a fetch policy option. Apollo allows you to configure the way you interact with the cache and you can opt-in for network-only, for example. Nevertheless, the in-memory cache only lives until the page is refreshed it might not be that critical depending on your use case.

What is next?

That is my initial take when thinking about feature flags with GraphQL. The possibilities are many and as I wrote several times in this article it will depend on your use cases! So make it better work for you.

In my perception potential extensions would be:

Adding options or variations as a field of Feature, then you can branch the feature implementation depending on its variation or properties (aka A/B testing).
Making the components and hooks more generic accepting the query as props to them.
Adding a new query, featureEnabled to query the enabled status by the name directly from the backend so you do not have to filter it in the client-side.

What is your take on feature flags? 😊🙌🏽

cover image by Mikkel Bech on Unsplash
This post is a complete rewrite of feature flag approach for react using apollo client. I felt it needed an update.

Multiple Apollo Clients in React

Rafael Nunes — Fri, 09 Aug 2019 01:22:15 +0000

This is a review after one year of Apollo Multiple Clients with React?. I took a time to rewrite it, adding community implementation suggestions, Apollo Federation, etc. Realised then that I could share my humble knowledge here as well.

This quick post explains how to use different Apollo clients in the same React application, but in the end, discuss other approaches when working on multiple GraphQL APIs. This is not intended to question the GraphQL philosophy by any means 😝!

I wrote this because I found myself questioning how could I use multiple clients to query different GraphQL APIs from my React application. It turns out there were lots of issues in Apollo GitHub project, discussing the need and presenting suggested implementations for it.

TL;DR: passing any ApolloClient instance to Query/Mutation/Subscription components as props works just fine! Check: https://github.com/peaonunes/apollo-multiple-clients-example

Some links to related issues, discussions, and proposals are listed below. Some of the old proposals indeed were merged and come along old react-apollo versions. However, the approach to using the Apollo client and querying changed a lot (for better) since 2.1.

Why would we need multiple Apollo clients?

Apollo Client accepts only one client uri on its initialization, therefore, it is meant to be used with one client at the time.

import ApolloClient from "apollo-boost";

const client = new ApolloClient({
 uri: "https://48p1r2roz4.sse.codesandbox.io"
});

So if in your React application you need to retrieve data from two different GraphQL services, for example, you cannot use the same client or provider instance.

In my case specifically, I was just looking for a quick win implementation approach to get data from two GraphQL APIs to validate a solution. I was not worrying too much about schemas collision since the types, cache, state (...) would not overlap.

In my scenario, it would make sense to have a way of switching clients when querying APIs on Apollo. In the current approach though, you wrap your entire application with the ApolloProvider component which passes the client for the application through the context.

import { ApolloProvider } from "react-apollo";
import ApolloClient from "apollo-boost";
import { render } from "react-dom";
import React from "react";

const client = new ApolloClient({
 uri: "https://48p1r2roz4.sse.codesandbox.io"
});

const App = () => (
 <ApolloProvider client={client}>
 <div>
 <h2>My first Apollo app 🚀</h2>
 </div>
 </ApolloProvider>
);

render(<App />, document.getElementById("root"));

That actually makes it simple to query data using the Query Component, but it also means that the client provided via context is the only used when querying.

⭐️ First Solution

I spent some time looking through numerous issues and related projects and it turns out that there is a way of overriding the context client for Query and Mutation component passing another client through props 🎉 🎉 !

Update Aug 2019: Although they have changed the implementation it still works. https://github.com/apollographql/react-apollo/blob/master/packages/components/src/Query.tsx#L17

 <Query client={anotherClient} query={query}>
 {({ data }) => (<div>{data.name}</div>)}
 </Query>

This feature is not mentioned in any part of the official documentation. We can indeed pass any client for the components that they will give preference for the one passed via props order than via context. So we could make:

// ...
const customClient = new ApolloClient({
  uri: "http://other-api/graphql"
});

const Dogs = ({ onDogSelected }) => (
  <Query query={GET_DOGS} client={customClient} >
    {({ loading, error, data }) => {
      if (loading) return "Loading...";
      if (error) return `Error! ${error.message}`;

      return (
        <select name="dog" onChange={onDogSelected}>
          {data.dogs.map(dog => (
            <option key={dog.id} value={dog.breed}>
              {dog.breed}
            </option>
          ))}
        </select>
      );
    }}
  </Query>
);
// ...

I have implemented a runnable example that uses two different clients in this repository: https://github.com/peaonunes/apollo-multiple-clients-example

Even though this approach is functional you should keep in mind that you won't have Apollo features running applying for both clients unless you pass the same cache to the clients (that might be a risk in case of schema collision), manage other features will be by your own. Apollo features will get compromised and as the application grows your codebase becomes thicker and development will probably be slower.

What would be the ideal approach then?

Solving the problem in the Frontend

Some people found the original article on medium and beyond discussing the approaches they have come up with their implementations for solving this issue.

Community implementations

Michael Duve, wrote react-apollo-multiple-clients a packaged that allows you to switch between clients. It considers multiple providers and provides you a HOC component that accepts a client prop to switch to the desired client consumer. Discussion

Paul Grieselhuber, suggested in his post a way where everything worked through a single client and allowed you to simply toggle on context to select a uri where the client will dispatch the requests. You can follow the discussion here.

Client-side schema stitching

Despite support for server side, it is not common to see people trying to solve the issue right on the client, there are some issues looking for or requesting stitching on client side, #797 for example.

The company Hasura, though, points out a way of client side schema stitching and it might be sufficient in your case.

Although I think that these approaches solve the problem I also think they can increase so much the complexity of the frontend application as the application grows. From my point of view, the work should be done on Backend by providing a unique interface for all the different APIs.

Gateways for Frontends

API Gateway is a known pattern with increasing adoption in our "microservice boom" age. API Gateway is a single interface between the services and clients.

It seems to be a consensus in the GraphQL world as well that the API Gateway is the way to go on connection with different GraphQL APIs. However sometimes going beyond that, since the Gateway itself can create a GraphQL interface for other REST and RPC APIs.

The real problem of serving different APIs through a unique gateway is how to manage and orchestrate different schemas.

Schema Stitching

The first attempt the Apollo team advocated for was Schema Stitching.

Schema stitching is the process of creating a single GraphQL schema from multiple underlying GraphQL APIs.

After some time of development and feedback from the community this approach was considered fragile and it is now deprecated.

Apollo Federation

Apollo recently launched a new concept for solving this problem of managing different schemas through a gateway which is called Apollo Federation.

"Apollo Federation is our answer for implementing GraphQL in a microservice architecture. It’s designed to replace schema stitching and solve pain points such as coordination, separation of concerns, and brittle gateway code." James Baxley III

They have launched the Federation spec before and it already counts with implementations in some languages, apollo-gateway, for example. The idea is to have a gateway that composes the schemas and the federated services can connect with each other through keys (just like primary keys) and they are also able to extend types. All this just using regular GraphQL spec.

I recommend taking the time to watch the video below and spend some time playing around with this promising approach.

Apollo Federation - A revolutionary architecture for building a distributed graph

I personally tried it and I am seeing companies working on solutions based on this new approach. It is also notable that there are some challenges and space for other discussions like managing authentication/authorization, how flexible the gateway should be, etc. Hopefully, the Federation get evolving based on feedbacks from the community and companies.

Conclusion

As I mentioned before this post is not about questioning the right way on querying multiple GraphQL APIs, but it is about pointing out approaches that hopefully might be enough for solving the issues of today.

I think the whole discussion about using API Gateways and managing different GraphQL schemas is just at the beginning and the community will continuously work on better solutions.

I am more than happy to read suggestions and engage discussions so leave your thoughts below.

An introduction to the container world with Docker

Rafael Nunes — Mon, 29 Jul 2019 02:14:41 +0000

This is a repost from my 2017 article on medium. Although today Docker is substantially more known topic as it was before I think it might be good to let the basic knowledge I shared in this post accessible in the dev.to platform as well. I took the opportunity to update the post and refine it though. So if you are new to it, come along and enjoy =)

An introduction to the container world with Docker

What will I achieve? By the end of this article, you will understand the core concepts of Docker, such as images, containers, Dockerfiles, using it along with useful docker commands. And comprehend why it is good for production and development and will be able to run your applications using Dockerfile and Docker Compose.

At this time you probably heard someone talking or read some article that cites Docker. But what is it all about? Why should I use Docker? And why is it good for both dev and production systems.

Why use containers?

Imagine yourself having two different services (1 and 2) running in the same host machine at AWS, they have the same technology dependency, both is running under the framework v2. Right now you have to upgrade the service 1 to the new version framework v3, because it integrates with the monetization platform of your company.

So you have to enter inside your machine running at AWS using command line tools and now you update the framework! Unfortunately the service 2 is not compatible with this new version and everything starts breaking! You can rent another machine on AWS, enter in it, copy all the files of service 2 and install the older version of the framework, now it is running fine.

However, is this mean time the team had another version of the service 2 and you just installed the older one because you have copied the wrong code base! The process starts over again! Isn't it getting boring?

When it comes to provisioning machines and configuring dependencies to run some application there are some options. Tools such as X allows you to write infrastructure as a code and automatically configure and deploy machines and related. We can go beyond that though.

Using cloud services or not hosting, delivering and running services add some relevant concerns like:

How do I guarantee a stable environment for my application?
How do I manage the environment configuration of my application?
How do I scale and upgrade my service efficiently?
How to isolate my service dependencies from the others?

Containers

Containers are not a new concept, used since early 30's to the actual patent in 1956 by Malcom McLean. The need of shipping different packages of products with different constraints (size, dimension, weight…) came to the standardization of a shipping model called container.

Metaphors aside, in the software production world we find the same needs. And here comes the Software Container, something that bundles the software product and manages its configuration for shipping.

Docker

Software Container is not a new concept too, but working on it is a hard low-level job for most of the engineers. Docker, however, turns out being a fast, easy to use, and powerful tool for containerization of your software.

Using Docker you define images which are descriptions of a software environment settings and commands. And from those images, you can run containers which are the actual executable bundle.

How does the docker work?

Docker runs under the host system kernel, the containers contains only user space files and all resources, configuration needed, libs, dependencies and executable commands are defined through images which are light and easily adaptable for different purposes.

Differently from VM's, Docker does not emulate the entire OS on the host machine and that is why is so light compared to VM. The Docker Engine works like a middleware managing the containers process along the host OS. The containers with Docker only loads the necessary bins/libs (and the app obviously 😛) for your App to run.

The goods come are notorius when you start using.

Resource efficiency: You are able to configure disk space, memory usage, libs and bins to load of your container. Being able to create the lightest and efficient environment for your app.
Compatible: Compatible with Linux, Windows and MacOS distributions.
Easy to run and fast: Easy installation, command line tools use and optimizations of the building and run containers.
Software maintenance: Release new versions changing the containers and guaranteeing the right environment.
Scalability: Scale your service replicating containers as long as your traffic is heavy and turn some down when it is not so bothered.
Security: The containers are isolated from the host machine, so it can't access anything outside its own boundaries.
Reproducibility: The containers are a well defined environment and you can guarantee the same infrastructure over a set of definitions.

Hands on! 🙌🏽

Let's try out using Docker now! Installation: On Install Docker you will find the instructions for your correct system. There are dist for Mac, Windows and Linux dists.

Once you have the docker installed and running on your machine jump to your terminal and hit docker -v for checking your docker version. Now try run the following:

$ docker run -it alpine sh

This command says to docker run in interactive mode, -it flag, the Linux Alpine and runs the sh command. So as you probably does not have the alpine image on your machine the Docker will download it before running.

If everything went well you should be on the sh shell mode of the alpine. That’s right, you are on a terminal of a Linux running inside a container in just a few seconds! Try ls for checking the files and folders.

Now type exit and you are done. You will exit and stop the container.

Note: The Docker was built for Linux and it's now native for Windows too. However, on Mac, it still has to run a VM in the background for emulating the host. It is still much lighter than using VM's for all the job.

Images

You might asked yourself on how does the Docker know about alpine and where did he get it from. The alpine comes from this repository on DockerHub. DockerHub which is a repository of container images. Users and organizations can publish their official docker image of their [software, language, system, OS, …].

DockerHub is the GitHub of containers. You can pull some image for starting a containers like you pull some code on GitHub to run. The daemon looks for the image in the host machine, if he does not find it then he looks for the image on the DockerHub.

Using a Dockerfile you can start from a very basic image definition and create layers over it, describing the next steps of the image execution. Doing that, you can be incremented and adapted to your needs.

Dockerfile

Clone the following code for ease the next steps. Download here. There are two folders holding two different applications one called node-service and the other is webapp. Let's start with webapp, create a new file called Dockerfile at the webapp folder.

I recommend the reading of the documentation for more details.

The first thing we set on a Dockerfile is the starter image from our app. In this case, the webapp is a React application so an environment with Node.js installed is fine for us. Thankfully there is an image on DockerHub for that.

FROM node:6.3.1

This command says that from the starting image node:6.3.1 do the rest. This image contains the Node.js version 6.3.1 installed under a Linux distribution. Let's continue writing down others commands:

FROM node:6.3.1

# Run a command for creating the following path on container
RUN mkdir -p /usr/web-app

# Sets the work directory of our app to be the new path
WORKDIR /usr/web-app

# Copy all files from current directory to the new path in container
COPY . /usr/web-app

# Run the command for installing our node dependencies 
RUN npm install

# Define the command that will execute when the container start
CMD npm start

Now that we have our file set. Let's run the application inside the container.

$ cd webapp
$ docker build -t web-app .

It might take some time to download the image of Node Running the build builds the image based on the Dockerfile present on current (.) directory. The -t is a flag for tagging this image and name it web-app.

$ docker images

Your web-app image should be listed. Now let's run our app!

$ docker run -d --name web-app-container -p 3000:3000 web-app

The docker run your container in a no interactive mode by the flag d, it then names your container with --name web-app-container, and also maps the port using -p (format is port-on-your-machine:port-on-the-container). And use our image named web-app for that. Try to go for your browser on http://localhost:3000.

The React app is running inside the container on localhost:3000. This port on the container is mapped to our host machine so we can access the application.

The webapp dependes on some data from the node-service so as you can see an error message is displayed on the place for id and name❗️

$ docker ps

The command above lists all the containers that are running at the moment, try -a for display all containers created. Now we can see that it's really running if you aren't sure yet try to stop the container and reload the browser!

$ docker stop <container-id-listed-on-ps>

Let's move to and start the node-service application. Go to its root folder and create a new Dockerfile for this service. As it is a node application it will be pretty much the same.

FROM node:6.3.1

RUN mkdir -p /usr/node-service

WORKDIR /usr/node-service

COPY . /usr/node-service

RUN npm install

CMD npm start

Let's build and run the node-service container, then reload the webapp!

$ cd ../node-service
$ docker build -t node-service .
$ docker run -d --name node-service-container -p 8080:8080 node-service

Perfect! Your containers are now running and talking to each other! ✅
If for any reason you need to delete an image or a container built use:

Images use $ docker rmi <containerID>
Containers use $ docker rm <containerID>

It might be useful to run your container in interactive mode to debugging or doing work on the container environment, in this case use -it flag on docker run.

However, if you want to enter in the container on bash, for example, and your container is already running go for:

$ docker exec -it <containerID> bash

You can try all these commands above in the container we just created.

⭐️ Now you know a little bit of containers using Docker and already ran it for real! That's great! There are only a few more topics that I want to go through.

Right now I recommend you to take a cup of coffee ☕️ and relax before continuing.

Docker Compose

Docker Compose is a tool that came installed along Docker and is useful on the orchestration of different containers. The point is to let your Composer manage the build and the run all of yours projects.

Container orchestration is the next level for managing our services lifecyles. We are able to manage and control enumerous things like: Load balancing, Redundancy, Resources allocation, Scale up and down the instances, etc.

The Docker compose is the defualt format to use along Docker Swarm orchestrator.

However, we are able to try it in our project that we just made! We just have to create the docker-compose.yml file!

Access the root folder intro-docker-examples of your project and create the docker-compose.yml file. Let's now configure it properly.

In this file, you have to define our apps under the services property. We are going to define first the webapp.

version: "2"
services:
  webapp:
    build: ./webapp
    ports:
      - "3000:3000"
    depends_on:
      - node-service

We defined above the webapp service with the build instruction for build the project folder (it will look for our Dockerfile), the map of the ports as well as we did early in the commands and we are saying that for this service to run it depends on the node-service so the docker compose will run the node-service first for guarantee this dependency.

version: "2"
services:
  node-service:
    build: ./node-service
    ports:
      - "8080:8080"
  webapp:
    build: ./webapp
    ports:
      - "3000:3000"
    depends_on:
      - node-service

So we defined now the node-service as we did for webapp. The version defines the type of the docker compose configuration and this template is related to version 2!

Stop now the older containers if they are still running and remove them using the commands I showed you before. And now we could see the Docker Compose building everything again. From the command line on the root folder go for:

$ docker-compose up

This will create new images for your projects, build the containers and run them on an interactive view. You will now see the logs from the services.

Access the http://localhost:3000 and check now that everyhing is working fine!

For stopping the containers go to another tab on your terminal, navigate to the folder and run the command below. It will stop each container in order.

$ docker-compose down

That's great! Everything working fine, but what does will happen if I have to change my Dockerfiles definitions? If you are using the docker-compose then simply run:

$ docker-compose up --build

In case you made editions to your Dockerfile you can use the flag -- build` to force rebuild the images and containers. The rebuild of any docker container uses cached steps for optimizations. That means the docker only rebuilds the steps from the step changed to the final.

The final files of this implementation are available here.

Docker beyond production

Using Docker for production deployment is a reality and has a lot of benefits. However, using Docker under the development environment is also a good practice.

Defining the configuration and dependencies of your project on a Dockerfile sets correctly the environment to anyone who is going to work on your project! This avoid issues dependencies related to host and libs versions and allow your the host machine environment to stay clean.

For example, you can spin up a local database such as postgres or mongodb in a container and make your application locally connect to it instead of having this installed in your computer.

A good tip for devs is look for volumes. This creates a channel that enables synchronization between a folder inside the container and the host machine. So if you write your code on the host machine it will be synced to the code in the container.

Some languages and applications, like in webapps, have the capable of hot reload. So as long as you code from your host machine you can see the changes being compiled and ran into the container. But if your technology does not have this function you can open a terminal tab to enter in the container and recompile/run the project as well.

You can also use Docker in your CI/CD pipelines building docker images to run test over and publishing them if it is healthy.

The end?

Actually it is the beginning of our journey using Docker! There a lot to learn and practice! Look forward more topics and concepts of Docker.

As Kubernetes became really popular, is the most popular container orchestrator in the block. The next step for you is definetly explore the endeavors related with container orchertration!

If this article helped you somehow please leave your appreciation ❤, if it did not fulfill your expectations please send your feedback ✉️ and always share your thoughts in the comment section below 📃!

See you next time =]