DEV Community: Sergio Andrés Jaime Sierra

Chapter 3: Let's get into Fauna: a guide to understanding Fauna while creating a social media database

Sergio Andrés Jaime Sierra — Fri, 06 Nov 2020 22:33:07 +0000

In chapter 1, we created a database using the Fauna and Next.js tutorials together, we created some users and logged them in using a project from Next.js.
In chapter 2, we added functionality to follow and post as well as the necessary permissions to do it. Now you have a repository to clone and use it for this purpose.

In this chapter we are going to make use of Fauna’s access control, ABAC (Attribute Based Access Control) to limit what users are allowed to do. For example, they will only be able to create, edit or delete posts if they are the owners. We will create private content and reject access to vip. Also, upper roles and configure post's permissions.

What is ABAC?

We already mentioned what ABAC stands for, but what does it mean? Fauna can access a specific document and the user trying to access it, with this information it can determine if the user trying to access/change the document actually has the permissions to do it. This can help a lot to keep a portion of the user’s information private or prevent changes in a document (e.g. a post) which doesn’t belong to the user trying to change it.

ABAC is composed of two sections: The first one is the Membership, we did already do something about membership in our second chapter: you created a Lambda function that checks the documents in a collection, if the Lambda function returns true, the document has this role.

Let’s use the Fauna’s Dashboard and navigate to Security/Manage Roles/basicUser/Membership

If you followed through the second chapter, you can see the Users collection and should be able to expand it to see a Lambda function. This function has “ref” as a parameter and returns true every time. This means all the users from the Users collection will have this permissions schema. This Lambda function can be changed to include any attribute relatable to the Users collection. For example, the default Lambda function when you are creating a membership goes like this:

Lambda("ref", Select(["data", "vip"], Get(Var("ref"))))

This function uses Get (reads) on the “ref” and then Select(s) the document path data / vip. Here, vip is supposed to contain a boolean stating if the user has a vip (premium) status. You can also check if the user is in a secondary list, like another collection where you can find the references of the admins. Here, we will go through some examples and apply them.

Example 1: Premium content:

Let’s think about this scenario: You don’t have a social network but some premium content your users will be able to see after paying a fee, a lifetime subscription to a service.

Create a collection called PaidVideos.

CreateCollection({name:'PaidVideos'})

Create some documents on it with a field called video:

Map(
  [
    {video:"dQw4w9WgXcQ",text:"Old but gold"},
    {video:"XcgoZO-p9tI",text:"Secret of the forest"},
    {video:"D5q094yRsbA",text:"Tyrano lair"},
    {video:"re0A23CSvpw",text:"Imp’s song"},
    {video:"cM4kqL13jGM",text:"Rebirth of slick"}
  ],
  Lambda(
    "docPayload",
    Create(Collection('PaidVideos'),{data:Var('docPayload')})
  )
)

Create a new function called premiumContent with the following body

Query(
  Lambda(
    [],
    Map(
      Paginate(Documents(Collection("PaidVideos"))),
      Lambda("videoRef", Select("data",Get(Var("videoRef"))))
    )
  )
)

You can see there’s a new method called Documents. This method returns a set containing all the documents of the collection in the argument.

Now, let’s create a new role, head to Security/Manage Roles and press on New Role.

This new role will require the collection PaidVideos, we will grant view permissions, also, the function premiumContent, we will grant call permissions.

Why only these two permissions? As you may remember, any document in Users will have the basicUser’s permissions. Their predicate function always returns true. Any document in Users who also has a field called vip with a value of true will have the basicUser’s permissions as well as the premiumUser’s.

Now, head to the Membership tab, add the collection Users and use the function provided by Fauna.

Put a name on your new role, I used premiumUser, you can pick any name you like, but we will use this name here when referring to this role.

Take one or two of your existing users and Update them to have a new field vip:true, this will enable them as premiumUser

If you cloned this repository at the beginning of the lesson, you can switch to the branch called third-chapter-end to update your repository to test this functionality.

Log in with any user valid to premiumUser (the ones we updated to have vip:true), click on the new tab labeled premium.

If the user has the attribute vip set to true, it will be able to access the content inside the PaidVideos collection, otherwise, the function will throw an error stating the user doesn’t have permissions to access these documents.

In this case, we handled the error from the API, we can also handle it from the front end to get a 403 status, indicating further payment is required.

Example 2: Monthly subscription

This scenario is very similar to the previous one, except your subscription expires after some time.

Create a new role with the same permissions as premiumUser, in this case, we will name it subscribedUser. Head to the Membership tab, add the Users collection and add this function to the predicate function:

Lambda(
  "ref",
  Let(
    {
      subExpiration: Select(
        ["data", "expiration"],
        Get(Var("ref")),
        TimeSubtract(Now(),1,"day")
      ),
      remainingTime: TimeDiff(Var("subExpiration"), Now(), "seconds")
    },
    GTE(Var("remainingTime"),0)
  )
)

This function seems a little more complex, but don’t panic. We use the method Let to create 2 variables: subExpiration which Get(s) the User info, Select(s) the path data/expiration which will be a timestamp with the expiration date of the subscription (the third argument means if there’s no data at that value, return the current time but yesterday); as well as remainingTime, which subtracts (using TimeDiff) the current time to the time stored on subExpiration and returns the value in seconds. Now, GTE returns true if the variable remainingTime is greater or equal to 0, which means the user still has time on its subscription.

