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.

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.

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;

1. Having our server as close to the customer as possible, distributing our sites globally when possible.
2. 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.

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.

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

• Time To First Byte, Improve server response time
• Core Web Vitals
• Timing for bringing page experience to Google Search
• Largest Contentful Paint (LCP)
• Previewing time breakdown, cURL
• Timing web requests
• Content Delivery Network, Page Rendering
• Using NS-Prefetch, Using preconnect, Link preload
• HTTP Keep-alive, Disadvantages of keep-alive

Originally published at https://peaonunes.com.

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 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!

Originally published at https://peaonunes.com.

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!

lass 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 👋

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.

2020 edition

Early in 2020 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 👋

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.

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:

1. The first 4 requests happen within the 5 seconds window, the gem realises we hit our threshold. Therefore, it opens the circuit.
2. Our next attempt to request the API will pass speed=fast as we set to do that if i > 3.
3. Because the circuit is open all efforts during the sleep_window will be short-circuited and return null immediately.
4. 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?

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 optimizes 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 boilerplate 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.

Did you like this post? Read the original one and more at https://peaonunes.com.

How I avoid the side project frustration

JSCity visualizing JavaScript code

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:

1. We first add the root to the stack.
2. We loop while the stack is not empty (that means we still have nodes to visit).
3. We pop an item from the stack to be our new currentNode.
4. We use fs.readdirSync(currentNode.path) to get the node's sub-directories and files.
5. 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. 👋

I’ll be still cross-posting some things, but I will by posting first on my personal site and DEV.to. You can check out this and other posts bellow

How I avoid the side project frustration

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.

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?

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:

1. 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.
2. 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 😅)!
3. 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 😬.
4. Used react-three-fiber to read the city definition and to render the city.
5. 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.

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.

Feel free to reach out to me on twitter.

The idea behind is: enable or disable features during execution time without any deploy. There are hundreds of implementations across different languages and the applications are many: A/B testing, toggle app configuration, delivery new features gradually, etc.

This post suggests an approach for implementing React components for Feature Flag consuming a GraphQL API using Apollo Client for that!

EnabledFeatures

Let's first assume the schema below as our main schema.

In this schema, if a Feature is present in the array it means that the user has that feature enabled . The lack of some feature means that the feature is not visible/available for that user.

Disclaimer: The post assumes you are identifying the user through headers such as Authorization. Learn more on User Authentication with Apollo with their docs.

Having this contract we are now able to fetch user features by querying enabledFeatures .

query {
  enabledFeatures {
    name
  }
}

You can see a live querying using the Codesandbox of our example.

For querying with Apollo Client though we need to create the query definition which will be passed as an argument of the query executor.

The snippet above defines our query where we fetch the name of each feature.

FlaggedFeature

Now that we have a contract and a way to query, we have to implement the component which in fact queries the user features.

We will use the Query component as indicated by the docs for querying. Since Query component provides a render props API we can keep this strategy in our implementation.

While using FlaggedFeature you should pass the children function to the component. If you are not familiar with render function read this.

The component queries enabledFeatures and while it is not ready it returns the loading or error variables from Query component.

Once the data is retrieved, enabled is changed for the result of the filter and you will know whether or not the feature is enabled for this user.

With the following example you are already able to render a component if feature1 is available for the user or a fallback strategy instead.

Caching and EnabledFeatures

Although our FlaggedFeature is enough for 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 has a in memory cache implementation that caches the queries results by default! Knowing that, we deduce the FlaggedFeature will be slower only on it first execution. After that, the result will be cached. However, we can go further with cache implementing another strategy.

What if we pre-cache the user features? If we query the feature beforehand then when they are actually needed they will be already available in cache.

To achieve that, we can implement a pretty similar component which I called EnabledFeatures. This component follows the same principles as FlaggedFeature, but it is not concerned about any specific feature. It is only worried about querying the API.

As the first component we did, this implementation provides the query state via render props and return a ready property when its work is finished.

A good place to useEnabledFeatures would be wrapping up your App then the component will first query the user features. Or perhaps, you would wrap a portion of your App that can be controlled by the feature flags. The query will be executed whenever you reach that portion of the App .

If the immediate children do not depend on the flags then they can be rendered right. You may ignore the loading state and return your App.

In the example, the EnabledFeatures queries the API and relies on Apollo to cache the result in memory. So when FlaggedFeature renders, instead of going for a network call the component first hits the local cache, fetches the results from there and saves network time for you! 🎉

The main goal of using EnabledFeatures is that you are able to query all the features before you actually need them. Rendering this component as a wrap of your application does not impact the user experience, actually provides you a way of showing some extra feedback and when the features are needed, accessing them is much faster.

This approach reduces networks calls thanks to Apollo cache and improves the user experience. But, be aware that the flags will stick in the memory cache until the user refreshes the page.

What's next?

Now that the basic flow is done, you can think about evolving the schema and features. For example, you might wanna add options or variations as a field of Feature, then you can branch the feature implementation depending on its variation or properties. You can make the components more generic passing the query as props to them.

In the end, whenever implementing new system features using GraphQL and Apollo keep in mind that the cache can be a valuable ally to improve user experience.

Comments and suggestions are welcome as always! 😊

Feature Flag approach for React using Apollo Client 🚀 was originally published in Open GraphQL on Medium, where people are continuing the conversation by highlighting and responding to this story.

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.

• https://github.com/apollographql/react-apollo/pull/481
• https://github.com/apollographql/react-apollo/issues/464
• https://github.com/apollographql/react-apollo/issues/1588
• https://github.com/apollographql/react-apollo/pull/729

Why would we need multiple 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.

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.

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 🎉 🎉 !

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

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

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:

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

As a product of this article discussion some approaches have come up by folks who did their own abstractions/implementations for solving this issue.

Community own package 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 an implementation 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 as I mentioned in this post before.

• The next generation of schema stitching
• GraphQL Remote Stitching Micro-services with NodeJS

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.

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 requesting 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 discussing about using API Gateways and managing different GraphQL schemas is just at the beginning and the community will work on nicer and better solutions.

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

Apollo Multiple Clients with React? was originally published in Open GraphQL on Medium, where people are continuing the conversation by highlighting and responding to this story.