DEV Community: Vladimir Novick

Performance Regression Testing for React Native

Vladimir Novick — Fri, 27 Jan 2023 10:51:28 +0000

Introduction

Let's talk about developing React Native apps. Or, to be more precise about developing performant React Native apps.

React Native is an excellent framework for developing cross-platform mobile apps. It's fast; it's easy to use. However, certain things should be kept in mind while developing React Native apps. One of them is performance.

As React Native applications grow in size, their performance tends to deteriorate. React Native is a JavaScript framework, and JavaScript is a single-threaded language. While the UI is being rendered, the JavaScript thread is blocked, and no other JavaScript code can be executed.

React Native Re-renders

Re-renders are one of the most common causes of performance problems in React Native apps. They can go unnoticed in React web apps; however, in React Native apps, an excessive amount of re-renders leads to serious performance issues and slow UI. On top of that, it's pretty hard to spot code changes that lead to re-renders just by reviewing the code.

When a component re-renders, a serialized message is sent through the bridge from the JavaScript thread to the native platform. The native platform unserializes the message and creates a new native view, which is then rendered on the screen. If the render result is the same as the previous result, it may not result in native view changes; however, the time it takes to re-render a portion of the element tree might block the JS thread.

If the JavaScript thread is unresponsive for a frame, it will be considered a dropped frame. Any animations controlled by JS would appear to freeze during that time; and if it lasts longer than 100ms, the user will surely feel it. Not only animations are impacted; response to touches can be affected as well. In fact, there are quite a lot of performance issues that re-renders can cause. You can read about possible causes of such problems in the following guide on performance for possible causes of performance problems
https://www.callstack.com/campaigns/download-the-ultimate-guide-to-react-native-optimization

Development lifecycle

Development lifecycle would make a good topic for a separate blog post, but let me be brief here. In a nutshell, a simplified version of what happens during the development process is as follows:

New feature is introduced
Tests are added
QA goes on
Release takes place

Looks good, right? Especially because in reality, tests are sometimes skipped, or the QA process is rushed for the sake of releasing to prod. Let's assume a best-case scenario where test coverage is maintained in the high percentile, coverage reports are monitored, integration tests are automated, regression tests are executed, etc.

Even in this perfect setting, there might be bugs that escape the QA engineer's notice. But more importantly, performance problems that fail to be recognized by any test or QA process can occur.

Adding additional re-render can sound like no big deal, but performance degradation is like a snowball. As more features are developed, it gets more excruciating to pinpoint or fix performance issues. And once they become apparent to end users, it usually requires a lot of refactoring and a dedicated team working for hours to find the problem and carry out improvements. These, in turn, can introduce breaking changes to the rest of the app and lead to months of further development work.

Introducing Performance Regression testing

So, what can we do about this snowball of performance degradation growing over time? How can we know that a new feature reduces performance? How can we catch the unnecessary re-renders and get actual performance metrics without the overhead of having a dedicated team working on performance improvement?

Of course, there is no silver bullet to finding ALL performance problems, especially the ones that originate on the native side. Still, we can address the ones that arise from incorrect usage of React or React Native, like long lists, not using memoization, unnecessary re-renders, etc.

It's not enough to only identify these performance issues; we also need to introduce some measuring tools into development workflow and CI to automate performance regression tests. While doing it manually on each PR review is possible, it takes precious development time, introduces complexity to the release process, and increases the chance of performance problems slipping through the PR review process and ending up in prod.

Reassure for the rescue

Given that there hasn't been any tool for automating performance regression testing so far, folks at Callstack have decided to create one: https://www.callstack.com/open-source/reassure

Introducing a new tool means introducing a new workflow. This can lead to lower adoption, as developers need to to get familiar with it in the first place. To prevent that from happening, we've based Reassure on https://callstack.github.io/react-native-testing-library/ API as something React Native developers should be familiar with.

Reassure can be easily integrated with your current React Native Testing Library setup. Writing performance tests is pretty close to writing regular tests, as we will see in examples later in this blog post.

Adding Reassure to your project

yarn add --dev reassure

or

npm install --save-dev reassure

After you've added reassure you can start writing performance regression tests by adding .perf-test.tsx extension.

Since there is a similarity between your regular tests and reassure performance regression tests, the process of creating the latter will usually involve copy-pasting existing tests and altering them to match reassure API.

In a nutshell, instead of using render function from React Native Testing library, you would use measurePerfomance function and pass the scenario function to it, which will execute the scenario to measure.

To run reassure, you will run yarn reassure and get the results.

Let's take a look at a more detailed example, so we can understand how we can not only measure the performance of an existing component, but also refactor it while significantly improving its performance.

Refactor long lists while measuring performance

Consider the following GameList component.

export const GameList = () => {
  const {isLoading, data} = useGetGames();

  const [gameLikes, setGameLikes] = React.useState<any>({});

  const likeGame = (id: number) => {
    setGameLikes((prevState: any) => {
      return {
        ...prevState,
        [id]: prevState[id] ? prevState[id] + 1 : 1,
      };
    });
  };

  return isLoading ? (
    <Box
      flex={1}
      backgroundColor="black"
      alignItems="center"
      justifyContent="center">
      <Spinner color="purple.500" size="lg" testID="spinner" />
    </Box>
  ) : (
    <View testID="list">
      <Box>
        {data?.pages
          ?.map((page: {results: any}) => page.results)
          .flat()
          .map((game: any) => (
            <GameItem
              game={game}
              likes={gameLikes[game.id]}
              likeFn={() => likeGame(game.id)}
            />
          ))}
      </Box>
    </View>
  );
};

This component will get games data from useGames hook and render it on the screen. Before measuring component performance and optimizing it, let's first write a simple test for it.

We will create GameList.test.tsx file and write our test there.

First, we need to mock useGames hook:

jest.mock('../hooks', () => ({
  useGetGames: () => ({
    data: {
      pages: [
        {
          results: Array.from({length: 1000}, () => ({
            id: Math.random() * 10000,
            name: Math.random().toString(36).substring(7),
            background_url: `https://i.imgur.com/${Math.random()
              .toString(36)
              .substring(2)}.jpg`,
          })),
        },
      ],
    },
    hasNextPage: true,
    fetchNextPage: jest.fn(),
    isFetchingNextPage: false,
  }),
}));

Initially, our component is pulling data from https://api.rawg.io/api, so we will need to match results to be in the same structure as returned from API. As you can see in the code above, we will generate 1000 game items with random ids, random names, and background_url pulled from imgur

Note: For the sake of simplicity in this particular example, we use jest.mock to mock our API results. Yet, it's advised to use msw to mock Api call results, which you can read more about here

Now, let's write the test.

const initialWindowMetrics = {
    frame: {
      x: 0,
      y: 0,
      width: 0,
      height: 0,
    },
    insets: {
      top: 0,
      left: 0,
      right: 0,
      bottom: 0,
    },
  };

test('Renders GameList', async () => {
  const createWrapper = () => {
    return ({children}) => (
      <NativeBaseProvider initialWindowMetrics={initialWindowMetrics}>
        {children}
      </NativeBaseProvider>
    );
  };
  const wrapper = createWrapper();
  render(<GameList />, {wrapper});
  const gameItems = await screen.findAllByTestId('game-item');
  expect(gameItems).toHaveLength(1000);
  expect(screen.queryByTestId('spinner')).not.toBeTruthy();
  expect(screen.queryByTestId('list')).toBeTruthy();
});

We are using NativeBase for our UI in this test, which means we also have to wrap our GameList with NativeBaseProvider and supply it with initialWindowMetrics, so it can successfully render our UI.

In this test, we have 1000 game items and list component is present.The test passes, but we can probably identify the problem here. There are 1000 rendered game items. Clearly, our component is not optimized and will render all 1000 items, even though they are not visible to the user initially.

Measuring performance with Reassure

In the previous section, we've set up Reassure, so now, let's use it to measure the performance of our component.

Let's copy our GameList.test.tsx to be GameList.perf-test.tsx and alter our performance test to match Reassure API.

Mocking

We will reuse the same mock we've created in GameList.test.tsx, but since the performance test will take way more time to run, we need to limit the test to only 100 items instead of 1000 and increase jest default timeout from 5000ms to a minute by using jest.setTimeout(60_000);