As you can see, this status can change if the user’s subscription expires during the day. When the User’s expiration date has passed, it will no longer have the attributes to be a subscribedUser. Thus, when the user requests the PaidVideos, it will get a “permission denied” response.

Let’s update any non-vip user to have an expiration date for tomorrow.

When updating a file on the dashboard, if you use the method TimeAdd (or any other method), Fauna will update the field to the result of such method instead of a fixed value.

Let’s login with our updated user and head to the premium tab of our Next.js project. You should see the content we defined as PaidVideos.

If you try with a non-vip, non-subscribed user, you should see a message stating you are not premium

Example 3: Admins only

Let’s suppose your website has a section for admins, managers or any other role which is only granted to some handpicked users.

Create a new collection and name it UpperRoles. Create a new index called roles_by_user_id by using the next command on the Fauna’s shell:

CreateIndex(
  {
    name: "roles_by_user_id",
    unique: true,
    serialized: true,
    source: Collection("UpperRoles"),
    terms: [
      {
        field: ["data", "userId"]
      }
    ],
    values: [
      {
        field: ["data", "roles"]
      }
    ]
  }
)

We mark unique as true to have a simple user in the collection with all the roles assigned to it.

Create a new role with the same permissions we had on premiumUser and subscribedUser, now, let’s head again to the membership tab, select the Users collection and add this as predicate function:

Lambda(
  "ref", 
  Let(
    {
      rolesPage:Paginate(Match(Index('roles_by_user_id'),Var("ref"))),
      roles:Select(["data"], Var("rolesPage"),[]),
    },
    IsNonEmpty(Intersection(["admin"],Var("roles")))
  )
)

We bring the results of the index we just created, it’s expected to bring a single result as it has the unique flag marked as true, on roles we bring the first result of the page and set the default as an empty array, we expect roles to be an array of all the roles a user has available. Finally, we get the Intersection of our roles array and an array containing the role “admin”. If it’s a non-empty array, the user will have this role’s privileges.

Now, let’s grant a user these admin privileges:

Copy the ref of any non-premium, non-subscribed user.

Create a new document on the UpperRoles collection with the following data:

Create(
  Collection("UpperRoles"),
  {data:{
    userId:Ref(Collection("Users"), "277425124024517138"), //The reference you just copied
    Roles:["admin","accountant","manager"] //additional roles as reference
  }}
)

As you can see, this user will have some roles, including “admin”, which is the value we will look for.

We’ve explored some scenarios to define the role of a user based on its attributes. Next, we are going to determine if a user has access to read/update/create/delete a document.

In chapter two, we set the access to posts in a way that allowed any basicUser to change any document in the collection Posts, to create and delete any document in the collection Followers as well as many other privileges that give way too much freedom and may cause undesired behaviour.

Let’s head to the Security section, click on manage roles, find the basicUser and click the cogwheel on the right side. Let’s click the Users collection to expand it. Look at the </> symbols below each action. When clicked, it allows us to create a predicate function or script to grant privileges.

When you click any of them, Fauna provides a simple template script to hint you into a useful function.

If you don’t want to use a script but you already clicked on the button, just find the clear option on the lower right part of the script area.

Let’s expand the Posts collection and see what we can do regarding write permissions.

When writing a document, Fauna’s ABAC calls this function with 3 arguments: the previous document (olData), the document’s future state (newData) and the document’s id (usually ref). Let’s check what is new here, the Equals method compares the arguments inside it and returns true if all of them are equal. The And method returns true if all the arguments are true, just like a regular AND logical gate.

In this example, we check if the document belongs to the user trying to modify it by using Equals:

Equals(Identity(), Select(["data", "owner"], Var("oldData")))

As you can see, it checks the path data/owner in the previous document and compares it with the Identity of the logged in user, which means you can only edit the posts you own. Also, we want the data to remain of the same user, so we check the field in data/owner in both, previous and new, documents to check if the owner will remain the same.

As both Equals methods are inside an And method, both have to return true to confirm the document write. You can also add another field, for example, the creation date of the previous document must be equal to the new date.

Equals(
  Select(["data", "date"], Var("oldData")),
  Select(["data", "date"], Var("newData"))
)

If the function returns true, the document will be updated as if the user had full permissions to do it, otherwise, it will throw an error and the document will remain unchanged.

Note: newData contains the whole document’s new state. If you modify a single field, newData will contain the whole document with the change on the modified field. There’s no need to send the fields you want ABAC to compare.

This is very useful to keep some fields of the database static, for example, the owner of a post. For now, uncomment the functional part of the script so we use it, then, click on the </> symbol under the Create action.

You can see the function here is very similar to the other one, except we only have one argument on the Lambda function which is values, these are the values that are about to be written on the database. The path data/owner has to be equal to the Identity to allow a user to create a post, otherwise, no document is created at all. Let’s uncomment this function as well and check on the Delete action.

This function gets the document’s id as argument and names it ref, It performs a Get method on the argument and checks the path data/owner to compare it with the Identity. If it’s the owner who’s deleting the post, the action is performed. Let’s uncomment this functional part as well and scroll down to save our changes.

Let’s try to create a post under the regular method. Navigate to chrome, create a post and you should see nothing has changed since we did it in the previous chapter.