Note that to get a more reliable performance measurement, Reassure executes each scenario ten times and averages the results (the number of runs can be easily configured using configure function

Due to a slight API difference between Reassure and React Native Testing library, we also need to change our createWrapper function from the previous test in the following way:

const createWrapper = () => {
  return (node: JSX.Element) => (
    <NativeBaseProvider initialWindowMetrics={initialWindowMetrics}>
      {node}
    </NativeBaseProvider>
  );
};

Then we eliminate all our assertions and call measurePerformance function from Reassure, passing it to our wrapper.

The final performance test looks like this:

import React from 'react';
import {NativeBaseProvider} from 'native-base';
import {measurePerformance} from 'reassure';
import {GameList} from './GameList';
jest.setTimeout(60_000);
jest.mock('../hooks', () => ({
  useGetGames: () => ({
    data: {
      pages: [
        {
          results: Array.from({length: 100}, () => ({
            id: Math.random() * 10000,
            name: Math.random().toString(36).substring(7),
            background_url: `https://i.imgur.com/${Math.random()
              .toString(36)
              .substring(2)}.jpg`,
          })),
        },
      ],
    },
    hasNextPage: true,
    fetchNextPage: jest.fn(),
    isFetchingNextPage: false,
  }),
}));

test('GameList perf test', async () => {
  const initialWindowMetrics = {
    frame: {
      x: 0,
      y: 0,
      width: 0,
      height: 0,
    },
    insets: {
      top: 0,
      left: 0,
      right: 0,
      bottom: 0,
    },
  };

  const createWrapper = () => {
    return (node: JSX.Element) => (
      <NativeBaseProvider initialWindowMetrics={initialWindowMetrics}>
        {node}
      </NativeBaseProvider>
    );
  };

  const wrapper = createWrapper();

  await measurePerformance(<GameList />, {
    wrapper,
  });
});

At this point, we can run yarn reassure --baseline to gather baseline metrics to compare during all subsequent runs.

After running this command, .reassure/baseline.perf file is created with the following data:

{"metadata":{}}
{"name":"GameList perf test","runs":10,"meanDuration":480.2,"stdevDuration":31.957610813214572,"durations":[516,506,505,504,495,488,473,456,431,428],"meanCount":1,"stdevCount":0,"counts":[1,1,1,1,1,1,1,1,1,1]}

Since there can be discrepancies between the measured performance metrics, Reassure is designed to execute multiple runs (10 by default) and provide the average for two main parameters:

render count
render duration

In the .perf file, we can see the exact rendering duration and the number of renders for each run. We can increase the number of runs by providing runs: number option to measurePerfomance function.

Introducing scenarios

While measuring performance, we usually want to check whether the component is re-rendered due to UI interaction. In our example, when clicking on a game item, likes for this item are updated. The way it works at the moment is by setting the state on the component and, as a result, triggering GameList re-render.

Let's validate this scenario in our performance test and see how it will impact our metrics.

We create a scenario async function where we can use any React Native Testing library methods.

const scenario = async () => {
  const gameItems = await screen.findAllByTestId('game-item');
  fireEvent(gameItems[0], 'press');
};

Now we can pass this scenario to measurePerformance function:

await measurePerformance(<GameList />, {
  scenario,
  wrapper,
});

Now, if we run yarn reassure, Reassure will compare .reassure/baseline.perf file with .reassure/current.perf file, and we will see the following results:

✅ Written Current performance measurements to .reassure/current.perf
🔗 /Users/vladimirnovick/dev/Callstack/Reassure/reassuredemo/.reassure/current.perf

❇️ Performance comparison results:

Current: (unknown)

Baseline: (unknown)

➡️ Signficant changes to render duration

GameList perf test: 480.2 ms → 690.7 ms (+210.5 ms, +43.8%) 🔴🔴 | 1 → 2 >(+1, +100.0%) 🔴

➡️ Meaningless changes to render duration

➡️ Render count changes

GameList perf test: 480.2 ms → 690.7 ms (+210.5 ms, +43.8%) 🔴🔴 | 1 → 2 >(+1, +100.0%) 🔴

➡️ Added scenarios

➡️ Removed scenarios

Here we can see an increase in the render count of the component and 43.8% increase in rendering time.

It's an excellent showcase of how new interactions during the development of new features can gradually increase rendering time and decrease the component's performance. Having a tool like Reassure gives us a detailed insight into how components' performance changes as the app grows.

Improving performance

Let's set this new metric as our new baseline and start improving our component to be more performant, measuring the number of re-renders and rendering time as we do our refactoring.

First of all, to set up a new baseline, let's run yarn reassure --baseline.

As mentioned before, it will write new metrics in baseline.perf file and use it for comparison later on

Refactoring to FlatList

You might be wondering, why not use FlatList? That’s a fair question. We shouldn't map over items, but rather use FlatList to render game items on the screen. So let's refactor our component accordingly:

<FlatList
  data={data?.pages?.map((page: {results: any}) => page.results).flat()}
  renderItem={renderData}
  keyExtractor={gameItemExtractorKey}
  onEndReached={loadMore}
  onEndReachedThreshold={0.3}
  ListFooterComponent={isFetchingNextPage ? renderSpinner : null}
/>

Results will be outstanding:

Written Current performance measurements to .reassure/current.perf
🔗 /Users/vladimirnovick/dev/Callstack/Reassure/reassuredemo/.reassure/current.perf

❇️ Performance comparison results:

Current: (unknown)

Baseline: (unknown)

➡️ Signficant changes to render duration

GameList perf test: 687.6 ms → 83.8 ms (-603.8 ms, -87.8%) 🟢🟢 | 2 → 2

➡️ Meaningless changes to render duration

➡️ Render count changes

➡️ Added scenarios

➡️ Removed scenarios

As you can see, there is an 87.8% improvement in rendering times.

If you run yarn test GameList.test.tsx to check if our unit test is working, it will fail due to the FlatList rendering only 10 game items out of 1000 items available. That’s because the remaining items are off-screen and do not need any rendering.

Let's also change our GameList.test.tsx test and switch from

expect(gameItems).toHaveLength(1000);

expect(gameItems).toHaveLength(10);

For further improvement, let's move likes logic into GameItem component. This will yield the following results:

Performance comparison results:

Current: (unknown)

Baseline: (unknown)

➡️ Signficant changes to render duration

GameList perf test: 687.6 ms → 47.3 ms (-640.3 ms, -93.1%) 🟢🟢 | 2 → 2

➡️ Meaningless changes to render duration

➡️ Render count changes

➡️ Added scenarios

➡️ Removed scenarios

✅ Written JSON output file .reassure/output.json
🔗 /Users/vladimirnovick/dev/Callstack/Reassure/reassuredemo/.reassure/output.> json

✅ Written output markdown output file .reassure/output.md
🔗 /Users/vladimirnovick/dev/Callstack/Reassure/reassuredemo/.reassure/output.md

As you can see from this example, we've successfully improved the performance of our component by 91.4% and reduced rendering times from 687.6ms to 59.3ms.

Using Reassure for performance regression testing in CI

Even though in our example, we've used Reassure as a tool to improve and measure performance, the area where the tool shines the brightest is Performance Regression testing.

As we develop new features, it's easy to gradually degrade performance until the problem becomes noticeable to the user. With Reassure, you can compile a report of performance changes by running Reassure in CI on your PRs.

It's important to note that the speed of the machine on which Reassure is running matters. To resolve any potential inconsistencies in the results, Reassure runs tests multiple times, averages the results, and provides a handy CLI tool to assess machine stability.

By running yarn reassure check-stability, it carries out performance measurements for the current code twice, so that baseline and current measurements refer to the same code. In such a case, the expected changes are 0% (no change). The degree of random performance changes will reflect the stability of your machine. This command can be run both on CI and local machines.

When integrating Reassure into CI, your CI agent stability is even more important than its speed. That’s because we want to see consistent results.

Tip: If your machine or CI agent stability is so-so, consider increasing the number of runs in the Reassure configure function

You can create a custom script for CI to run to compare performance between your main branch and the current branch

#!/usr/bin/env bash
set -e

BASELINE_BRANCH=${BASELINE_BRANCH:="main"}

# Required for `git switch` on CI
git fetch origin

# Gather baseline perf measurements
git switch "$BASELINE_BRANCH"
yarn install --force
yarn reassure --baseline

# Gather current perf measurements & compare results
git switch --detach -
yarn install --force
yarn reassure

In the script above, we set the baseline branch to be the main branch and run yarn reassure --baseline to gather baseline metrics on it.

Then we compare them with the current branch by running yarn reassure.

You can read more about setting up Reassure in CI in official docs here

In this article, I presented a few simple examples of things that can cause performance problems in the long run. As you've noticed, minor refactoring led to a 93.1% performance improvement. Even though performance issues presented in the article can be caught during a thorough PR review, that can become inherently harder in complex codebases and as your React Native app grows. Making Reassure part of your test suite to address potential performance regressions and automate things in CI would greatly benefit you in the long run. Also, if you already write tests with react-native-testing-library (If you don't, you definitely should), creating Reassure perf tests is, to some degree, a copy-paste of existing tests with slight modification so that it can be quickly introduced into the development workflow.
Due to the open-source nature of Reassure, if you have improvement suggestions, feel free to create issues in the repo, and Reassure team will address them.

Scaling a Hasura GraphQL Backend with Distributed SQL

Vladimir Novick — Mon, 06 Apr 2020 20:36:51 +0000

GraphQL is taking the modern development world by storm having been adopted by companies like Facebook, GitHub, and Intuit because it solves many of the common problems developers encounter when working with REST APIs. For example, it solves issues like overfetching (getting more data than your response needs) and underfetching (having to make multiple fetches to get all the data you need), or when consolidating API responses on the client is necessary. When a developer follows the GraphQL spec, it means they have typed schema on the server that defines the exact structure of their API. Another advantage of GraphQL is that it gives us a single API endpoint and query language so we can query any data that we need from the client without introducing a lot of new API endpoints.

Creating a GraphQL backend can be tough. Creating it with real-time capabilities in mind is even tougher. And scaling a GraphQL backend can be really tough. Luckily there are free and open source projects like Hasura that solve lots of these problems. The Hasura engine is a compiler that runs on top of PostgreSQL and compiles your GraphQL query language into better performing SQL statements while leveraging the best features that PostgreSQL has to offer.

In a nutshell, the Hasura engine auto generates a GraphQL CRUD API, provides an eventing system to trigger serverless functions, can stitch other GraphQL servers inside the engine, has a permission system built-in, auth, and more. For a deeper dive, check out some of my blog posts on Hasura, including Effortless Real-time GraphQL API with serverless business logic. There are also a few Twitch streams on twitch.tv/vnovick that you can check on my YouTube channel.

Initially, scaling Hasura involves stitching multiple Hasura instances together, however, this does not solve the problem of how to scale our database.

So, what are the challenges we will likely encounter with scaling the database? Because modern apps need to support users worldwide, we need a database that is geo-distributed, fast, supports transactions, and can scale up or down without incurring any downtime. By employing a database with these characteristics, data will always be available, and the operations team won’t have to architect external systems and processes to handle scaling, fault tolerance, multi-region asynchronous replication, and so on.

Introducing YugabyteDB

YugabyteDB is an open-source, high-performance distributed SQL database for powering global, internet-scale applications. Built using a unique combination of a high-performance document store, per-shard distributed consensus replication and multi-shard ACID transactions (inspired by Google Spanner), YugabyteDB serves both scale-out RDBMS and internet-scale OLTP workloads with low query latency, extreme resilience against failures and global data distribution.

YugabyteDB is also a cloud-native database, so it can be deployed across both public and private clouds, including Kubernetes environments. In regards to serving as a backend for microservices, YugabyteDB brings together three must-haves: a PostgreSQL-compatible SQL API, low-latency read performance, and globally distributed write scalability.

Getting started with YugabyteDB

To get started head on over to: https://docs.yugabyte.com/latest/quick-start/

Note: For the purposes of this blog post, I will be running YugabyteDB locally on my Mac, but you can run on any of the major cloud providers. Look for additional blog posts from me on this topic in the future.

Get started on Mac

I will follow relevant docs section with the following steps:

Check the prerequisites

Make sure you check the prerequisites for your machine before you venture forward. Like the Python version and increasing the maxfiles limit. These are described pretty well here

Download YugabyteDB

Download the YugabyteDB tar.gz file using the following wget command.

wget https://downloads.yugabyte.com/yugabyte-2.1.2.0-darwin.tar.gz

To unpack the archive file and change to the YugabyteDB home directory, run the following command.

tar xvfz yugabyte-2.1.2.0-darwin.tar.gz && cd yugabyte-2.1.2.0

Adding loopback addresses

In our example I want to create a YugabyteDB cluster with 3 nodes. Since these nodes will be running on localhost, I want to add six loopback addresses by running the following:

sudo ifconfig lo0 alias 127.0.0.2
sudo ifconfig lo0 alias 127.0.0.3
sudo ifconfig lo0 alias 127.0.0.4
sudo ifconfig lo0 alias 127.0.0.5
sudo ifconfig lo0 alias 127.0.0.6
sudo ifconfig lo0 alias 127.0.0.7

Create a local cluster

Now it's time to create a local cluster. In the unpacked Yugabyte folder I will run the following:

./bin/yb-ctl create --rf 3 --tserver_flags "ysql_suppress_unsupported_error=true"

This will create a distributed SQL cluster with 3 nodes. Note that I've added --tserver_flags which is crucial to make YugabyteDB work with Hasura.

After I've created my cluster, I can now run

./bin/yb-ctl status

to check my cluster status.

There is another option to check our cluster with the Admin UI, which is automatically exposed by Yugabyte on the localhost.

You can go to http://127.0.0.1:7000 for the YB-Master UI where you will see the

List of tables present in the cluster
List of nodes (aka YB-TServer servers) present in the cluster
List of utilities available to debug the performance of the cluster

You can also access each tablet server individually by selecting the Tablet Servers menu option and accessing each server admin link.

For example if I want to access the second tablet server admin UI, I can go to http://127.0.0.2:9000/

Running Hasura on top of Yugabyte

Now that I have YugabyteDB running, let's setup Hasura on top of it.

I can either go to the Docker Deploying section in the Hasura docs and follow the instructions or just simply run the following command:

docker run -d -p 8080:8080 -e HASURA_GRAPHQL_DATABASE_URL=postgres://postgres:@host.docker.internal:5433/yugabyte -e HASURA_GRAPHQL_ENABLE_CONSOLE=true hasura/graphql-engine:latest

You can notice that HASURA_GRAPHQL_DATABASE_URL points now to
postgres://postgres:@host.docker.internal:5433/yugabyte

Hasura migrations

We want to be sure that when we destroy our cluster, we will be able to recreate database changes that we will do through the Hasura console. In order to recreate these changes, we will make sure Hasura will write migration files whenever we change database schema in the console. (You can read more about migrations here

In order to do that we will run hasura init in any folder of our choice (typically project folder) and then

cd hasura
hasura console

That will bring up our Hasura console:

From that point on any changes done in the console will write migration files. If for some reason (or for cleanup) I need to destroy my cluster, I will always be able to recreate the database schema just by running hasura migrate apply.

Testing CRUD

Now I will create a simple blog post API below. You can also find videos of this on my YouTube channel

Let's try the following queries in the Hasura console

mutation insertPost {
  insert_posts(objects: {user: {data: {name: "Vladimir Novick"}}, title: "First blog post 1", content: "Content"}) {
    returning {
      user {
        id
      }
      id
    }
  }
}

mutation updatePost($id: uuid!) {
  update_posts(where: {id: {_eq: $id}}, _set: {title: "First blog post"}) {
    affected_rows
  }
}

mutation deletePost($id: uuid!) {
  delete_posts(where: {id: {_eq: $id}}) {
    affected_rows
  }
}

query getPosts {
  posts {
    title
    content
    user {
      name
    }
  }
}

subscription getPostsSub {
  posts {
    title
    content
    user {
      name
    }
  }
}

It looks like all of them work just perfectly.

Simulate downtime with active subscriptions

Now let's simulate downtime while having an active GraphQL subscription running. For that we will run the following GraphQL subscription in the Hasura console.

subscription getPostsSub {
  posts {
    title
    content
    user {
      name
    }
  }
}

Now head to the terminal in the Yugabyte unpacked tar folder and execute:
./bin/yb-ctl stop_node 3

This will stop one of the nodes of the Yugabyte cluster, but our GraphQL subscription will keep working. Only if we stop node 2 as well, we will get an error.

This is because YugabyteDB is configured with Replication Factor 3 that allows it to tolerate one infrastructure failure automatically. We have simulated a node failure here but such failures can also include disk, network, availability zone, cloud region/datacenter, or even entire cloud (for a multi-cloud cluster configuration).

So basically if 2 out of 3 nodes are failing we will get an error.

{
  "data": null,
  "errors": [
    {
      "errors": [
        {
          "extensions": {
            "path": "$",
            "code": "unexpected"
          },
          "message": "postgres query error"
        }
      ]
    }
  ]
}

Now let's start node 2 again. Almost immediately our subscription will continue working.

Summary

As you’ve seen in this blog post, getting started with YugabyteDB and integrating it to work with Hasura is straightforward. When you combine these two technologies you get all the benefits of GraphQL’s efficiency and performance when dealing with APIs plus the scale and availability of a YugabyteDB backend.

YugabyteDB with its global data distribution brings data close to users for multi-region and multi-cloud deployments. It is a self-healing database that tolerates any failures, which we've just seen in our example.

Finally, recall that everything I’ve shown in this blog post is open source, so there is no proprietary code, licenses or trial periods to hold you back from developing with GraphQL and a YugabyteDB backend!

The Ultimate Guide to handling JWTs on frontend clients (GraphQL)

Vladimir Novick — Mon, 23 Sep 2019 08:44:25 +0000

This is an excerpt of an original post published on blog.hasura.io

JWTs (JSON Web Token, pronounced 'jot') are becoming a popular way of handling auth. This post aims to demystify what a JWT is, discuss its pros/cons and cover best practices in implementing JWT on the client-side, keeping security in mind. We’ve kept the examples especially relevant to GraphQL clients.

Introduction: What is a JWT?

For a detailed, technical description of JWTs refer to this article.

For the purposes of auth, a JWT is a token that is issued by the server. The token has a JSON payload that contains information specific to the user. This token can be used by clients when talking to APIs (by sending it along as an HTTP header) so that the APIs can identify the user represented by the token, and take user specific action.

But can’t a client just create a random JSON payload an impersonate a user?

Good question! That’s why a JWT also contains a signature. This signature is created by the server that issued the token (let’s say your login endpoint) and any other server that receives this token can independently verify the signature to ensure that the JSON payload was not tampered with, and has information that was issued by a legitimate source.

But if I have a valid and signed JWT and someone steals it from the client, can’t they use my JWT forever?

Yes! If a JWT is stolen, then the thief can can keep using the JWT. An API that accepts JWTs does an independent verification without depending on the JWT source so the API server has no way of knowing if this was a stolen token! This is why JWTs have an expiry value. And these values are kept short. Common practice is to keep it around 15 minutes, so that any leaked JWTs will cease to be valid fairly quickly. But also, make sure that JWTs don’t get leaked.

That’s why it’s also really important not to store JWT on the client, say via cookies or localstorage. Doing so you make your app vulnerable to CSRF & XSS attacks, by malicious forms or scripts to use or steal your token lying around in cookies or localstorage.

So does a JWT have a specific kind of structure? What does it look like?

A JWT looks something like this, when it's serialized:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o

If you decode that base64, you'll get JSON in 3 important parts: header, payload and signature.

The serialized form is in the following format:

[ base64UrlEncode(header) ] . [ base64UrlEncode(payload) ] . [signature ]

A JWT is not encrypted. It is based64 encoded and signed. So anyone can decode the token and use its data. A JWT's signature is used to verify that it is in fact from a legitimate source.

Here is the diagram of how a JWT is issued(/login) and then used to make an API call to another service(/api) in a nutshell:

Ugh! This seems complicated. Why shouldn’t I stick to good old session tokens?

This is a painful discussion on the Internet. Our short (and opinionated answer) is that backend developers like using JWTs because a) microservices b) not needing a centralized token database.

In a microservices setup, each microservice can independently verify that a token received from a client is valid. The microservice can further decode the token and extract relevant information without needing to have access to a centralized token database.

This is why API developers like JWTs, and we (on the client-side) need to figure out how to use it. However, if you can get away with a session token issued by your favorite monolithic framework, you’re totally good to go and probably don’t need JWTs!

Continue reading here

Custom auth for Hasura with Netlify

Vladimir Novick — Thu, 01 Aug 2019 13:11:32 +0000

In the last couple of months, I published several blog posts on authentication with different providers such as Auth0 or AWS Cognito. I also summarized different authentication options with these providers in Hasura Authentication Explained blog post

One of the auth solutions that I've been missing is Netlify. In this tutorial, we will create an auth solution for hasura.io using Netlify in a bit different way than we did it previously. The main difference is that Netlify Identity (Netlify auth solution), even though supports JWT, it still does not support custom claims which is crucial to make Hasura work with JWT tokens. We will talk about the different approach here - using custom Auth webhook to verify JWT token provided by Netlify Identity, extract data from it and send this data in the format Hasura can parse and use in permission system.

Getting started

Setting up our Hasura

First of all, we will set up our Hasura on Heroku. If you are new to Hasura you can read more about it in the following blog post

We will create two tables: posts and users, User table will have Text type id, because we will get that from Netlify identity.

Getting users into Hasura

In this section we will make sure when signing up, the user will be written into users table.

Create netlify site

We will start simple by the creation of our netlify site:

mkdir hasura-netlify-identity-auth
npm init
netlify init

For this custom auth solution we will need two things:

Netlify function, which will run on signup and will add users to Hasura
Netlify function which we will use as auth webhook to validate our token, extract data and send this data to Hasura

Frontend

I won't be creating frontend in this blog post, but will use react-netlify-identity-widget sample. You can check frontend code here

Creating signup hook

We will use netlify cli to create signup hook.

netlify functions:create

choose identity signup. This will create functions folder and auto-generate identity-signup.js file with boilerplate code. Netlify identity will call identity-signup.js automatically whenever user confirmed his email.

We will install node-fetch cause we will need it to execute our insertUser mutation

npm install node-fetch

on signup function hook we will execute insertUser mutation to insert a new user into Hasura

const fetch = require("node-fetch");

exports.handler = async function(event, context) {
  const { user } = JSON.parse(event.body);

  const responseBodyString = JSON.stringify({
    query: `
    mutation insertUser($id: String, $email:String, $name:String){
      insert_users(objects: {id: $id, email: $email, name: $name}) {
        affected_rows
      }
    }    
  `,
    variables: {
      id: user.id,
      email: user.email,
      name: user.user_metadata.full_name
    }
  });

  console.log(responseBodyString);

  const result = await fetch(
    "https://netlify-stream.herokuapp.com/v1/graphql",
    {
      method: "POST",
      body: responseBodyString,
      headers: {
        "Content-Type": "application/json",
        "x-hasura-admin-secret":
          process.env.HASURA_SECRET
      }
    }
  );
  const { errors, data } = await result.json();

  if (errors) {
    console.log(errors);
    return {
      statusCode: 500,
      body: "Something is wrong"
    };
  } else {
    return {
      statusCode: 200,
      body: JSON.stringify(responseBody)
    };
  }
};

Let's also add hasura secret in environment variables in Netlify to set admin secret for Hasura.

If you want to watch this part, which we streamed together with swyx on https://twitch.tv/hasurahq

It's available here:

Creating custom auth webhook

In this section, we will create a custom auth webhook by creating a new function to validate auto-generated jwt token whenever we sign up.

What we will do first is to create a new function using

netlify fuctions:create

we will call it validate-user

Inside the function we will get identity and user object from context.clientContext

Netlify automatically decodes JWT token and if a token is supplied properly, then we will be able to get a user object. If not, then we will set a role as anonymous

const fetch = require("node-fetch");

exports.handler = async (event, context) => {
  const {
    identity,
    user
  } = context.clientContext;
  if (user) {
    const userID = user.sub;
    return {
      statusCode: 200,
      body: JSON.stringify({
        "X-Hasura-User-Id": userID,
        "X-Hasura-Role": "user"
      })
    };
  }
  return {
    statusCode: 200,
    body: JSON.stringify({
      "X-Hasura-role": "anonymous"
    })
  };
};

You can notice that we return x-hasura-role and x-hasura-user-id, so we will be able to use them in the permission system inside Hasura.

Now the last thing left to do is to add HASURA_GRAPHQL_AUTH_HOOKenvironment variable to Heroku or any other environment you run hasura at. Whenever you do so, the token will be validated with netlify identity and correct values will be sent to the permission system.

Watch the part2 of our Twitch stream with swyx here:

Signing in with Google

Something that we haven't covered in the stream, but you might want to do is to sign with Google or any other providers. For that, you cannot rely on identity-signup name convention, but you need to create a hook manually. So the process will be to rename identity-signup function to something else and then in Notification settings for identity, add our signup hook url triggered on signup event.

Summary

This blog post is a rough explanation of what we did during our twitch stream, so if you haven't subscribed to our twitch streams or to Youtube channel I strongly suggest doing so, cause we stream this type of content on a weekly basis, having guests from different companies guiding me through live coding solutions for real-world problems. All of this is done in a fun, friendly environment.

If you want to show me some really cool technique, product or solution involving Hasura, I would be happy to find the time to stream with you, so let me know on Twitter

Trying out GraphQL with Unity3d engine

Vladimir Novick — Fri, 05 Jul 2019 08:15:28 +0000

GraphQL is an amazing technology that took the world like a storm. More and more companies are switching to using GraphQL instead of REST APIs because so many things, GraphQL solves.

In a nutshell, GraphQL is a query language for your API. It gives you an ability from a client-side to query your single API endpoint and define a shape of data that you want to get. On the server, you define a schema - the shape of data and how this data is resolved. Whether from a database, microservices or literally in any way you want.