Now, let’s break our application:
Copy the ref of any user different from the one you’re logged in, just like we did for the upper roles. Go to the functions section, select the createPost function and change the field on the path data/owner to look like this:

Query(
  Lambda(
    "description",
    Create(Collection("Posts"), {
      data: {
        description: Var("description"),
        date: Now(),
        owner: Ref(Collection("Users"), "277945843461390867"), // The ref you just copied
        likes: 0,
        comments: 0
      }
    })
  )
)

As the reference in the field owner is different from our logged in user, our permission will be denied. Save the broken function and try creating a post again.

This error message is quite large, but the punchline is in the responseRaw field (also, you can catch the field responseContent.errors), you will find the reason for the error is “permission denied” and the description states you don’t have the permissions for the action. This is the error you will find every time you try to perform an action you’re not allowed to. This is not the expected behaviour of your app, but a failsafe in case someone tries to break havoc in your app. Now you can repair the broken function, we have tested what we wanted.

Debugging ABAC

Well, we’ve set up some permissions and we want to know if the functions we defined are actually doing what we need them. We will use the Fauna Shell to compare our results with our expectations.

For example, let’s bring our predicate function for premiumUser:

Lambda(
  "ref",
  Select(
    ["data", "vip"],
    Get(Var("ref"))
  )
)

The variable ref will be the user’s ref. So, let’s head to the Fauna’s shell, use the Let method to bring a variable with the name ref.

Let(
  {
    ref:Ref(Collection("Users"),"277945843461390867")
  },
  Select(
    ["data", "vip"],
    Get(Var("ref"))
  )
)

We changed the Lambda method for a Let, and created the variable ref with the reference of a user. In this case, this is the user’s document:

{
  "ref": Ref(Collection("Users"), "277945843461390867"),
  "ts": 1603515727810000,
  "data": {
    "email": "testmail5@mail.com",
    "posts": 0,
    "activeSince": Time("2020-09-28T21:31:02.124870Z"),
    "vip": true
  }
}

When you execute on the shell, you’ll realize that getting the document and selecting the value in the path data/vip will return true.

When you try with another user, for example this:

{
  "ref": Ref(Collection("Users"), "280324497574199812"),
  "ts": 1603600132565000,
  "data": {
    "email": "testmail4@mail.com",
    "posts": 0,
    "activeSince": Time("2020-10-25T03:38:43.365515Z"),
    "expiration": Time("2020-10-26T04:28:52.453007Z"),
    "vip":false
  }
}

The function will return false. Meaning the user will not be included in the premiumUser role.

The only way an ABAC function grants privileges or includes a document within a role is by having the predicate function return true, having a function that returns an error will deny the privileges or the role. This means that you can have users that don’t contain the field vip and this won’t break the functionality of ABAC.

Now, let’s try with the predicate functions to update a post:

Lambda(
  ["oldData", "newData"],
  And(
    Equals(Identity(), Select(["data", "owner"], Var("oldData"))),
    Equals(
      Select(["data", "owner"], Var("oldData")),
      Select(["data", "owner"], Var("newData"))
    )
  )
)

This one requires the definition of 3 variables: oldData, newData and the user’s id which will replace the Identity method, this is because Fauna's Shell has no identity nor document associated.

Copy and paste the whole existing document for the oldData, do the same for the newData, but change the owner to some other user id (or just something random, it doesn’t matter). When executed on the Fauna shell, you’ll see this returns false because the new value for the owner is not Equal to the previous one.

Let(
  {
    oldData:{
      "ref": Ref(Collection("Posts"), "280597810560107014"),
      "ts": 1603857775247000,
      "data": {
        "description": "I like turtles",
        "date": Time("2020-10-28T04:02:55.038172Z"),
        "owner": Ref(Collection("Users"), "277425124024517138"),
        "likes": 0,
        "comments": 0
      }
    }, 
    newData:{
      "ref": Ref(Collection("Posts"), "280597810560107014"),
      "ts": 1603857775247000,
      "data": {
        "description": "I like turtles",
        "date": Time("2020-10-28T04:02:55.038172Z"),
        "owner": Ref(Collection("Users"), "280324497574199812"),
        "likes": 0,
        "comments": 0
      }
    },
    userId:Ref(Collection("Users"), "277425124024517138")
  },
  And(
    Equals(Var("userId"), Select(["data", "owner"], Var("oldData"))),
    Equals(
      Select(["data", "owner"], Var("oldData")),
      Select(["data", "owner"], Var("newData"))
    )
  )
)

The reason we copied the whole document instead of just the path we needed is to show you how ABAC will see the information when you are trying to perform the write action on a document. Something similar will happen when you try to read/create/delete a document in this collection due to the predicate functions.

This is basically it, copy the functional part of the Lambda within a Let and set the expected (and some unexpected) values as the Let definitions, with this, you will be able to predict the behaviour of any predicate function you declare.

Password reset for your users

Let’s think about this common scenario: One of your users doesn’t remember the password used for signup. How do you recover it? Fauna won’t show you the password or allow you to see the user’s login keys. Even if you are an admin. However, Fauna allows admins to create Login tokens for any user, no passwords required. This way, you may try to send the user’s token via email or any other confirmation method defined prior to the password loss.

We are going to create a function on Fauna to perform this action. We are going to receive the user’s email, look for it on our database to get the user’s id, create the token and return it to the API, we are expecting this API won’t return the token to the user directly, instead, the API will send an email to the user.

Query(
  Lambda(
    "email",
    Let(
      {
        userId: Select(
          ["data", 0],
          Paginate(
              Match(Index("users_by_email"), Var("email")),
          )
        ),
        returnData: Create(Tokens(), {
          instance: Var("userId"),
          data: { message: "you can add some information here" },
          ttl: TimeAdd(Now(), 5, "minutes") // add time to live
        })
      },
      Var("returnData")
    )
  )
)

We use this function to create a new document in the collection Tokens(), this is the collection where Fauna stores the Login tokens for all Users, this information is partially visible, we will not be able to see the current key nor the password used, but we can see the instance, which should be the user’s id, and the data field, which we used to store a message. We also added a ttl or time to live, this works as an expiration date, so the user has a limited time to reset the password with this token.

Last function on Fauna is resetPassword, this function will update the user’s password to the one provided on the parameters.

Query(
  Lambda(
    "password",
    Do(
      Update(Identity(), { credentials: { password: Var("password") } }),
      Logout(false)
    )
  )
)

As this will update the own user, we need to add privileges to the Users collection to update itself. Add this as the predicate function under the Write action.

Lambda(
  ["oldData"],
  Equals(Identity(), Select("ref", Var("oldData")))
)

Also, add the resetPassword function to the privileges and check the privilege to Call the function.

In our repository, we added a tab called Recover, sign up with a reachable email address and try to reset your password.

You will get an email similar to this:

And when you click on the link, you’ll be here

Add a new password and you’ll be able to login with it.

Are you test launching now? Here some advice:

When setting up your environment variables on an actual server, it’s recommended you don’t use a key with administrator or server privileges. Using a key with minimum privileges may keep the functionality intact and your application will be safer.

In Our case, we can have permissions to create and read on the Users collection, add read privileges to the index users_by_email, the function signupUsers and recoverPassword will have call permissions.

With this, you will have a public role with limited functionality, create a key for this role, you don’t need to add a collection or a predicate function, just add the key from the security menu.

And that’s it. Add some styles to make it look fancy, add some features to make it more interesting. It’s up to you.

Thank you so much for following this blog series, I hope it's useful to your projects or your new interests, perhaps.

Chapter 2: Let's get into Fauna: a guide to understand Fauna while creating a social media database

Sergio Andrés Jaime Sierra — Wed, 21 Oct 2020 02:30:47 +0000

In the first chapter of this series, we had the chance to walk through the Fauna and Next.js tutorials and started a simple website with a basic login mechanic. In this chapter, we are going to create the functions within Fauna to sign up new users, create following relationships between users, create posts, like them and comment them, we have our first approach to Fauna’s permissions system by granting users permissions to execute the functions mentioned.

Create new users

Last time, we did register our user using the Fauna dashboard. This is an impractical approach because we want our site to be autonomous and that transaction should be done from the user interface in our website. This is what the API called signup does.

What does this API do?

This API imports the query commands from fauna

1 import { query as q } from 'faunadb'

And then, uses the Create command to create a new document on the Users collection,

16  user = await serverClient.query(
17    q.Create(q.Collection('User'), { //errata: our collection is called Users 
18      credentials: { password },
19      data: { email },
20    })
21  )

As you can see, it’s very similar to the way we created our user with the Fauna’s dashboard. The main difference here is that we need to prepend every command with q. so it’s recognized as a Fauna’s method.

After creating the user, the API logs the user and returns the login token

31  const loginRes = await serverClient.query(
32    q.Login(user.ref, {
33    password,
34  })
35  )

The secret returned is very similar to the Server Key we created on the first chapter. We need to save it on a cookie so the user keeps it when navigating through the website.

41    const cookieSerialized = serializeFaunaCookie(loginRes.secret)
42
43    res.setHeader('Set-Cookie', cookieSerialized)

As you can see, we needed to call serverClient twice, the first time to create the user and the second time to log into the account. Even if two queries doesn’t look like a lot of calls, the user creation API is a good point to start using User Defined Functions (UDF), so, why don’t we try to make it a single database query to reduce latency on these requests? After this, we can understand how to do the same on larger functions that require an important amount of reads/writes.

Start using User Defined Functions (UDF) to improve your site's performance

Fauna allows you to create your own functions using the FQL methods described here, don’t panic, you don’t have to learn them all just yet. Most of the time we will be using Match, Paginate, Select and Get methods to get all the documents we require. Let’s now navigate to Fauna and create some simple functions.

Let’s open our database from the Fauna’s dashboard, open the functions menu and click on New Function. Usually Fauna gives you a short example function’s body by default, it goes:

Query(
  Lambda(
    "x", Add(Var("x"), Var("x"))
  )
)

Let’s explain it by parts:

Query: it’s only parameter is a lambda function and its purpose is to prevent the lambda function for immediate execution. It encases the function definition.
Lambda: this method has two parameters, the first one is the set of arguments the function can get (in this case, x), and the second one is the lambda function, which means the commands we will execute. All argument names should be strings, also, if you need to use more than one parameter, you should put all names in an array (e.g [“x”,”y”]).
Add: In the example code provided by Fauna, they use Add as the only method used, this returns the arithmetic sum of all the arguments. However, we will change this part to login the user.
Var: Everytime we make a reference to an existing variable, we need to call the method Var and put as argument the name of the variable as a string.