What's also cool, GraphQL gives you subscriptions functionality so you can get real-time data over WebSockets and build modern web and mobile apps with ease. If you are interested to learn more about GraphQL, you can check out learn.hasura.io tutorials on how to use GraphQL with lots of various web and mobile clients.
Also, you can check GraphQL Bootcamp I did some time ago on my Youtube channel

If you've been following me on twitter @VladimirNovick you probably know that I am working on Web, Mobile, AR, VR and IoT fields.

In VR and AR fields especially I've been working with Unity3d engine, so I was recently curious whether I can use GraphQL in Unity3d for things like real-time leaderboards.

After a long search for a graphql client for Unity3d, which I can use in C# and which will be supported in Unity engine, I found really basic one, that I used for the following demo.

So what's happening in this demo?
There are 3 scenes, which I have:

First one is just a loading screen and here I just show basic Loading screen with 10 seconds timer. So nothing really happening here.

Next loaded screen is HasuraSpaceDemo

I used FPS All in One first-person controller and Sci-Fi Modular corridor demo scene. For the portal, I used KTK Lighting asset to reduce time working on particle effects, but basically, it's just the Unity Shuriken particle system using a bunch of lighting assets. For UI and for Portal scene I used Sci fi UI pack and Living particles. Music in the scene is from Dark Sci-fi asset

HasuraSpaceDemo is used to showcase that GraphQL can be used in any type of game. If you walk into the portal I present UI where you can basically enter any GraphQL endpoint URL. When you do so, you are "teleported" into different - Portal scene.

I have UIManager script that handles UI:

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.UI;

public class UIManager : Singleton<UIManager>
{
    public string graphQLEndpoint;
    public GameObject graphQLCanvas;

    private void Start()
    {
        DontDestroyOnLoad(gameObject);
    }


    // Start is called before the first frame update
    public void LoadPortalScene()
    {
        GameManager.Instance.loadPortalScene();
    }

    public void setGraphQLEndpoint(Transform inputField)
    {
        graphQLEndpoint = inputField.GetComponent<InputField>().text;
    }

}

As you can see this script has two public methods - first one to load the portal scene and the second one to set graphQLEndpoint for later use in the next scene.

To use GraphQL in the next scene, what I do is, first of all, use GraphQLQuery script from graphql-client-unity package and set it on new empty Game Object in the scene calling it GraphQLClient

Then I need to add a Panel that will have interaction. The idea is when I approach a panel with text "GraphQL Schema Introspection", I will enter into Box Collider which will trigger OnTriggerStay method in IntrospectionPanelInteraction script.

When our IntrospectionPanelInteraction script starts, we set our GraphQuery URL, canvas to display a result as well as canvas content:

    void Start()
    {
        if (UIManager.Instance)
        {
            UIManager.Instance.graphQLCanvas = canvas;
        }

        GraphQuery.url = UIManager.Instance.graphQLEndpoint;

        fp = FindObjectOfType<FirstPersonAIO>();
        content = canvas.GetComponent<UICanvas>().Content;
    }

So when we are within Collider borders, OnTriggerStay function is running.


    private void OnTriggerStay(Collider other)
    {
        if (!canvas.activeSelf)
        {
            canvas.SetActive(true);
            runIntrospectionQuery();
        }
        InteractionController.Instance.disableInteraction(fp);
    }

query execution looks like this:

    void runIntrospectionQuery()
    {
        Debug.Log("Query");
      GraphQuery.onQueryComplete += DisplayResult;
      GraphQuery.POST(introspectionQuery);

    }

the query itself is defined as a string public variable and is visible in the editor:

The final IntrospectionPanelInteraction script looks like this:

using System.Collections;
using System.Collections.Generic;
using graphQLClient;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using UnityEngine;
using UnityEngine.UI;

public class IntrospectionPanelInteraction : MonoBehaviour
{