Ok, the functional part is Lambda, so let’s transform the default function’s body and make it a function for creating users.

Query(
  Lambda(
    ["email","password"],
    Let(
      {
        user:Create( //create the user
          Collection("Users"),
          { 
            credentials: { password: Var("password") },
            data: {
              email: Var("email"),
              posts: 0,
              activeSince: Now()
            }
        }),
        userRef: Select(
          "ref",
          Var("user")
        ),
      },
      Login(Var("userRef"), {
        password: Var("password"),
        data: {
          message: "first Login"
        }
      })
    )
  )
)

This time, I changed the parameters in the Lambda function to show you how to put more than one variable. In this case, email is the user’s email and password is the user’s password.
The method Let allows you to create an object with temporal variables (represented as the object’s fields) and use them in the second argument by calling the method Var. We create a field named user and define it as the response for creating a new user on the Users collection with the data provided and some additional fields (for reference). The response of Create is the created document.

We also create a field called userRef in which we Select the field ref of our newly created user (this is equivalent to using user.ref in javascript). After defining our binding variables, we set the second parameter of Let to Login the user, this means, the Let method will return the result of Login.
When you login a user, you can provide additional data, we did put a field called message and put the string first login. You can be more creative and include relevant information for metrics like user’s IP, language, web browser, etc.

Let's name our function as signupUser and save it.

Next step: call this function from the signup API on our local repository.
If you don't have this repository yet, you can create it with the _create-next-app. Just run this from your command shell

npx create-next-app --example with-cookie-auth-fauna with-cookie-auth-fauna-app
or
yarn create next-app --example with-cookie-auth-fauna with-cookie-auth-fauna-app

Replace the method in the first serverClientquery to

q.Call(q.Function('signupUser'), [ password , email ])

This function will return the result from Login the user, thus, the second query is unnecessary and you can delete it.

When we test it, we should have the same behaviour we had before adding the UDF.

What did we achieve with this? On the API, we reduced the queries to Fauna from 2 to 1, reducing some lines of code. On the database, we reduced the data sent and received by performing both processes on the same query, we didn’t need to receive any information to perform the Login as we used the Let method.
If we have additional processes like adding tasks, roles, historic data, etc. we will have even better performance when we use UDFs.

In this case it doesn’t seem as much, but when we start expanding our database, we will have more efficiency by having UDFs vs performing many database queries.

You can make these functions available in your repository by adding them to a setup file. This way, when you are setting up a similar database for another server, you can recreate the same structure with just a single command. If you already have some experience with Next.js, you can adapt this example from Fauna’s developer team. Otherwise, wait until Chapter 3 when we will summarize all our progress in a setup script for Javascript that we will be able to track on your repository of choice.

Use UDF to follow users and post contents with less connection requests

Setting-up: Following relationships

We have the methods for creating new users, but there’s not a lot we can do with that. It’s time to add following relationships between our users. In this series, we will use a follower/followee relationship in which a user can follow another, this is not necessarily reciprocal.

Use the Fauna's dasboard to create a new collection and name it Followers, leave the other fields with their default values. Create two new indexes for your new collection, name them followers_by_followee and followees_by_follower. We will make the first index return all the followers of an user and the later index will return the people a user is following (followees). Let’s also make a third index called is_followee_of_user, with this, we can find if a user is already following another one and make unique the document related to the following condition.

Create Followers collection:

Also, you can do it from the Fauna’s shell using the method CreateCollection:
CreateCollection({name:”Followers”})
Create Index followers_by_followee:

Create it from the Fauna’s shell using CreateIndex:

CreateIndex({
  name: "followers_by_followee",
  unique: false,
  serialized: true,
  source: Collection("Followers"),
  terms: [
    {
      field: ["data", "followee"]
    }
  ],
  values: [
    {
      field: ["data", "follower"]
    }
  ]
})

Create Index followees_by_follower:

And with Fauna Shell:

CreateIndex({
  name: "followees_by_follower",
  unique: false,
  serialized: true,
  source: Collection("Followers"),
  terms: [
    {
      field: ["data", "follower"]
    }
  ],
  values: [
    {
      field: ["data", "followee"]
    }
  ]
})

Create the index is_followee_of_user:

With this, we prepared our database to handle follower/followee relationships between all users, now, let’s prepare to post content.

Setting-up: User’s posts

Create a new collection and name it Posts. At this point, I think you’ve already got the hang of it.
Create an index for this collection and name it posts_by_owner. This index will have the field owner as term and the value field will be empty.

Now, our database can contain something more than users. Let’s create some functions to follow users and to create posts.

Follow users

CreateFunction({
  name: ‘followUsers’
  role: null,
  body: Query(
    Lambda(
      "followee",
      If(
        IsEmpty(
          Match(Index("is_followee_of_user"), [Identity(), Var("followee")])
        ),
        Do(
          Create(Collection("Followers"), {
            data: { follower: Identity(), followee: Var("followee") }
          }),
          { isFollowing: true }
        ),
        Do(
          Delete(
            Select(
              ["data", 0],
              Paginate(
                Match(Index("is_followee_of_user"), [
                  Identity(),
                  Var("followee")
                ])
              )
            )
          ),
          { isFollowing: false }
        )
      )
    )
  )
})