    [Tooltip("This is the query call that gives me introspection details)]
    [TextArea]
    public string introspectionQuery;

    public GameObject canvas;
    private FirstPersonAIO fp;
    private Text content;
    void Start()
    {
        if (UIManager.Instance)
        {
            UIManager.Instance.graphQLCanvas = canvas;
        }

        GraphQuery.url = UIManager.Instance.graphQLEndpoint;

        fp = FindObjectOfType<FirstPersonAIO>();
        content = canvas.GetComponent<UICanvas>().Content;
    }
    // Start is called before the first frame update
    private void OnTriggerStay(Collider other)
    {
        if (!canvas.activeSelf)
        {
            canvas.SetActive(true);
            runIntrospectionQuery();
        }
        InteractionController.Instance.disableInteraction(fp);
    }

    private void OnTriggerExit(Collider other)
    {
        if (canvas.activeSelf)
        {
            canvas.SetActive(false);
            InteractionController.Instance.enableInteraction(fp);
        }
    }

    void runIntrospectionQuery()
    {
        Debug.Log("Query");
        GraphQuery.onQueryComplete += DisplayResult;
        GraphQuery.POST(introspectionQuery);

    }

    public void DisplayResult()
    {
        string data = ParseData(GraphQuery.queryReturn, "__schema");
        canvas.gameObject.GetComponentInChildren<ScrollRect>().normalizedPosition = new Vector2(0, 1);
        Debug.Log(data);
        content.text = data;
    }

    void OnDisable()
    {
        GraphQuery.onQueryComplete -= DisplayResult;
    }

    string ParseData(string query, string queryName){
        JObject obj = JsonConvert.DeserializeObject<JObject>(query);
        return JsonConvert.SerializeObject(obj["data"][queryName], Formatting.Indented);
    }

}

Summary

As you can imagine this is a very simple example and it's me just trying out GraphQL in Unity engine. Also, it's a long way to go to get subscriptions, live queries etc. I am experimenting and I would love to see what use case for GraphQL in Unity3d or Unreal engine will be. I can see it really useful for things like leaderboards, high scores, in-app purchases, in-game ads, etc.

Please let me know on Twitter what GraphQL usage you see in Unity3d.

Adding Authentication to Hasura and Gatsby web app with Auth0

Vladimir Novick — Mon, 01 Jul 2019 15:40:54 +0000

A while ago we live-streamed a live coding event with Jason Lengstorf on how to create a real-time web app with Gatsby and Hasura.
If you are not familiar with Hasura, check this blog post:

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

In that live stream, we've created Gatsby static web app and added cool real-time capabilities using GraphQL Subscriptions. For this task, we live coded GraphQL server using Hasura.

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

During that stream I haven't covered auth though, so recently we decided to do another live stream with Jason to close this gap.

In this stream, we haven't covered Gatsby setup, but we covered authentication solution with Hasura using Auth0. I also wrote about other auth methods in my blog post Hasura Authentication Explained, but for Auth0 steps will be as following:

Setting Auth0 domain

Go to auth0.com and sign in or sign up if you don't have an account yet. After logging in, you will get to Dashboard screen. There, you need to create your app.

We will choose a Single page application and after we create our app, we can choose how to integrate Auth0 into our web app.

I won't cover this step, because it is pretty self-explanatory and it is well documented in Auth0 console. An important part is that we need to path Authorization: Bearer token to our GraphQL API.

Setting our Hasura with Auth0

Now, when we pass proper auth token to Hasura, there are several steps that we need to do:

On Signup, we need to execute mutation on Hasura endpoint and insert a new user with Auth0 user id. This can be done by using Auth0 rules. From our Dashboard we navigate to the Rules tab and create a new rule. The code for this rule will be:

function (user, context, callback) {
  const userId = user.user_id;
  const nickname = user.nickname;

  const admin_secret = "adminsecret";
  const url = "https://myendpoint/v1/graphql";
  request.post({
      headers: {'content-type' : 'application/json', 'x-hasura-admin-secret': admin_secret},
      url:   url,
      body:    `{\"query\":\"mutation($userId: String!, $nickname: String) {\\n          insert_users(\\n            objects: [{ id: $userId, name: $nickname }]\\n            on_conflict: {\\n              constraint: users_pkey\\n              update_columns: [last_seen, name]\\n            }\\n          ) {\\n            affected_rows\\n          }\\n        }\",\"variables\":{\"userId\":\"${userId}\",\"nickname\":\"${nickname}\"}}`
  }, function(error, response, body){
       console.log(body);
       callback(null, user, context);
  });
}

Here we will be using Hasura admin secret for server to server communication.

Remember - never use admin secret on the client

Before our token is generated, we need to add so-called custom claims to JWT token, so Hasura will be able to get required info from JWT Token. So what we need to do is create another rule with the following code:

function (user, context, callback) {
  const namespace = "https://hasura.io/jwt/claims";
  context.idToken[namespace] = 
    { 
      'x-hasura-default-role': 'user',
      'x-hasura-allowed-roles': ['user'],
      'x-hasura-user-id': user.user_id
    };
  callback(null, user, context);
}

Last and final step will be adding HASURA_GRAPHQL_JWT_SECRET as environment variable for Hasura. To generate config, you can use the following tool: https://hasura.io/jwt-config

Summary

You can read more about Authentication and Permissions in my previously mentioned blog posts or get some hands-on experience by creating your own real-time GraphQL backend with Authentication, access control in around 30 minutes by following our Hasura backend tutorial at learn.hasura.io

Building blog CMS in ReasonML with GraphQL and Serverless using Hasura

Vladimir Novick — Fri, 21 Jun 2019 09:54:28 +0000

This is the first part of blog post series where we will create blog cms using Hasura for GraphQL API, and serverless functions for logic and on the client we will write modern and robust code using ReasonML syntax. Let's get started.

ReasonML intro

First of all, before getting into actual code writing, let's discuss why ReasonML? Even though it's a topic for a stand-alone blog post, I will try to give you a brief overview. ReasonML gives us a fantastic type system powered by Ocaml, but as far as syntax goes, it looks pretty close to Javascript. It was invented by Jordan Walke, the guy who created React and is used in production at Facebook messenger. Recently various companies also adopted Reason and use it in production because of it's really cool paradigm: "If it compiles - it works."
This phrase is a very bold statement, but in fact, because Reason is basically a new syntax of OCaml language, it uses Hindley Milner type system so it can infer types in compile time.

What it means for us as developers?

It means that typically we don't write that many types, if at all, as we write in TypeScript for example and can trust the compiler to infer these types.

Speaking of compilation, Reason can be compiled to OCaml, which in turn can compile to various targets such as binary, ios, android etc, and also we can compile to human-readable JavaScript with the help of Bucklescript compiler. In fact that what we will do in our blog post.

What about npm and all these packages we are used to in JavaScript realm?

In fact, BuckleScript compiler gives us powerful Foreign function interface FFI that lets you use JavaScript packages, global variables, and even raw javascript in your Reason code. The only thing that you need to do is to accurately type them to get the benefits from the type system.

Btw if you want to learn more about ReasonML, I streamed 10h live coding Bootcamp on Youtube, that you can view on my channel

ReasonReact

When using Reason for our frontend development, we will use ReasonReact. There are also some community bindings for VueJs, but mainly, when developing for web we will go with ReasonReact. If you've heard about Reason and ReasonReact in the past, recently ReasonReact got a huge update making it way easier to write, so the syntax of creating Reason components now is not only super slick but looks way better than in JavaScript, which was not the case in the past. Also, with the introduction of hooks, it's way easier to create ReasonReact components and manage your state.

Getting started

In official ReasonReact docs, the advised way to create a new project is to start with bsb init command, but let's face it. You probably want to know how to move from JavaScript and Typescript. So in our example, we will start by creating our project with create-react-app.

We will start by running the following command:

npx create-react-app reason-hasura-demo

It will create our basic React app in JavaScript, which we will now change into ReasonReact.

Installation

If it's the first time you set up ReasonML in your environment, it will be as simple as installing bs-platform.

yarn global add bs-platform

Also, configure your IDE by installing appropriate editor plugin

I use reason-vscode extension for that. I also strongly advise using "editor.formatOnSave": true, vscode setting, because Reason has a tool called refmt which is basically built in Prettier for Reason, so your code will be properly formatted on save.

Adding ReasonML to your project

Now it's time to add ReasonML. We will install bs-platform and reason-react dependencies.

yarn add bs-platform --dev --exact
yarn add reason-react --exact

And get into the configuration. For that create bsconfig.json file with the following configuration:

{
  "name": "hasura-reason-demo-app",
  "reason": { "react-jsx": 3 },
  "bsc-flags": ["-bs-super-errors"],
  "sources": [
    {
      "dir": "src",
      "subdirs": true
    }
  ],
  "package-specs": [
    {
      "module": "es6",
      "in-source": true
    }
  ],
  "suffix": ".js",
  "namespace": true,
  "bs-dependencies": [
    "reason-react"
  ],
  "ppx-flags": [],
  "refmt": 3
}

Let's also add compilation and watch scripts to our package.json

"re:build": "bsb -make-world -clean-world",
"re:watch": "bsb -make-world -clean-world -w",

If you run these scripts, what will basically happen is all .re files in your project will be compiled to javascript alongside your .re files.

Start configuring our root endpoint

Let's write our first reason file, by changing index.js from

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import * as serviceWorker from './serviceWorker';

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

// If you want your app to work offline and load faster, you can change
// unregister() to register() below. Note this comes with some pitfalls.
// Learn more about service workers: https://bit.ly/CRA-PWA
serviceWorker.unregister();

Basically what I am doing here is render my App component into the dom with

And with

I import register and unregister methods from serviceWorker.js file so I can use Javascript in Reason.

to run our project, we need to run

npm run re:watch

so our Bucklescript will build files for the first time and watch for changes whenever new files are added.

and in different tab let's just run npm start and see our React app.

Basic styling

Styling with ReasonML can be either typed due to bs-css which is based on emotion or untyped. For simplicity, we will use untyped. Let's delete index.css and App.css we have from 'create-react-app', create styles.css file and import two packages:

yarn add animate.css
yarn add tailwind --dev

now in our styles.css file, we will import tailwind

@tailwind base;

@tailwind components;

@tailwind utilities;

and add styles build script in package.json

"rebuild-styles": "npx tailwind build ./src/styles.css -o ./src/index.css",

Writing our first component.

Let's rename our App.css file to App.re, delete all its contents, and write simple ReasonReact component.

Nice right? With ReasonML, we don't need to import or export packages, and in fact, each file is a module, so if our file name is App.re, we can simply use component in a different file.

String to element

In ReasonReact, if you want to add text in component, you do it by using ReasonReact.string

Also, I prefer the following syntax:

You will see it quite a lot in this project. This syntax is reverse-application operator or pipe operator that will give you an ability to chain functions so f(x) is basically written as x |> f.

Now you might say, but wait a second that will be a tedious thing to do in ReasonReact. every string needs to be wrapped with ReasonReact.string. There are various approaches to that.

A common approach is to create utils.re file somewhere with something like

let ste = ReasonReact.string and it will shorten our code to

Through the project, I use ReasonReact.string with a pipe so the code will be more self-descriptive.

What we will be creating

So now when we have our ReasonReact app, it's time to see what we will be creating in this section:

This app will be a simple blog, which will use GraphQL API, auto-generated by Hasura, will use subscriptions and ReasonReact.

Separate app to components

We will separate apps to components such as Header, PostsList, Post AddPostsForm and Modal.

Header

Header will be used for top navigation bar as well as for rendering "Add New Post" button on the top right corner, and when clicking on it, it will open a Modal window with our AddPostsForm. Header will get openModal and isModalOpened props and will be just a presentational component.

We will also use javascript require to embed an SVG logo in the header.

Header button will stop propagation when clicked using ReactEvent.Synthetic ReasonReact wrapper for React synthetic events and will call openModal prop passed as labeled argument (all props are passed as labeled arguments in ReasonReact).

Modal

Modal component will also be a simple and presentational component

For modal functionality in our App.re file, we will use useReducer React hook wrapped by Reason like so:

Notice that our useReducer uses pattern matching to pattern match on action variant. If we will, for example, forget Close action, the project won't compile and give us an error in the editor.

PostsList, Post

Both PostsList and Post will be just presentational components with dummy data.

AddPostForm

Here we will use React setState hook to make our form controlled. That will be also pretty straightforward:

onChange event will look a bit different in Reason but that mostly because of it's type safe nature:

<input onChange={e => e->ReactEvent.Form.target##value |> setCoverImage
}/>

Adding GraphQL Backend using Hasura

Now it's time to set GraphQL backend for our ReasonReact app. We will do that with Hasura.

In a nutshell, Hasura auto-generates GraphQL API on top of new or existing Postgres database. You can read more about Hasura in the following blog post blog post or follow Hasura on Youtube [channel](https://www.youtube.com/c/hasurahq.

We will head to hasura.io and click on Docker image to go to the doc section explaining how to set Hasura up on docker.

We will also install Hasura cli and run hasura init to create a folder with migrations for everything that we do in the console.

Once we have Hasura console running, let's set up our posts table:

and users table:

We will need to connect our posts and users by going back to posts table -> Modify and set a Foreign key to users table:

We will also need to set relationships between posts and users so user object will appear in auto-generated GraphQL API.

Let's head to the console now and create first dummy user:

mutation {
  insert_users(objects: {id: "first-user-with-dummy-id", name: "Test user"}) {
    affected_rows
  }
}

Let's now try to insert a new post:


mutation {
  insert_posts(objects: {user_id: "first-user-with-dummy-id", title: "New Post", content: "Lorem ipsum - test post", cover_img: "https://images.unsplash.com/photo-1555397430-57791c75748a?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=500&q=80"}) {
    affected_rows
  }
}

If we query our posts now will get all the data that we need for our client:

query getPosts{
  posts {
    title
    cover_img
    content
    created_at
    user {
      name
      avatar_url
    }
  }
}

Adding GraphQL to our app

Let's install a bunch of dependencies to add GraphQL to our ReasonReact app and start getting blog posts in real-time.

yarn add @glennsl/bs-json apollo-boost apollo-link-ws graphql react-apollo reason-apollo subscriptions-transport-ws

When we work with Reason, we want to run an introspection query to our endpoint so we will get our graphql schema introspection data as json. It will be used to give us graphql queries completion and type checking in the editor later on, which is pretty cool and best experience ever.

yarn send-introspection-query http://localhost:8080/v1/graphql

We also need to add bs-dependencies to our bsconfig.json

"bs-dependencies": [
    "reason-react",
    "reason-apollo",
    "@glennsl/bs-json"
  ],
  "ppx-flags": ["graphql_ppx/ppx"]

We've added graphql_ppx ppx flag here - that will allow us to write GraphQL syntax in ReasonML later on.

Now let's create a new ApolloClient.re file and set our basic ApolloClient

Adding queries and mutations

Queries

Let's head to our PostsList.re component and add the same query we ran previously in Hasura graphiql:

Now we can use GetPostsQuery component with render prop to load our posts. But before that, I want to receive my GraphQL API result typed, so I want to convert it to Records.

It's as simple as adding types in PostTypes.re file

and opening them in any file that will use them open PostTypes

The final version of PostsList component will look as following:

Mutations

To add mutation to our AddPostForm, we start in the same way as with queries:

The change will be in the render prop. We will use the following function to create variables object:

let addNewPostMutation = PostMutation.make(~title, ~content, ~sanitize, ~coverImg, ());

to execute mutation itself, we simply need to run

mutation(
  ~variables=addNewPostMutation##variables,
  ~refetchQueries=[|"getPosts"|],
  (),
) |> ignore;

The final code will look like this:

Adding Subscriptions

To add subscriptions we will need to make changes to our ApolloClient.re. Remember we don't need to import anything in Reason, so we simply start writing.

Let's add webSocketLink

and create a link function that will use ApolloLinks.split to target WebSockets, when we will use subscriptions or httpLink if we will use queries and mutations. The final ApolloClient version will look like this:

Now to change from query to subscription, we need to change word query to subscription in graphql syntax and use ReasonApollo.CreateSubscription instead of ReasonApollo.CreateQuery

Summary and what's next

In this blog post, we've created a real-time client and backend using Hasura, but we haven't talked about Serverless yet. Serverless business logic is something we will look into in the next blog post. Meanwhile, enjoy the read and start using ReasonML.

You can check out the code here:
https://github.com/vnovick/reason-demo-apps/tree/master/reason-hasura-demo and follow me on Twitter @VladimirNovick for updates.

Building AR apps in React Native, powered by GraphQL using Hasura

Vladimir Novick — Tue, 18 Jun 2019 13:55:12 +0000

Reality 2.0. This is how I tend to call Augmented Reality in the last half a year. Why is that?
I honestly believe that Augmented reality already at the stage of getting out of the field of "gimmicky" tech and got into the stage, where businesses seriously consider adding AR experiences for consumers. Location-based AR, casual games, retail, real estate. You name it. AR got to the point where it's still not ready yet in our smart glasses or "Black mirror type" contact lenses, but we have it on our phones with the help of ARKit and ARCore.

How it works

Now if you are not familiar with the later, ARKit and ARCore are frameworks by Apple and Google respectively that brings AR tech to any modern phone. In a nutshell, it has basic environment understanding and motion tracking that enables developers not only to render 3d content in the real world but to "anchor it" to recognized surfaces. For instance, pointing your phone camera, you can recognize your office desk as a surface and render a 3d model on it. The cool part is because of motion tracking when you walk around the model, it will seem to be on the same spot in the physical world where you've rendered it. It can enable you to create various experiences that bring real-world context to your app or vice versa.

React Native is the future of mobile apps

React Native has revolutionized mobile apps creation experience in recent years, and naturally, there is a demand for ARKit and ARCore solutions for developers specializing in React Native. Usually, the standard with creating AR solutions will be to go to the Unity3d game engine and create AR apps with a pretty straightforward workflow. Developers get excellent visual editor where they can work with 3d content, and the code they write is cross-platform - compatible for both iOS and Android.

So what if you need to embed AR Content in your existing React Native app. Or what if AR is just a part of a more extensive app written in React Native. There are several solutions there. In this blog post, we will talk though not about how to embed Unity content into our React Native app, which is also possible, but develop simple AR experiences using React components. And we will do so with a framework called ViroReact

Creating AR content in Viro.

ViroReact gives you rendering engine powered by ARKit and ARCore and supplies with a bunch of React Components and events that you can use to layout your AR app. In addition to that, it has all the following features described in the image below.

Getting started

To get started, you need to go to Viro website and sign up to get an API key. Follow quick start guide there to get up and running with simple Hello World app.

In a nutshell, it will be as simple as running.

npm install -g react-viro-cli
react-viro init MyAwesomeApp

When you do that you will have a basic app that you can run using Viro testbed app. You will need to add API key, to App.js file though

Alternatively, if you want to run it natively on your device, you can run ./setup-ide.sh - This script will set up your development environment for iOS, Android, or both. You can read more about that here for Xcode or for Android, here

Building blocks

The first and the most essential building block of any AR scene is <ViroARSceneNavigator> component. This component is the one you pass your apiKey to and pass your initialScene prop. Take a look at this example here:


      <ViroARSceneNavigator 
        apiKey="1839C275-6929-45AF-B638-EF2DEE44C1D9"
        numberOfTrackedImages={this.props.numberOfTrackedImages || 1}
        initialScene={{
          scene: this.props.navigation.state.params.screenType === "portal" ? ARPortalsScene: MarkerScreen,
          passProps: this.props.navigation.state.params
        }}
      />

Here we will specify an AR screen to be either ARPortalsScene scene or MarkerScreen. basically, we will be creating this experience:

Marker screen is the screen where we recognize the marker and show text data for every marker with slight animation. The portal screen is self-descriptive and is the one where you've seen a doorway to VR world from which you can still view our real world.

The portal

Let's actually start with the portal scene. Before loading the portal, you've seen a gray quad rendered on the ground. This quad is basically created by using ViroARPlaneSelector component, and it gives us an ability to select a recognized surface, and while it is selected, this component will render its children on the surface.

So the code for rendering the portal will look like this:

<ViroARPlaneSelector dragType="FixedToWorld">
   <ViroPortalScene passable={true} dragType="FixedDistance" onDrag={()=>{}}>
      <ViroPortal scale={[.5, .5, .5]}>
          <Viro3DObject onLoadStart={() => { alert("Loading portal") }}
              source={require('../res/portal_wood_frame.vrx')}
              resources={[require('../res/portal_wood_frame_diffuse.png'),
                                    require('../res/portal_wood_frame_normal.png'),
                                    require('../res/portal_wood_frame_specular.png')]}
              type="VRX"
          />
       </ViroPortal>
       <Viro360Image source={{ uri: data.portals_by_pk.portalMedia360 }} />
   </ViroPortalScene>
</ViroARPlaneSelector>

As you can see, we use helper components provided by Viro to both load .fbx model (.vrx is a FBX format extension passed through Viro compression script) and 360 image (can also be a video)

The marker

The marker will use ViroARImageMarker helper component to render specific data for every marker. The code will be as following.

              return (
                <ViroARImageMarker target={"businessCard"} 
                  onAnchorFound={
                    () => this.setState({
                        runAnimation: true
                    })}
                >
                <ViroNode key="card" onTouch={() => alert("twitter")}>
                  <ViroNode 
                    opacity={0} position={[0, -0.02, 0]} 
                    animation={{
                      name:'animateImage', 
                      run: this.state.runAnimation 
                      }}
                  >
                    <ViroFlexView 
                        rotation={[-90, 0, 0]}
                        height={0.03} 
                        width={0.05}
                        style={styles.card} 
                    >
                      <ViroFlexView 
                        style={styles.cardWrapper} 
                      >
                        <ViroImage
                          height={0.015}
                          width={0.015}
                          style={styles.image}
                          source={{uri: markerData.user.avatarUrl}}
                        />
                        <ViroText 
                          textClipMode="None"
                          text={`${markerData.user.name} ${markerData.user.lastname}`}
                          scale={[.015, .015, .015]}
                          style={styles.textStyle}
                        />
                      </ViroFlexView>
                      <ViroFlexView 
                        style={styles.subText} 
                      >
                        <ViroText 
                          width={0.01}
                          height={0.01}
                          textAlign="left"
                          textClipMode="None"
                          text={`@${markerData.user.twitterProfile}`}
                          scale={[.01, .01, .01]}
                          style={styles.textStyle}
                        />
                        <ViroAnimatedImage
                          height={0.01}
                          width={0.01}
                          loop={true}
                          source={require('../res/tweet.gif')}
                        />
                      </ViroFlexView>
                    </ViroFlexView>
                  </ViroNode>  
                  <ViroNode opacity={0} position={[0, 0, 0]} 
                    animation={{
                      name:'animateViro', 
                      run: this.state.runAnimation 
                    }}
                  >
                    { markerData.bottomBar && <ViroText text={markerData.bottomBar}
                      rotation={[-90, 0, 0]}
                      scale={[.01, .01, .01]}
                      style={styles.textStyle}
                  /> }
                  </ViroNode>
                </ViroNode>
                </ViroARImageMarker>

Here you can see we are using a bunch of other components such as ViroNode for grouping content and ViroFlexView, so we can layout text in AR world using flexbox. We also have sliding animations created etc.

What about the data

You've probably already noticed that we don't have hardcoded values and in fact, actual data comes from GraphQL API that was autogenerated with Hasura.

Hasura GraphQL

If it's the first time you hear about Hasura I strongly suggest to check out this blog post about it here or here

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

In a nutshell, Hasura can auto-generate GraphQL API from your Postgres DB either a new or existing one; it gives you impressive management console for both your data, graphql api, auth, access control, business logic and more. It provides you with various options of adding your business logic whether you prefer more synchronous approach or ready to step forward and use 3factor.app architecture for your modern apps. You can read more about adding your business logic here:

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

So what is crucial for us is to get real-time data also in our AR world. Let's start by creating our backend

Creating backend with Hasura

Head over to hasura.io and use any method of deploying the engine that you prefer. I will use Heroku. After deploying the engine, I will be presented with empty Hasura console where we will start adding our data

Head to the Data tab and let's create the following tables:

model_resources - will hold resources for 3d models (textures and such)

models - will hold 3d models obj urls, scaling, lighting models and will have a relationship to model_resources table

markers - will hold data for our markers and will have a relationship to users and models table

portals - Will hold data for our portals

users - we will have a dummy login in this app, but you can implement proper authentication by checking out the following blog post:

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

After you set all of this in the newly created engine, Hasura will auto-generate GraphQL API for you including really performant subscriptions which we will be using in our AR app.

Setup your client

Now it's time to head to our Viro app and actually, remove all example content we had and start by creating basic React Native app with GraphQL. If you are new to React Native and GraphQL, I strongly suggest checking learn.hasura.io tutorial on React Native.

Our AppScreen in App.js code from being just ViroSample will turn to something like this:



const mkWsLink = (uri) => {
  const splitUri = uri.split('//');
  const subClient = new SubscriptionClient(
    'wss://' + splitUri[1],
    { reconnect: true }
  );
  return new WebSocketLink(subClient);
}


const wsLink = mkWsLink(GRAPHQL_ENDPOINT)
const httpLink = new HttpLink({ uri: GRAPHQL_ENDPOINT });
const link = split(
  // split based on operation type
  ({ query }) => {
    const { kind, operation } = getMainDefinition(query);
    return kind === 'OperationDefinition' && operation === 'subscription';
  },
  wsLink,
  httpLink
);

// Creating a client instance
const client = new ApolloClient({
  link,
  cache: new InMemoryCache({
    addTypename: false
  })
});


export default class AppScreen extends React.Component {
  render() {
    return(
      <ApolloProvider client={client}>
        <RootNavigator
          client={client}
          session={this.props.sessionInfo}
        />
      </ApolloProvider>
    )
  }
}

As you can see we have ApolloProvider which sets our apollo client on React context, so it can be accessed through Subscription component later on.

Navigation

Let's take a look at our RootNavigator


const AppStack = createBottomTabNavigator({
  Markers: createStackNavigator({ 
    Home: Home, 
    ARScreen: ARScreen 
  }),
  Portals: createStackNavigator({ 
    Portals: PortalsList, 
    ARPortalScreen: ARScreen 
  })
});
const AuthStack = createStackNavigator({ SignIn: SignIn }); 

export default createAppContainer(createSwitchNavigator(
  {
    AuthLoading: AuthLoadingScreen,
    App: AppStack,
    Auth: AuthStack,
    Upload
  },
  {
    initialRouteName: 'AuthLoading',
  }
));

As you can see here our initial screen will be AuthLoading screen, but both Markers tab and Portals tab will have a stack that will have purely react native screen with a list of markers/portals and ARScreen.

We've already seen ARScreen previously but it looks like that:

 getARView() {
    return this.state.arEnabled ? (
      <ViroARSceneNavigator 
        apiKey=API_KEY
        numberOfTrackedImages={this.props.numberOfTrackedImages || 1}
        initialScene={{
          scene: this.props.navigation.state.params.screenType === "portal" ? ARPortalsScene: MarkerScreen,
          passProps: this.props.navigation.state.params
        }}
      />
    ) : null
  }

  render() {
    return (
      <SafeAreaView style={styles.container}>
        {this.getARView()}
        <View style={styles.bottomTab}>
          <Button text="Go Back" onPress={this._goBack} />
        </View>
      </SafeAreaView>
    )
  }

Subscriptions work in both AR and mobile world

Now the only thing we are left to do is to head to our MarkerScreen.js and wrap our Marker with Subscription. MarkerScreen render function looks like this:

  render() {
    return (
      <ViroARScene onTrackingUpdated={this._onInitialized} >
      <ViroDirectionalLight color="#777777"
        direction={[0, -1, -2]}
        shadowOrthographicPosition={[0, 8, -5]}
        shadowOrthographicSize={10}
        shadowNearZ={2}
        shadowFarZ={9}
        lightInfluenceBitMask={2}
        castsShadow={true} 
      />
        { this.state.isTracking ? this.getNoTrackingUI() : this.getARScene()}

      </ViroARScene>
    );
  }

Basically, we wrap our scene in ViroARScene component to bring AR capabilities to React Native leveraging ViroReact and ARKit/ARCore frameworks.
We've seen previously how marker code looks like, so now the only thing that is left to do is to wrap it with Subscription

const MARKER_DETAILS = gql`
subscription fetchMarker($markerId: uuid!) {
  markers_by_pk(id: $markerId) {
    user {
      name
      lastname,
      twitterProfile,
      avatarUrl
    }
    bottomBar
  }
}
`;


getARScene() {
    return (
      <ViroNode>
          <Subscription subscription={MARKER_DETAILS} variables={{ markerId: this.props.id }}>
            {({loading, error, data }) => {
              if (error) {
                alert("Error", "Could not fetch marker");
                return null;
              }

              if (loading) {
                return (
                  <LoadingComponent text="Loading Marker" />
                )
              }

              const markerData = data.markers_by_pk
              if (this.props.is3d) {
                return this.render3d()
              }
              return (
                <ViroARImageMarker target={"businessCard"} 
                  onAnchorFound={
                    () => this.setState({
                        runAnimation: true
                    })}
                >

// rest of marker code

The result will look as follows:

Summary

As you have seen in this blog post adding AR content to your React Native is not a rocket science and can be done pretty easily with a basic understanding of 3d environments. This AR content can be similarly connected to GraphQL API as regular React Native apps. And Hasura will make this step really easy and straightforward for you.

I haven't covered all the code from this sample app, but it's available here for you to check.
In the last few months, I also gave several talks on this topic featuring this demo app and explaining more on AR parts so check out a talk from DevDays Europe:

Slides are available here

If you want to learn more about AR and GraphQL combination, I will teach an AR and GraphQL workshop at Chain React 2019 conference so if you are interested in more guided hands-on experience with this, you are welcome to get tickets for it.

And on the final note before concluding this blog post, On a weekly basis, I or someone from the team at Hasura.io streams something cool on twitch.tv/hasurahq and upload that on our Youtube channel so make sure you are aware of our next events. For instance, yesterday, I streamed a detailed code overview of the same AR app we've just seen.

If you have any questions you are free to reach out to me by filling the contact form on my website: vnovick.com or by sending me DM on Twitter @VladimirNovick

Developer advocacy and consulting or what I actually do on a daily basis

Vladimir Novick — Fri, 31 May 2019 13:03:39 +0000

Hi there, recently I am being asked lots of question regarding what do I do on a daily basis. I travel a lot and speak at lots of conferences, so some people usually ask me if I actually code or just teach. So in this blog post, I will try to answer this question and what I actually do on a daily basis.

Developer Advocate @Hasura.

I work as Developer Advocate @Hasura and my day to day tasks include recording courses, teaching, going to conferences, doing workshops, working on cool demos, dev tools and so on. I absolutely love what I do and in fact, I've been doing this in my spare time even before being Developer Advocate. Now it's just a part of my job. I am fairly new to the Developer relations realm so I am still learning how to share the best content and collect the most valuable feedback that will benefit both the community. So if you follow me on twitter @VladimirNovick and have a suggestion of what tutorial/bootcamp/workshop or cool demo you want to see next or just have general feedback on what I do, don't hesitate to DM me and I will gladly hear you out.

Consultant in Web, Mobile, AR, VR, IoT fields

Some people ask me - "what about production code, complex apps, brainstorms and so on? What about solving complex problems beyond POCs and demos?". So what about all that? Did I change my specialization from being an Independent consultant for more than a decade on so many fields to Developer Advocate to abandon all of those and not to be involved in real-world problems and projects?

Well, the answer is no. I can never abandon the necessity to write code. I was into computers since I've been 7 years old and I simply cannot do that. Moreover, I never abandoned being a consultant and while I do work as Developer Advocate I usually find time for clients to consult on different projects in Web, Mobile, AR, VR and IoT fields. In fact, being Developer Advocate at Hasura helps a lot with these projects too cause now I can suggest a really good GraphQL and Serverless solutions to my clients making development faster.

So what's the purpose of this blog post?

Well, first of all, to explain that I never abandoned writing production code, after all, this is one of my basic needs 😉. Second to people wondering if they can reach out and book me for consulting, development, etc, sure, you can always drop me a line on twitter DMs @VladimirNovick and I will gladly hear you out and we might figure out how I can help you with your project. And if you don't favor twitter DMs and you want to learn more about myself, you can check my website with a bunch of social network profiles. https://vnovick.com

Different ways of adding your Business logic to Hasura

Vladimir Novick — Sat, 25 May 2019 14:25:14 +0000

Recently I taught GraphQL workshop at React Europe to 80 brilliant React developers.

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

Apart from being on top of things they asked me really nice questions, one of which was "How you add your Business Logic to Hasura?". I am asked this question for quite a while, so I decided to explain different ways of how to do that.

In GraphQL workshop we've used Hasura to create our backend, and in fact, you can read more about Hasura here and follow 30 minutes hands-on course to set up your GraphQL endpoint for free along with proper authentication and authorization at learn.hasura.io. In short - production ready backend that can support 10k concurrent subscriptions, which is a pretty substantial number.

So back to our question - "How do you add your Business logic to Hasura?". Hasura not only generates GraphQL API, but it also gives you great tools to add your GraphQL server, write custom reducers or trigger serverless functions using the eventing system.

So now, let's divide our Business logic into two categories:

First, more traditional (synchronous) approach

You have several methods of adding your custom logic in a synchronous way, but high-level architecture looks like this.

Basically, it means that you write GraphQL server or custom resolvers and Hasura takes care of schema stitching.

1. Creation full blown GraphQL server.

We can use any GraphQL server because any graphql endpoint exposes type information and Hasura can easily stitch two schemas together. So to add your GraphQL server you go to Remote Schemas tab and add a new remote schema like so:

In this example, I'm adding star wars API as a remote schema. You also can see that I can pass any headers to my custom graphql server so if you have your custom authorization of graphql server endpoint, you can pass proper token or headers easily.

So what you should do in the server? Here you also have several options.
Let's assume you want direct database control. So your app is executing mutation to Hasura graphql endpoint. Hasura forwards that to your custom GraphQL server, and on your server, you write data into a database after executing your logic. The cool part is because Hasura supports subscriptions and live queries out of the box; any change that is done on the database will propagate to any client subscribed to this change.

The architecture will look like this:

If you don't want direct access, you can basically reuse the fact that Hasura generates GraphQL CRUD for you and instead of opening a connection to a database, you can simply execute GraphQL mutation from Hasura endpoint. Changing architecture to something like this:

What does it mean? It means that even if you have GraphQL server with everything already done, you still can use Hasura to provide you with an authorization layer with permissions and access control management. And you won't need to implement subscriptions or live queries because the engine already implements them.

2. Writing custom resolvers

Now, what about more granular business logic? What if you want to write dedicated resolvers. The idea is pretty much the same as custom GraphQL server, but instead of having a big schema, that will be exposed and stitched into Hasura, you will have only one resolver for your specific needs.

For example check out this resolver which is taken from Hasura learn tutorial:



const { ApolloServer } = require('apollo-server');
const gql = require('graphql-tag');
const jwt = require('jsonwebtoken');
const fetch = require('node-fetch');
const typeDefs = gql`
  type auth0_profile {
      email: String
      picture: String
    }
    type Query {
      auth0: auth0_profile
    }
`;
function getProfileInfo(user_id){
    const headers = {'Authorization': 'Bearer '+process.env.AUTH0_MANAGEMENT_API_TOKEN};
    console.log(headers);
    return fetch('https://' + process.env.AUTH0_DOMAIN + '/api/v2/users/'+user_id,{ headers: headers})
        .then(response => response.json())
}
const resolvers = {
    Query: {
        auth0: (parent, args, context) => {
          // read the authorization header sent from the client
          const authHeaders = context.headers.authorization;
          const token = authHeaders.replace('Bearer ', '');
          // decode the token to find the user_id
          try {
            const decoded = jwt.decode(token);
            const user_id = decoded.sub;
            // make a rest api call to auth0
            return getProfileInfo(user_id).then( function(resp) {
              console.log(resp);
              if (!resp) {
                return null;
              }
              return {email: resp.email, picture: resp.picture};
            });
          } catch(e) {
            console.log(e);
            return null;
          }
        }
    },
};
const context = ({req}) => {
  return {headers: req.headers};
};
const schema = new ApolloServer({ typeDefs, resolvers, context});
schema.listen({ port: process.env.PORT}).then(({ url }) => {
    console.log(`schema ready at ${url}`);
});

As you can see it's super small, but what it does is it exports proper GraphQL schema which gets data even not from Postgres database, but from Auth0. It means that your custom resolvers can basically be hosted anywhere as soon as they expose GraphQL schema and they can do anything that you want including connecting to Microservices APIs, Third Party or just sending an email. It's up to you what to write there.

Second approach - 3factor.app architecture (asynchronous)

What about the second way of adding business logic? The approach is different, and it is described in 3factor.app architecture proposal. The idea of 3factor.app architecture is having async serverless, reliable eventing, and Realtime GraphQL (subscriptions and live queries) as 3 essential factors of modern software architecture.

In fact, at React Europe, I gave a talk which was called "Redux style backends."

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

The main concept was to bring Redux mental model to software architecture. It looks like this:

The idea behind this is that Database is your state, Eventing system purpose is to trigger events(actions) which will call serverless functions(reducers) to execute custom logic. Serverless functions, in turn, will call mutations on Hasura GraphQL Endpoint changing state to a new one. In the end, because of real-time GraphQL, everything will be propagated to the client through subscriptions and live queries.

1. Serverless functions

To add serverless function as an event trigger, you need to go to the Event trigger tab and add it there. You will have a bunch of options that you can include such as trigger events only on specific column updates and so on

If you are interested in checking a live example, I've live-streamed serverless function with Netlify some time ago on our Hasura Twitch stream, so you can check it here:

2. Using the eventing system to trigger webhooks

Serverless functions attached to event triggers are not the only thing you can do with events. Basically any url can be attached to event and it's up to you what you do inside. Let's take a look at example from [Hasura learn tutorial] of creating an event trigger for sending email:



const nodemailer = require('nodemailer');
const transporter = nodemailer.createTransport('smtp://'+process.env.SMTP_LOGIN+':'+process.env.SMTP_PASSWORD+'@' + process.env.SMTP_HOST);
const fs = require('fs');
const path = require('path');
const express = require('express');
const bodyParser = require('body-parser');
const app = express();
app.set('port', (process.env.PORT || 3000));
app.use('/', express.static(path.join(__dirname, 'public')));
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({extended: true}));
app.use(function(req, res, next) {
    res.setHeader('Access-Control-Allow-Origin', '*');
    res.setHeader('Cache-Control', 'no-cache');
    next();
});
app.post('/send-email', function(req, res) {

  const name = req.body.event.data.new.name;
  // setup e-mail data
  const mailOptions = {
      from: process.env.SENDER_ADDRESS, // sender address
      to: process.env.RECEIVER_ADDRESS, // list of receivers
      subject: 'A new user has registered', // Subject line
      text: 'Hi, This is to notify that a new user has registered under the name of ' + name, // plaintext body
      html: '<p>'+'Hi, This is to notify that a new user has registered under the name of ' + name + '</p>' // html body
  };
  // send mail with defined transport object
  transporter.sendMail(mailOptions, function(error, info){
      if(error){
          return console.log(error);
      }
      console.log('Message sent: ' + info.response);
      res.json({'success': true});
  });

});
app.listen(app.get('port'), function() {
  console.log('Server started on: ' + app.get('port'));
});

As you can see, it's a straightforward express server that sends mail based on event payload, it receives.

Summary

As you can see there are lots of options to add your business logic to Hasura, but if you have doubt and not sure how to integrate Hasura with your existing architecture, contact us on Discord, and we will figure out how to help.

Using Amplify CLI for adding Auth to your Hasura GraphQL engine

Vladimir Novick — Mon, 22 Apr 2019 06:34:13 +0000

Let's assume you already played around with Hasura open source GraphQL engine and you were wondering how to add an authentication layer with AWS Cognito. Couple of words about Hasura if you are not familiar. Hasura is free and open source engine that auto generates GraphQL API on top of new or existing Postgres database. If this is the first time you hear about it, I suggest to check my introductory article here:

Vladimir Novick

@vladimirnovick

I just published Effortless Real-time GraphQL API with serverless business logic running in any cloud link.medium.com/DET666lI3T

11:47 AM - 05 Feb 2019

and if you were wondering about how to use Authentication with Hasura you can read about it here:

Vladimir Novick

@vladimirnovick

Just published a blog post explaining @HasuraHQ Authentication options including @awscloud Cognito, @auth0, @Firebase, custom auth servers or custom auth webhooks. Check it out.
dev.to/hasurahq/hasur…

06:38 AM - 08 Apr 2019

In last article I showed AWS Cognito as one of solutions how to create your authentication for your app and pass Auth token to Hasura. In this article I want to explain how you do that with aws-amplify CLI as well as how you connect your users to actual cognito user pool users.

In a nutshell we will cover

How to deploy Hasura
How to setup aws amplify with aws cognito
How to setup a AWS lambda to update our database after user is created in cognito
Customise cognito JWT creation to enable hasura permission rules

Creating and deploying our engine
Setting up Hasura CLI
Setting our database structure
Setting our Auth with Amplify CLI
Creating your Frontend
Adding a new User pool user into Hasura
- Pre Sign-Up Lambda
- Pre token generation Lambda
- Create Roles in Hasura Permission system

Creating and deploying our engine

Let's start by regular step of Deploying to Heroku

We also can use AWS RDS to deploy our engine which is described in detail here

Now before we setting any auth or continue in general we will secure our endpoint by setting HASURA_GRAPHQL_ADMIN_SECRET

Setting up Hasura CLI

We want changes done in our console to be reflected as migrations files and stored in source control as explained in detail here

What we will do is set HASURA_GRAPHQL_ENABLE_CONSOLE to false in our heroku config vars

Now it's time to init our hasura project with through Hasura CLI

hasura init --endpoint https://aws-sample.herokuapp.com

And then

cd hasura
hasura console --admin-secret=<your admin secret>

Console will open up on localhost and whatever you do in the console will be saved in local migration files that you can store in source control.

Setting our database structure

Now when we have our engine set up, we need to create database structure. We will create simple blog cms so we will have only posts and users table. Important part is that users table id have to be of a text format so we can wire it up with AWS user pool properly.

Posts table will look like this:

User table will look like this:

I also added object relationship from posts userId to user object

so we can query our users from posts query like so

query {
  posts {
    title
    content
    user {
      name
    }
  }
}

Now when our backend ready it's time to set up our frontend and authentication.
Now I don't know what frontend framework you use, so I will use React for this example, but the process is similar in Vue and Angular. I hardly will touch Frontend here. My main goal is so you will understand the flow.

Setting our Auth with Amplify CLI

npm install -g @aws-amplify/cli
amplify configure

This will open up the AWS console. Once you are logged in to the console you can jump back to the command line. Then we need to specify AWS region.

In the next step we will need to specify a new AWS IAM user we about to create.
It will open up IAM dashboard with the user we already set up with the one we specified through CLI.

Next we will need to set up AWS permissions. I will just click Next, Review and will create a user. You will be presented with a screen with Access key and secret which you should type in amplify cli

Creating your Frontend

We will use Amplify auth module with React, but you can choose your own favorite framework. Check Amplify Vue docs and Angular docs for more detail.

we will start by creating our frontend with

npx create-react-app react-frontend

and then run

amplify init

To add basic authentication with User pools run amplify add auth with default configuration. After adding auth we need to deploy it to AWS. This can be done by running amplify push which will update our resources in the cloud and will add Cognito User Pool

It's time to add auth to our React app:

yarn add aws-amplify aws-amplify-react

In our App.js file let's wrap our app with Amplify withAuthenticator HOC

import Amplify, { Auth } from 'aws-amplify';
import awsmobile from './aws-exports';
import { withAuthenticator } from 'aws-amplify-react'; // or 'aws-amplify-react-native';

Amplify.configure(awsmobile);


export default withAuthenticator(App, true);

What we will be presented is AWS auth screen where we will have sign up, sign in etc. We won't cover how to customize everything for your app, so let's just use the default one

Now let's add some behavior on sign up/sign in.
Whenever our App is authenticated, basically our App component will be rendered.
So if I will add this code to our App.js:

import { Auth } from 'aws-amplify'

//....rest of code

componentDidMount(){
    Auth.currentAuthenticatedUser().then(user => {
      console.log(user)
    })
}

//rest of code

you will be able to get user data.

So far we have authentication, but there is a problem. We need to add this auth data to our Hasura.

Adding a new User pool user into Hasura

If we open our AWS console on User pool tab we will be able to see that we can create custom Triggers for different stages in authentication process. We will need to create at least two triggers. Pre sign-up and pre token generation.

Let's start with sign up trigger

Pre Sign Up Lambda

Let's go to AWS Lambda console and create a new lambda. You will have to create it locally first because we will have node-fetch dependency, so we will need to upload a zip to AWS console. Our lambda index.js file will look like this:

const fetch = require('node-fetch');

const adminSecret = process.env.ADMIN_SECRET;
const hgeEndpoint = process.env.HGE_ENDPOINT;

const query = `
mutation addUser($id: String!, $phone:String!, $email: String!){
  insert_users(objects:[{
    email: $email
    id: $id
    phone: $phone
  }]) {
    returning {
      email
    }
  }
}
`

exports.handler = (event, context, callback) => {

try {
  const qv = {
    email: event.request.userAttributes.email, 
    phone: event.request.userAttributes.phone_number,
    id: event.userName
  };

  fetch(hgeEndpoint + '/v1alpha1/graphql', {
      method: 'POST',
      body: JSON.stringify({query: query, variables: qv}),
      headers: {'Content-Type': 'application/json', 'x-hasura-admin-secret': adminSecret},
  })
  .then(res => res.json())
  .then(json => {
      callback(null, event);
  });


} catch (e) {
  callback(null, false)
}


};

What we are trying to do here is to insert a new user to database by executing mutation. You can notice that we pass our Admin Secret at headers, but this is fine for server to server communication. What is happening here is that our id will be cognito username

Let's try to Sign Up now.

We will get notification mail with our verification code

Now we can sign in and see our Auth token in the console.

The cool part is also that we will have our user created in Postgres. Let's check our console:

Pre Token Generation lambda

We are getting our token, but it's not enough. If we want to use JWT_TOKEN with Hasura we need to do several things. (I explained JWT auth in details here):

Set `HASURA_GRAPHQL_JWT_SECRET`

Set HASURA_GRAPHQL_JWT_SECRET as env variable in our Heroku. Our config will be:

{
"type":"RS256",
    "jwk_url": "https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-    known/jwks.json",
"claims_format": "stringified_json"
}

Note that {userPoolId} should be substituted to your userPoolId taken from AWS console as well as {region} to correct region you are using

Create our Pre Token generation lambda.

For our pre token generation lambda we need to add custom claims. We will pass username as user id so we will be able to reference it in Hasura permission system

exports.handler = (event, context, callback) => {
    event.response = {
        "claimsOverrideDetails": {
            "claimsToAddOrOverride": {
                "event": JSON.stringify(event.userName),
                "https://hasura.io/jwt/claims": JSON.stringify({
                    "x-hasura-allowed-roles": ["anonymous","user", "admin"],
                    "x-hasura-default-role": event.userName === "vnovick" ? "admin": "user",
                    "x-hasura-user-id": event.userName
                })
            }
        }
    }
    callback(null, event)
}

Let's copy signInUserSession.idToken.jwtToken from Auth.currentAuthenticatedUser() response and paste it in Hasura console as Authorization Bearer token

Now all custom claims will be passed to Hasura permissions system and we will be able to reference them there.

Create Roles in Hasura Permission system

Let's see how it's done. We will create two additional roles - anonymous without any permissions and a user role.

I want user to be able to query only their own user data as well as see only their posts. We can set up permissions in the console accordingly:

user role will be able to see only their own data.

Let's double check that by querying all users:

Summary

This blog post is only a brief overview of what you can do with Hasura and AWS Cognito, but I hope you get the idea of main auth workflow you should stick to. As you can see, because we use Lambda triggers and plug them into Cognito auth process we can do any level of complexity. We can validate if our user exists, add custom variables to hasura custom claims and so on.

After reading this blog post I will appreciate if you can give me feedback what parts you want me to cover more in depth so I can either write another more advanced blog post or lead you to resources explaining these parts.

Create a real time web app with Hasura and Gatsby

Vladimir Novick — Sun, 21 Apr 2019 15:59:51 +0000

A bit more than a month ago we live streamed how to create Gatsby blog with Hasura. This blog post summarizes it. If you haven't watched this video as well as other videos we have on Hasura Youtube channel I strongly suggest to check it out

What we were creating.

The idea was to create a simple blog powered by GraphQL backend. For backend we chose Hasura because lots of reasons I layed out in this blog post:

Vladimir Novick

@vladimirnovick

I just published Effortless Real-time GraphQL API with serverless business logic running in any cloud link.medium.com/DET666lI3T

11:47 AM - 05 Feb 2019

We started by deploying Hasura to Heroku and creating bunch of tables, connecting them with foreign keys and immediately we had queries subscriptions and mutations generated for us by Hasura. We had some weird behaviors though. Columns were dropping, fields were changing. It was kinda weird at first and then we realized that there were people trolling with us. Because endpoint was not secured and console was enabled, people were able to connect to it and change schema.

When we realized that we secured an endpoint by using HASURA_GRAPHQL_ADMIN_SECRET environment variable which we tried to keep secret from our audience. Finally everything was stable and people just could not troll us.

Creating gatsby site

We created our gatsby site by running
gatsby new . gatsbyjs/gatsby-starter-hello-world

to get very basic setup.

Integrating Hasura GraphQL into Gastby

We installed gatsby-source-graphql and configured it to work with HASURA_GRAPHQL_ADMIN_SECRET, but in real world scenario we will have Authorization bearer token, so our gatsby.config will look like this:

const fetch = require("isomorphic-fetch")
const createHttpLink = require("apollo-link-http")


/// Rest of the code

{
  resolve: "gatsby-source-graphql",
  options: {
    typeName: "hasura",
    fieldName: "blog",
    // Create Apollo Link manually. Can return a Promise.
    createLink: () => {
     return createHttpLink({
       uri: 'hasura graphql endpoint',
         headers: {
           'Authorization': `bearer ${token}`,
         },
         fetch,
    })
  },
}

To read more about Authentication you can read it in my blog post "Hasura Authentication Explained

In our live stream we used our admin secret just for simplicity.

Note: You cannot use admin secret in production environment cause your client will be able to do any changes to database

So at that point we were able to query our blog field

Creating pages

We started creating our pages by exporting our query and referencing the data from blog field. Basically under blog field we had all queries that we can run with Hasura engine.

Once we had our first page with a list of blog posts, Jason started creating other pages by using Gatsby createPages api

In order to create these pages programmatically what had to be done is the following:
After getting result from Hasura posts graphql query, create each page programmatically with path/${post.id} path. In that way we were able to link to these pages later on. For post page component we created a new template/post.js file. There we added real time functionality later on.

Adding GraphQL subscriptions

That was a tricky part. Gatsby queries Hasura GraphQL endpoint on build, but we had to add some real time capabilities using subscriptions, so we needed our post page to behave like a single page app of sorts.

So we had to set up Apollo with ApolloProvider and subscriptions. If you've dealt with react-apollo in the past you probably know that you need to create two links and create a new instance of ApolloClient you can read more about it here:

With Gatsby it's similar, but a bit different. We had to create a root element wrapper and specify it in both gatsby-browser.js and gatsby-ssr.js so Gatsby will get it rendered both when doing server side rendering and both when rendering on the client. This element looked like this.

export const wrapRootElement = ({ element }) => (
  <ApolloProvider client={client}>{element}</ApolloProvider>
)

Dealing with SSR and subscriptions

Defining HttpLink on the client is easy, but when SSR is involved you need to pass fetch implementation to HttpLink, so it won't fail.

import fetch from "isomorphic-fetch"

//rest of the code

const http = new HttpLink({
  uri: "https://hasura-gatsby-livestream.herokuapp.com/v1alpha1/graphql",
  fetch,
})

With subscriptions it was similar, but instead of passing fetch we had to use a package ws and do a custom check if we are running in the browser or not:

//...
import ws from "ws"
//...

const wsForNode = typeof window === "undefined" ? ws : null

//...

const wsClient = new SubscriptionClient(
  "wss://hasura-gatsby-livestream.herokuapp.com/v1alpha1/graphql",
  {
    reconnect: true
  },
  wsForNode
)

//...
const websocket = new WebSocketLink(wsClient)

After configuring our apollo in that way we were able to subscribe to changes from our post template by using

useSubscription(SUBSCRIPTION_NAME, { suspend: false }, variables: { id })

Yeah we used React hooks.

Summary

So what is the purpose of this blog post. First of all a recap on something cool we did a bit more than a month ago, second remind that Gatsby can be used with real time data and that Hasura will give you GraphQL API on top of your existing or new Postgres in no time and also to remind that live coding with other folks in the community is one of my top priorities so if you have something you wanna live code together involving Hasura and some other awesome tool, feel free to reach out to me on twitter. My Twitter DMs are open.

And subscribe to our Youtube channel or Join Discord