This function toggles the follow/unfollow state of the users. If you already follow a user, you’ll stop following it, if you are not a follower, you’ll become one. Also, this function returns the new following status as true or false.

Create Post

CreateFunction({
  name: "createPost",
  role: null,
  body: Query(
    Lambda(
      "description",
      Create(Collection("Posts"), {
        data: {
          description: Var("description"),
          date: Now(),
          owner: Identity(),
          likes: 0,
          comments: 0
        }
      })
    )
  )
})

With this function, you can create a new post and put initial values like the date it was posted as well as set the amount of likes and comments to 0.

List Users

CreateFunction({
  name: "listUsers",
  role: null,
  body: Query(
    Lambda(
      "cursor",
      Map(
        Paginate(Reverse(Documents(Collection("Users"))), {
          after: Var("cursor")
        }),
        Lambda("ref", {
          userId: Select("id", Var("ref")),
          isFollowee: IsNonEmpty(
            Match(Index("is_followee_of_user"), [Identity(), Var("ref")])
          ),
        isSelf: Equals(Identity(), Var("ref"))
        })
      )
    )
  )
})

This function brings all the users, due to the nature of Paginate, every function call will return a page of 64 documents by default, in case we need the next page of 64 users, we can send a cursor variable containing the ref of the last user from the last result. Also, we can change the size of every page as we need. The response will contain a field called data which is an array of objects containing the fields userId (a string with the reference of the user), isFollowee (a boolean stating if you are following this user), and isSelf (a boolean indicating whether this user is you).

We’ve got several functions and indexes, but our users have permissions to none of them, all they can do is get their own user id. Let’s use the Fauna dashboard and the hints they provide to help us set the permissions for everyone.

First, let’s get to the manage roles section:

Click on new custom role and name it basicUser, then start adding the collections and functions, add everything except the index called users_by_email and the function called signupUser.

Fauna’s ABAC (Atribute-Based Access Control) will grant the documents of a collection all the permits that you grant. An authenticated document (in this case user) can have one or more roles, if any role grants permission to perform a certain action, the action will be performed when required.

After you finish adding your collections and indexes, you should see this:

Each row represents a collection, index or function. Each column stands for an action.
+Over the Collections your actions are Read / Write(update) / Create / Delete / Read History / Write on History / Unrestricted (do all)
+Over the indexes, you can Read / Unrestricted access (read all index's records, even for documents you can’t directly access)
+You can Call functions

Now, let’s grant the permissions for these items, click on the red X to turn it into a green checkmark on the next items:
+Read permissions for collections Users, Followers, Posts.
+Create permissions on Followers and Posts (we will change that later).
+Delete permissions on Followers.
+Read permissions on all indexes.
+Call permissions on all functions.

Finally, let’s click on the Membership tab on the upper side of the window to define who will have the permissions we’ve just set.

Select the Users collection as the users will be the ones with these permissions, now you can click on the new Row with the name Users to set a predicate function. In this case, all users will have permissions, so let’s just make the function return true all the time.

It’s done. Click save and we are ready to test our new functions using Next.js

For this, let’s clone this repository
https://github.com/Sertge/fauna-example

In this repository, we updated the example from Fauna in this address
https://github.com/vercel/next.js/tree/canary/examples/with-cookie-auth-fauna

To include the APIs that will call the functions we’ve just created. When you’re done cloning, add your Fauna’s server key to the environment variable, input the command npm install or yarn, and then npm run dev or yarn dev to run your local server.

When you clone this repository and run it, you should see some additional options in your header

From Signup, create some new users and click on the Users option from the header.
Here, you can see a list of all users on the database and will have the option to follow/unfollow them, also, you can follow yourself.

And finally, you can add some posts and see them on the database from the tab called New post

Great, now we can create some follower/followee relationships, see which users we are following as well as the ones we aren’t and we can create some posts, all of this by using Fauna’s UDF. In the next section, we will harvest even more power from Fauna.

Interact with your followers, have them like and comment your posts

On a social network, we want to have our wall/feed populated with the users we follow and keep up to date with them. Also, we want to let them know we admire their work by liking or commenting on their posts. It’s time to add a collection called Likes and another one called Comments as well as create the functions to post comments, toggle the like/unlike status on a post, and finally, grant permissions to our users so they can do all of this.

+Use the dashboard to create a new collection and name it Likes or use CreateCollection({name:’Likes’}) on the Shell.
+Create a new collection and name it Comments.
+Create a new Index for the collection Likes and name it likes_by_post_id, use the field postId as search term.

You can also run the command on the shell

CreateIndex({
  name: "likes_by_post_id",
  unique: false,
  serialized: true,
  source: Collection("Likes"),
  terms: [
    {
      field: ["data", "postId"]
    }
  ]
})

+Create another index for the Comments collection and name it comments_by_post_id, it's the same as the previous step, just change the collection and the name.
+Create an index for the Likes collection called is_liked_by_user and use the owner and the postId as terms. Make it unique by marking the Unique field, so a user can only like a post once.

Let’s also add a function to post comments and name it postComment

CreateFunction({
  "name": "postComment",
  "role": null,
  "body": Query(
    Lambda(
      ["postId", "description"],
      Create(Collection("Comments"), {
        data: {
          owner: Identity(),
          date: Now(),
          likes: 0,
          description: Var("description"),
          postId: Var("postId")
        }
      })
    )
  )
})

A function to toggle the like/unlike status on the post

CreateFunction({
  name: "toggleLike",
  role: null,
  body: Query(
    Lambda(
      "postId",
      If(
        IsEmpty(Match(Index("is_liked_by_user"), [Identity(), Var("postId")])),
        Do(
          Create(Collection("Likes"), {
            data: { owner: Identity(), postId: Var("postId"), date: Now() }
          }),
          { isFollowing: true }
        ),
        Do(
          Delete(
            Select(
              ["data", 0],
              Paginate(
                Match(Index("is_liked_by_user"), [Identity(), Var("postId")])
              )
            )
          ),
          { isFollowing: false }
        )
      )
    )
  )
})

A function to get the posts of all the users you follow (feed):

CreateFunction({
  name: "getFeed",
  role: null,
  body: Query(
    Lambda(
      "cursor",
      Map(
        Paginate(
          Reverse(
            Join(
              Match(Index("followees_by_follower"), Identity()),
              Index("posts_by_owner")
            )
          )
        ),
        Lambda(
          "post",
          Merge(Select("data", Get(Var("post"))), {
            isLiked: IsNonEmpty(
              Match(Index("is_liked_by_user"), [Identity(), Var("post")])
            ),
            postId: Var("post"),
            userIsOwner: Equals(
              Identity(),
              Select(["data", "owner"], Get(Var("post")))
            )
          })
        )
      )
    )
  )
})

And finally, a function to get the comments from a post:

CreateFunction({
  name: "getComments",
  role: null,
  body: Query(
    Lambda(
      "postId",
      Map(
        Paginate(Match(Index("comments_by_post_id"), Var("postId"))),
        Lambda(
          "comment",
          Merge(Select("data", Var("comment")), {
            isLiked: IsNonEmpty(
              Match(Index("is_liked_by_user"), [Identity(), Var("comment")])
            ),
            commentId: Var("comment"),
            userIsOwner: Equals(
              Identity(),
              Select(["data", "owner"], Get(Var("comment")))
            )
          })
        )
      )
    )
  )
})

We’re almost there, it’s time to add the permissions so our regular users are able to use these collections, indexes and functions. Add the following permissions:

+Likes: Read, Create, Delete.
+Comments: Read, Create
+All new indexes: Read
+All new functions: Call

Now, you can head to the feed and get all the posts your followees have posted:

Click on any post to open it and see all the comments:

Now, we have some of the functions a small social network requires to work. In the next chapter, we will display more information, add the stories, chats, and use Fauna's ABAC to limit the user’s actions, giving us some control within our application. Also, we will learn how to create ABAC predicate functions and debug them.

Let's get into Fauna: a guide to understand Fauna while creating a social media database

Sergio Andrés Jaime Sierra — Tue, 15 Sep 2020 12:02:33 +0000

Chapter 1

Fauna is a great serverless database created to work as a data API, its functionality makes it great to work with serverless frameworks like next.js. In this series, we will use Fauna’s power to create a social network back-end structure. This time we won’t be using GraphQL, instead, we will use all the functionality provided by Fauna’s dashboard and shell.

Why Fauna?

Fauna’s storage model is a non-structured database, the flexibility of such a database allows the design, functionality, and business model to be flexible as well. Most changes in relationships will not represent changes in the rest of your structure, it feels like you were already thinking of that feature when you started.
Even with the non-structured database, it is easy to set up indexes that work like lookups without having to bring a large set of data, saving you lots of bandwidth and improving your site’s performance.
Serverless means you can expand for as many operations as you need, Fauna takes care of everything and prices are very competitive. Don’t just take my word on it and check on Fauna's official website, simulate your monthly costs based on your site’s needs and register here.

Fauna has the option to create your own User Defined Functions, these functions can be useful to improve your site’s performance even further, it handles some tasks locally, reduces API calls from your servers, helps you manage actions more consistently, it can even help you protect your database (which you’ll learn more about in next chapters)

Social network overlook

We want to exploit the most potential out of Fauna, in this series, we will do it by creating a social network. For this, we will have user authentication, password recovery, follow users, chats, publishing, liking, and commenting posts. We will retrieve this data via APIs while we integrate it with Next.js, a serverless react framework.
Let’s start by outlining our database. We want to know how our data will be related between different collections as well as how indexes will retrieve information from a collection based on the information from another collection, the diagram below will give us an approach that is easy to understand and will help us keep track of the app’s functionality and what we will need to build in order to make it work. Note the internal reference in the user’s collection, this is the user’s ID and will be constantly used throughout the app.

I know these connections might seem overwhelming at first, but when we start to create our database, they will become an obvious need for a social network and we will go over every one of them as we advance in the series.
As you can see, the Users are the center of a social network. Therefore, everything is connected to them at this point. The Users collection will have the user’s email, the username, a profile description or bio and a profile picture; Fauna stores passwords in a separate collection that can’t be accessed, even by admins, making it easier and safer when someone reads the documents in the User collection. Also, Fauna stores a reference for the user which we will use for all our relationships.
Tokens is an internal Fauna collection, Fauna doesn’t show too much from this collection, however, we can use it to save some information about the User’s login, such as the navigator used or the amount of active logins such user has. You can use this to limit the number of logins a user can have, or to restrict their use to certain regions.
Also, the UpperRoles collection is used to give specific hand-picked Users additional permits using ABAC. This way, we will use regular users and promote them to moderators, admins, etc.
All the other collections will be defined as we need them.
Note: If you want to follow through our examples, you need to install FaunaDB to use it on your preferred Command shell, and install node.js to setup a local server and get your APIs running.

Setting up with Next.js

This time, we will set up our project on Next.js. Fauna does not require a full-time connection between the Client and the Server, it works like an API: You open a connection, make a request, get a response, close the connection. Same with Next.js, your server can get requests all the time, but your connections will only last as long as the request.
If you want to learn how to use Next.js, follow this link (Next.js is a framework based on React, thus, you may need to know some React before diving into Next.js)

For this series, we will start by using the example from Fauna found in this page, we will cover the things you need to get your APIs running. Thus, you can read the tutorial or continue reading this chapter.
Use your explorer or command Shell (E.g. Windows Powershell, Gitbash) to navigate to the folder you want to download our example to.
You can use any of these commands to download the example from Next.js repository:

npx create-next-app --example with-cookie-auth-fauna with-cookie-auth-fauna-app
or
yarn create next-app --example with-cookie-auth-fauna with-cookie-auth-fauna-app

Navigate inside the newly created folder and launch the command npm install or yarn to download the required libraries.
If you are working on Windows 10, you should have a folder which looks like this:

To access the database, Fauna uses keys that are created from Fauna’s dashboard and are deleted from there as well, a master key is needed to create users and contact the database to log in an existing user. When a user logs in, they get a key that needs to be saved on a secure cookie, the file .env.local.example needs to contain the master key from Fauna. So, let us set up our database to use it with this fresh Next.js project

Setting up your database and your server keys

If you’ve already got into Fauna, read some documentation and completed the tutorial on the Database, you may already know how to create your database and your server key and can skip this part.

If you haven't signup for Fauna yet, you can do it on this link

On the dashboard, you can create a new database from the main view

Click on the button marked with “NEW DATABASE” and input the name of your new database. This time we won’t need demo data as we will be using our own in this series.

Great, now you have a new database, but you can’t access it yet from outside the Fauna’s dashboard. Let’s change that.
On the menu on your left, click Security and Create new key, assign it the server role and click save (you can add an optional name if you want, but it won’t be used anywhere, it’s merely cosmetic).
Note: This key will only be shown once, so you will need to add it to your .env.local.example file at once. If you lose it for some reason, you can always create a new one. Just make sure to revoke the older one.

When you add the secret to the .env.local.example file, change its name to .env, so Next.js can read it.

When you put your key on your environment variable, it should look like this:

That one is my key, yours should be different.
Create a collection called Users and an index called users_by_email, the index’s source should be the Users collection and the terms should be data.email, also, check the box Unique to prevent duplicate entries, this means the index will return the reference of the user that matches the email you request.

The index creation menu should look like this:

Let’s create a test user and see if it works, for this, we will use the Fauna’s dashboard shell, we will create a method for signup on our app later in this course.
The Create method creates a document in the collection you define in the first parameter with the data you define on the second parameter as an object. The object you provide can have the following fields:

data: This field contains an object with all the data you want to save on your document, you can have as many fields inside this object as you need. Also, the index we created earlier will look at the field email and will try to match the email you provide for a search, more on that later.
credentials (optional): This field contains an object with a password field which is a string with the user’s password, note that in a social network we only want users to log in, but in another scenario, perhaps a factory, we can separate collections for supervisors, engineers, operators, etc. Meaning any document in any collection can login if it has credentials set.
delegates(optional): This field contains an array of references that will have the same permissions as this document. We won’t use this field on the series.
ttl(optional): Time-To-Live, this is useful for stories, as they last only 24 hours, this field is a timestamp with the expiration date of the document.

Create(
    Collection('Users'),
    {
      credentials:{password:'123456'},
      data:{email:'testmail1@mail.com'}
    }
)

When you execute the command above, you should see something like this on the Fauna shell:

Also, you can confirm on the Collections section that your user has been created on the Users collection.
As we mentioned earlier, Fauna stores password on a different collection that is not accessible (even by admins) meaning the user’s password will be safer and the user’s document can be read by other users with no need to keep hiding the password field.
Let’s try to log in with our new user from our local project in Next.js. open a command shell on your project folder and use the command yarn dev or npm run dev, depending on the package manager you have installed. When the command shell prints “event – compiled successfully”, open your browser and navigate to “localhost:3000”

Click Login and try to login with your fresh user. If you followed this example, you should see something like this:

You will see a different number, but if you compare with the document’s ref on the Users collection, it will match.
When you want to shut down the local server you’ve set up, you can hit ctrl+c twice.
At this point, we have set up a simple site using Fauna and Next.js examples. In the next chapter we will create methods to update the user’s profile, change the password, recover a lost password via email, learn how to use ABAC to limit the collections a user can access, make use of Fauna’s User Defined Functions to improve your performance and reduce latency, and create indexes that will help you get your posts in reverse order (newer first).