Apollo on Janik von Rotz

Apollo GraphQl server and client sorting

Wed, 29 Jan 2020 14:05:23 +0100

GraphQl is not opinionated about sorting and pagination. It is up to you to implement the sorting for your query. I’ve seen various approaches doing that, but none seemed elegant. After compiling a few blog posts and tutorials I came up with the following solution.

We want to make a selected query sortable. Therefore we add an optional parameter to the query in the schema. The parameter is a custom input type. It consists of a field name and a sort order. The field property is a string and the order property is an enum. Order is either ascending or descending.

Here is my schema example:

enum Order {
  ASC
  DESC
}

input SortBy {
  field: String!
  order: Order!
}

type Group {
  id: String!
  name: String!
}

type Tenant {
  id: String!
  name: String!
  group: Group
}

type Query {
  tenants(sortBy: SortBy): [Tenant]
}

The query in action would look like this:

{
  tenants(sortBy: { field: "name", order: DESC }) {
    id
    name
  }
}

Implementing the resolver is up to you.

Here is an example of my MongoDB collection lookup.

// ...
const resolvers = {
  Query: {
    tenants: async (obj, args, context) => {
      const sortBy = {}
      if (args.sortBy) {
        sortBy[args.sortBy.field] = args.sortBy.order === 'ASC' ? 1 : -1
      }
      return (await (await collection('tenants')).find({}).sort(sortBy).toArray()).map(prepare)
    },
    // ...

Quite simple isn’t it? But, what if we wanna sort by a nested property. Let’s say tenant.group.name.

It simply is not possible to accomplish this in GraphQl. Subtypes are resolved in an isolated resolver.

// ...
const resolvers = {
  Query: {
      // ...
    },
    // ...
  },
  Tenant: {
    group: async (obj, args, context) => {
      return groupResolver.Query.group(obj, { id: obj.group }, context)
    }
  }
  // ...

Now instead of sorting on the server side you could to that on the client side.

The main difference is that you do not have access to the full data set. Assuming you only return a subset of the data from the Graphql api, you only sort a part of the full data on the client.

Here is a sort function that provides a similar functionality as we’ve seen above.

const compareValues = (key, order = 'ASC') => {
  const keys = key.split('.')

  return (a, b) => {
    let i = 0

    // Access nested property
    while (i < keys.length) {
      a = a[keys[i]]
      b = b[keys[i]]
      i++
    }

    const varA = (typeof a === 'string') ? a.toUpperCase() : a
    const varB = (typeof b === 'string') ? b.toUpperCase() : b

    let comparison = 0
    if (varA > varB) {
      comparison = 1
    } else if (varA < varB) {
      comparison = -1
    }
    return (
      (order === 'DESC') ? (comparison * -1) : comparison
    )
  }
}

This function can be passed to the array sort method.

const tenants = [
  {
    id: 1,
    name: 'A-Tenant',
    group: {
      id: 1,
      name: 'A-Group'
    }
  },
  {
    id: 2,
    name: 'B-Tenant',
    group: {
      id: 2,
      name: 'B-Group'
    }
  },
  {
    id: 3,
    name: 'C-Tenant',
    group: {
      id: 3,
      name: 'C-Group'
    }
  }
]

tenants.sort(compareValues('group.name', 'DESC'))

I would be really interested if you have another solution for the nested sorting problem.

Apollo Graphql integration testing in practice

Thu, 05 Dec 2019 10:16:19 +0100

The Apollo Graphql documention offers a pretty comprehensive guide on how to test your Graphql API. But sure its different once you implement tests for your non generic project. That is why I wrote this post. First I would like to introduce you to integration tests and how they are different from the other testing levels. And then I’ll give you a hands on experience for writing integration tests for Apollo Graphql with Ava.

Testing levels

As promised first we will have a look at the different testing levels. For this I created this beautiful visualization:

![](/images/Testing levels.png)

On the right you’ll see a distributed software system and wrapped in boxes you’ll see what type of test type focuses on which components of the software system.

Unit Tests

When considering the entire software system and functions that can be tested, unit tests are the smallest test methods. Unit tests check methods of classes and objects of the source code. They are used to ensure that the smallest possible testable functions behaves correctly. The overall function of the software system is neglected. The highest possible test coverage is desired here. The effort for implementation is low.

Integration Tests

Integration tests are used to check whether the application is running correctly on the server. Thus the server environment is also included in the test. The test coverage is lower compared to the unit tests. Integration tests show how interoperable the application is.

End to End Tests

An application connects to various services and databases. End to end tests are used to check communication with surrounding systems. The implementation effort for end-to-end tests is high. The test coverage is low. With end-to-end tests, statements can be made about the overall behavior of the software system.

UI Tests

UI tests are the most complex form of tests. They simulate the behavior of a user. With the help of automation tools, the same actions of a user are executed in the client application. The implementation of UI tests is extremely time-consuming and is known for continuous need of repair. Every change to the software system affects the UI tests.

Integration tests with Apollo Graphql

To showcase how integration tests are implemented for an Apollo Graphql API we need a schema, mutation, queries and resolvers. Here is an Graphql type example:

schema.js

...
type Tenant {
  id: String!
  name: String!
  assigned_users: [User]
  assigned_category: Category

  created: Date
  created_by: User!
  updated: Date
  updated_by: User!
}
...

The API provides these queries and mutations.

...
type Query {
  tenants: [Tenant] @hasRole(roles: [ADMIN])
  tenant(id: String): Tenant @hasRole(roles: [ADMIN])
}
...
type Mutation {
  createTenant(name: String!): Tenant @hasRole(roles: [ADMIN])
  updateTenant(
    id: String!
    name: String
    assigned_users: [String]
  ): Response @hasRole(roles: [ADMIN])
  deleteTenant(id: String!): Response @hasRole(roles: [ADMIN])
  assignTenant(
    id: String!,
    user: String!
  ): Response @hasRole(roles: [ADMIN])
}
...

As you can see there are other types and directives in the example schema. For this tutorial we focus on the tenant type, ignore the others.

Running integration tests means I want know wether the resolvers of the queries and mutations work correctly.

Therefore we have to start the server, bootstrap the database, run the tests and clean everysthing.

In your codebase test code is separated from the functional code. In Ava every test case has its own standalone file for running the tests.

To test resolvers I have created this file:

resolvers.test.js

I am using the official Apollo server testing package to setup the test server.

Imports:

const { createTestClient } = require('apollo-server-testing')
const { ApolloServer, gql } = require('apollo-server-micro')
const typeDefs = require('./schema')
const directives = require('./directives')
const { merge } = require('lodash')
const tenantResolvers = require('./resolvers-tenant')
const test = require('ava')
const { ObjectId } = require('mongodb')
...

Ava is my test runner. The ObjectId is used to validate if the resolvers actually returns a correct mongo object id.

Environment config:

...
// Load environment configuration
require('dotenv').config({ path: `${__dirname}/.env.${process.env.NODE_ENV}` })
...

Tests run in a separate environment. Env variables are loaded from the .env.test file.

Context and server initialization:

...
// Initialize Apollo server
var context = { user: { id: 1, email: 'admin@labtrail.app', role: 'ADMIN', tenant: 1 } }
const server = new ApolloServer({
  typeDefs,
  resolvers: merge(
    tenantResolvers
  ),
  context: () => (context),
  schemaDirectives: directives
})
const { query, mutate } = createTestClient(server)
...

Here the Apollo Server is initialized with a context mock. The context mock ensure that the tests have the privileges required to run the queries and mutations.

First test:

...
// Share context between tests
var result = {}

test.serial('Create tenant Acme', async t => {
  const CREATE_TENANT = gql`
  mutation createTenant( $name: String!) {
    createTenant(name: $name) {
      id
    }
  }
  `
  result = merge(result, await mutate({
    mutation: CREATE_TENANT,
    variables: { name: 'Acme' }
  }))
  t.assert(ObjectId.isValid(result.data.createTenant.id))
})
...

In our test scenario tests depend on each other. They must be executed serially. Every test has a description, runs a query or mutation and asserts the result at the end of the async test function.

More tests:

...
test.serial('Get tenant Acme by Id', async t => {
  const GET_TENANT = gql`
  query tenant($id: String) {
    tenant(id: $id) {
      id
      name
    }
  }
  `
  result = merge(result, await query({
    query: GET_TENANT,
    variables: { id: result.data.createTenant.id }
  }))
  t.is(result.data.tenant.name, 'Acme')
})

test.serial('Mutate tenant Acme to AcmeX', async t => {
  const UPDATE_TENANT = gql`
  mutation updateTenant($id: String!, $name: String) {
    updateTenant(id: $id, name: $name) {
      success
    }
  }
  `
  result = merge(result, await mutate({
    mutation: UPDATE_TENANT,
    variables: { id: result.data.createTenant.id, name: 'AcmeX' }
  }))
  t.assert(result.data.updateTenant.success)
})

test.serial('Delete tenant Acme by Id', async t => {
  const DELETE_TENANT = gql`
  mutation deleteTenant( $id: String!) {
    deleteTenant(id: $id) {
      success
    }
  }
  `
  result = merge(result, await mutate({
    mutation: DELETE_TENANT,
    variables: { id: result.data.createTenant.id }
  }))
  t.assert(result.data.deleteTenant.success)
})

The tests shown here match queries and mutations of the schema. For every type and set of queries and mutations there is separate test file. Ava runs them concurrently, but ensures that the single tests cases are executed serially.

Running the tests is simple. I created a script task to run Ava with yarn.

package.json

  ...
  "scripts": {
    ...
    "test": "ava"
  },
  ...

And running yarn test will do the job.

For more details on Ava checkout the documentation.

Hope this tutorial gave you an idea about testing and how to apply it to Apollo Graphql 😊

Build an Apollo Graphql user authentication for your React app - part 3

Thu, 26 Sep 2019 10:31:27 +0200

This is the final post of my GraphQL Auth series. Before reading this post checkout post 1 and post 2.

As mentioned in my last post we need to polish our authentication solution. First we wanna ensure that the JWT token expires. Second, I think the isAuthenticated directive is insufficient for proper permission management on our types, queries and mutations. We need a role based solution. While the first point is simple to implement, the second is more complex and definitely requires walking through the previous posts.

Files

We will update the following files of our GraphQL server:

schema.js: Type, query, mutation and directive definitions.
context.js: Extracts claims from JWT token.
directives.js: Directive implementations.
resolvers.js: Resolve methods for schema.

Schema

Update the GraphQL schema with a role direcive.

schema.js

const { gql } = require('apollo-server-micro')

// GraphQL schema
const typeDefs = gql`
...

directive @hasRole(roles: [Role!]) on FIELD_DEFINITION

enum Role {
  ADMIN
  USER
}

...

type User {
  id: String!
  email: String!
  password: String!
  firstname: String!
  lastname: String!
  name: String
  role: Role!

  created: Date
  created_by: String!
  updated: Date
  updated_by: String!
}

type Query {
  currentUser: User @isAuthenticated
  users: [User] @hasRole(roles: [ADMIN])
}

type Mutation {
  createUser(email: String!, password: String!, firstname: String!, lastname: String!, role: Role): User @hasRole(roles: [ADMIN])
  updateUser(id: String!, email: String, password: String, firstname: String, lastname: String, role: Role): Response @hasRole(roles: [ADMIN])
  deleteUser(id: String!): Response @hasRole(roles: [ADMIN])
}
`
module.exports = typeDefs

In addition to our isAuthenticated there is now a hasRole directive. This directive accepts a list of roles and only grants user equipped with such role access or execution rights.

The User type has a new property role. It is now possible to assign a role from the Role enum to the user.

Context

In the GraphQL context the JWT token is verified and the user details are retrieved from the store.

context.js

...

  // Verify token if available
  if (token) {
    try {
      token = jwt.verify(token, process.env.JWT_SECRET)

      // Get user from database
      user = await (await usersCollection()).findOne({ email: token.email })

    } catch (error) {
      throw new AuthenticationError(
        'Authentication token is invalid, please log in.'
      )
    }
  }

  return {
    email: token ? token.email : null,
    name: token ? token.name : null,
    role: user ? user.role : null
  }
}

module.exports = context

The role attribute simply contains the user role.

Directive

This is the implementation of the hasRole directive.

directives.js

const { SchemaDirectiveVisitor, ForbiddenError } = require('apollo-server-micro')
const { defaultFieldResolver } = require('graphql')

...

// Custom directive to check if user has role
class hasRole extends SchemaDirectiveVisitor {
  // Field definition directive
  visitFieldDefinition (field) {
    // Get field resolver
    const { resolve = defaultFieldResolver } = field

    // List of roles from directive declaration
    const roles = this.args.roles

    field.resolve = async function (...args) {

      // Get context
      const [, , context] = args

      // Check if user email is in context
      if (roles.indexOf(context.role) === -1) {
        throw new ForbiddenError('You are not authorized for this ressource.')
      }

      // Resolve field
      return resolve.apply(this, args)
    }
  }
}

module.exports = { isAuthenticated: isAuthenticated, hasRole: hasRole }

It throws an error if the context role is not included in the directive roles arguments.

Resolver

By default new users should get the role USER.

resolvers.js

...
    createUser: async (obj, args, context) => {
      // Check if user already exists
      const user = prepare(await (await usersCollection()).findOne({ email: args.email }))
      if (user) {
        throw new ForbiddenError('User already exists.')
      }

      // Default value
      args.role = args.role ? args.role : 'USER'

      // Hash password
      args.password = await bcrypt.hash(args.password, BCRYPT_ROUNDS)
      args.created = new Date()
      args.created_by = context.name || 'system'
      return prepare((await (await usersCollection()).insertOne(args)).ops[0])
    },
...

That’s it! You now have role based authorization for your GraphQL resources.

Before we reach the conclusion of this post series, we wanna ensure that the JWT token expires after week.

resolvers.js

...
    loginUser: async (obj, args, context) => {
      // Find user by email and password
      const user = prepare(await (await collection('users')).findOne({ email: args.email }))

      // Compare hash
      if (user && await bcrypt.compare(args.password, user.password)) {
        // Generate and return JWT token
        const token = jwt.sign({ email: user.email, name: (user.firstname + ' ' + user.lastname) }, process.env.JWT_SECRET, { expiresIn: '7d' })
        return { token: token }
      } else {
        // Throw authentication error
        throw new AuthenticationError('Login failed.')
      }
    }
...

Adding the expiresIn: '7d' option to the sign method ensures that the verify method will throw an error if the token has expired.

Conclusion

In this post series we covered the basic of authentication with GraphQL and a React App. The solutions provided here are supposed to give you a basic idea and a far from production ready. Having type definitions and access control in the same place is very convenient. That is what like most about GraphQL. Having this flexible layer that unifies access control, api access and schema definitions.

I hope I was able to give you an idea and would be glad if you share your thoughts and question with me 😊.

Addition

Some final hints on what should be considered when developing an authentication solution like this.

JWT referesh token > Auth0 - Refresh Tokens: When to Use Them and How They Interact with JWTs
Token for identity only > iana - JSON Web Token Claims

Build an Apollo Graphql user authentication for your React app - part 2

Thu, 29 Aug 2019 19:34:07 +0200

In my last post we built a Graphql API that handles user authentication and authorization. In particular we added a loginUser query that returns a JWT token. This token can be used to access restricted resources. In this post I will show what the implementation looks like on Reacts side.

Walking through this guide requires basic React knowledge. We will use React Router for routing, React Hooks for executing Graphql queries and Matieral-UI for the component framework.

Files

Let’s get started with an overview of the project files.

Apollo.js: Apollo client configuration
HeaderLoginButton.js: Links to login page and handles logout
Login.js: Login page
Profile.js: View for user profile
queries.js: Exports all Graphql queries and mutations
Routes.js: React router component
hooks.js: Export React hooks

2019-09-18 Edit: Added React hook file

So obviously we are not going to build an React app from scratch. This guide assumes you already have one and intent to add authentication and authorization functionality.

Routes

Routes is a higher-order component (HOC) that connect our view components with specific routes.

Routes.js

import React from 'react'
import { Route } from 'react-router-dom'
import Home from './Home'
import Login from './Login'
import Profile from './Profile'

const Routes = () => (
  <>
    <Route exact path='/' component={Home} />
    <Route exact path='/login' component={Login} />
    <Route exact path='/profile' component={Profile} />
  </>
)

export default Routes

So if the user opens or gets redirected to /login the Login component will be shown.

So what does the Login component looks like?

Login.js

import React from 'react'
import { useLazyQuery } from '@apollo/react-hooks'
import { Redirect } from 'react-router'
import Paper from '@material-ui/core/Paper'
import Typography from '@material-ui/core/Typography'
import TextField from '@material-ui/core/TextField'
import Button from '@material-ui/core/Button'
import { LOGIN_USER } from './queries'
import Loading from './Loading'
import Error from './Error'
import { useForm } from './hooks'

const Login = () => {

  // Use form state
  const { values, handleChange, handleSubmit } = useForm((credentials) => loginUser(), {
    email: '',
    password: ''
  })

  // Lazy query for login user method
  const [loginUser, { called, loading, data, error }] = useLazyQuery(LOGIN_USER, { variables: values })

  // Wait for lazy query
  if (called && loading) return <Loading />

  // Show error message if lazy query fails
  if (error) return <Error message={error.message} />

  // Store token if login is successful
  if (data) {
    window.localStorage.setItem('token', data.loginUser.token)

    // Redirect to home page
    return <Redirect to='/' />
  }

  return (
    <Paper className={classes.paper}>
      <Typography className={classes.title} variant='h3' component='h1'>
        Login
      </Typography>
      <form onSubmit={handleSubmit}
      >
        <TextField
          variant='outlined'
          margin='normal'
          required
          fullWidth
          id='email'
          name='email'
          label='Email Address'
          type='email'
          value={values.email}
          onChange={handleChange}
          autoFocus
        />
        <TextField
          variant='outlined'
          margin='normal'
          required
          fullWidth
          id='password'
          name='password'
          label='Password'
          type='password'
          value={values.password}
          onChange={handleChange}
        />
        <Button
          type='submit'
          fullWidth
          variant='contained'
          color='primary'
          className={classes.submit}
        >
          Sign in
        </Button>
      </form>
    </Paper>
  )
}

export default Login

The component presents a login form. When credentials are submitted a React hook is used to run the lazy Graphql query and retrieve the JWT token. If the login is successful the token is stored in the local storage of the browser.

The form state is managed by a React hook as well. See the hooks.js for the simple useForm React hook example that can be reused for other form.

As you can see the query is imported from the queries.js file. This is externalized because we want to share queries among component.

queries.js

import gql from 'graphql-tag'

const GET_CURRENT_USER = gql`
{
    currentUser {
        firstname
        lastname
    }
}
`

const LOGIN_USER = gql`
query loginUser($email: String!, $password: String!) {
    loginUser(email: $email, password: $password) {
        token
    }
}
`

export {
  GET_CURRENT_USER,
  LOGIN_USER
}

And here is the useForm React hook.

hooks.js

import { useState } from 'react'

const useForm = (callback, data) => {
  const [values, setValues] = useState(data)

  const handleChange = (event) => {
    event.persist()
    setValues(values => ({
      ...values,
      [event.target.name]: event.target.value
    }))
  }

  const handleSubmit = (event, onSubmit) => {
    event.preventDefault()
    callback(values)
  }

  return {
    handleChange,
    handleSubmit,
    values
  }
}

export { useForm }

2019-09-18 Edit: Added useForm React hook

Apollo

We saw that the token is being stored in the local storage. But how is passed to Apollo server? This is done in the Apollo client.

Apollo.js

import ApolloClient from 'apollo-boost'
import React from 'react'
import PropTypes from 'prop-types'
import { ApolloProvider } from '@apollo/react-hooks'

// Initialize Apollo client
const client = new ApolloClient({
  uri: process.env.REACT_APP_APOLLO_URL || 'http://localhost:3000/api',
  request: async operation => {
    // Get JWT token from local storage
    const token = window.localStorage.getItem('token')

    // Pass token to headers
    operation.setContext({
      headers: {
        Authorization: token ? `Bearer ${token}` : ''
      }
    })
  }
})

// Define Apollo component
const Apollo = ({ children }) => (
  <ApolloProvider client={client}>
    {children}
  </ApolloProvider>
)

Apollo.propTypes = {
  children: PropTypes.object.isRequired
}

export default Apollo

This HOC initializes the Apollo client and connects to the API. For every request it check if a token is available and if so forwards it in the Bearer Authorization header.

Logout

Assuming the user has logged in, we can run queries that requires authorization from every other component.

Profile.js

import React from 'react'
import { useQuery } from '@apollo/react-hooks'
import Paper from '@material-ui/core/Paper'
import Typography from '@material-ui/core/Typography'
import { GET_CURRENT_USER } from './queries'
import Loading from './Loading'
import Error from './Error'

const Profile = () => {

  const { loading, error, data } = useQuery(GET_CURRENT_USER)

  if (loading) return <Loading />
  if (error) return <Error message={error.message} />

  return (
    <Paper>
      <Typography variant='h3' component='h1'>
            Profil
      </Typography>
      <Typography component='p'>
        {`${data.currentUser.firstname} ${data.currentUser.lastname}`}
      </Typography>
    </Paper>
  )
}

export default Profile

The getCurrentUser query requires an authentication. Data is only shown if the user has logged in.

Now we got to the final step. Usually you’ll find a login/logout button on the top right of the nav bar. This button is called HeaderLoginButton in our case and handles the logout.

HeaderLoginButton.js

import React from 'react'
import { useQuery } from '@apollo/react-hooks'
import { Link } from 'react-router-dom'
import Button from '@material-ui/core/Button'
import { GET_CURRENT_USER } from './queries'

const HeaderLoginButton = () => {

  const { client, data } = useQuery(GET_CURRENT_USER)

  // Reset Apollo and local store on logout
  const logout = () => {
    window.localStorage.clear()
    client.resetStore()
  }

  if (data && data.currentUser) {
    return (
      <Button onClick={logout} color='inherit'>Logout</Button>
    )
  }
  return (
    <Link to='/login'>
      <Button color='inherit'>Login</Button>
    </Link>
  )
}

export default HeaderLoginButton

If the user is not logged in the button if clicked will redirect to the login page. Once the user has logged in the button will logout the user if clicked. The logout process simply gets rid of the token in the local storage and resets the Apollo client.

Here you can also observe the power React hooks. We don’t have to pass the Apollo client object down the hierarchy. Simply retrieve it from the useQuery hook!

That’s it! 🎉

In the next and final post we are going to improve our solution regarding security. Cliff hanger questions: What if the user copies the token and paste it after logout? How can we ensure that a token cannot be used indefinitely 😕?

Navigate to part 1 or part 3.

Additions

As already mentioned in my last post I focus on the modifications you have to make to the app in order get a user authentication. Proper implementation of course requires various other features. So here are some I can think of:

Password reset component
User profile page
Proper error and success notification
Redirect to error page if user is unauthorized
User signup process

Edits

2019-09-18: Added useForm React hook.

Build an Apollo Graphql user authentication for your React app - part 1

Tue, 27 Aug 2019 18:35:12 +0200

I am currently building an Apollo Graphql API and a React web application. The application requires a user authentication functionality in order to enforce access restrictions on the Graphql endpoint. Apollo Graphql does not provide an out-of-the-box-solution and therefore I would like to present my solution.

This post requires some basic knowledge about building APIs with Apollo and later on combining the Apollo Client with React. First we are going to define the user schema and implement the resolvers. For the authentication mechanism we are going to implement a query that expects user credentials and returns a JSON Web Token as response. This token will be used by the React app and passed as an Bearer Authorization header to every sequentially API call. The Apollo server verifies the token and restricts access on certain calls if an invalid token has been provided. The access restriction is enforced on schema field level using a custom directive.

Files

My Apollo server implementation consists of the following files:

index.js: Creates the Apollo server
schema.js: Contains Graphql type definitions
resolvers.js: Schema resolvers for data transformation and persistence
context.js: Verifies the JWT token
directives.js: Custom directives for the schema

Note: This guide does not cover how user data is stored and retrieved. Comments in the code snippets will point out where to implement these functionalities. In short this guide can be read regardless of the storage solution.

Schema

Let us start with the type definitions. I have split the schema.js file into several parts.

schema.js

const { gql } = require('apollo-server-micro')

// GraphQL schema
const typeDefs = gql`

directive @isAuthenticated on FIELD_DEFINITION

scalar Date

The Date scalar is custom type, ignore it for now. The isAuthenticated directive will be discussed later.

Next follows the user type.

type User {
  id: String!
  email: String!
  password: String!
  firstname: String!
  lastname: String!

  created: Date
  created_by: String!
  updated: Date
  updated_by: String!
}

Then the token and default response.

type Token {
  token: String!
}

type Response {
  success: Boolean!
  message: String
}

Queries are restricted by the custom directive.

type Query {
  currentUser: User @isAuthenticated
  users: [User] @isAuthenticated
  loginUser(email: String!, password: String!): Token
}

And here are the mutation we need to actually create and manipulate a user.

type Mutation {
  createUser(email: String!, password: String!, firstname: String!, lastname: String!): User
  updateUser(id: String!, email: String, password: String, firstname: String, lastname: String): Response
  deleteUser(id: String!): Response
}
`

module.exports = typeDefs

Put everything together and you got the schema definitions.

Resolvers

In the resolvers file we map schema types and fields with functions that return the actual data. You can think of it as actually implementing the schema.

resolvers.js

const { GraphQLScalarType } = require('graphql')
const { AuthenticationError, ForbiddenError } = require('apollo-server-micro')
const bcrypt = require('bcrypt')
const jwt = require('jsonwebtoken')
const { Kind } = require('graphql/language')

// Hash configuration
const BCRYPT_ROUNDS = 12

// Resolve GraphQL queries, mutations and graph paths
const resolvers = {
  Query: {
    users: async (obj, args, context) => {
      const user // -> Access data layer and get user data
      return user
    },
    currentUser: async (obj, args, context) => {
      const user // -> Access data layer and get user data
      return user
    },
    loginUser: async (obj, args, context) => {
      // Find user by email and password
      const user // -> Access data layer and get user data

      // Compare hash
      if(user && await bcrypt.compare(args.password, user.password)) {
        // Generate and return JWT token
        const token = jwt.sign({ email: user.email, name: (user.firstname + ' ' + user.lastname) }, process.env.JWT_SECRET )
        return { token: token }
      } else {
        // Throw authentication error
        throw new AuthenticationError('Login failed.')
      }
    }
  },
  Mutation: {
    createUser: async (obj, args, context) => {
      // Check if user already exists
      const user // -> Access data layer and get user data
      if (user) {
        throw new ForbiddenError('User already exists.')
      }

      // Hash password
      args.password = await bcrypt.hash(args.password, BCRYPT_ROUNDS)
      args.created = new Date()
      args.created_by = context.name || "system"
      const user // -> Access data layer and store user data
      return user
    },
    updateUser: async (obj, args, context) => {
      args.updated = new Date()
      args.updated_by = context.name || "system"

      // Hash password if provided
      if(args.password){
        args.password = await bcrypt.hash(args.password, BCRYPT_ROUNDS)
      }

      // -> Access data layer and update user data
      return { 
        success: true
      }
    },
    deleteUser: async (obj, args, context) => {
      // -> Access data layer and delete user data
      return { 
        success: true
      }
    }
  },
  User: {
    // Hide password hash
    password() {
      return ''
    }
  }
}

module.exports = resolvers

The most important part of the resolver files are the bcrypt and jwt method calls. If a user is created the plaintext password is hashed and stored in the database. If the loginUser query is called the user is retrieved and the password hash compared. If successful a JWT token is generated and returned.

Context

We assume that during the login process in the client app the Apollo client calls the loginUser query, retrieves token and stores it in the local storage. If set the token is passed in the Bearer Authentication header with each API call. On the Apollo server side the token must be verified and its claims added to the Apollo context.

So what is the context? To put it simply the context is an object that is available to all resolvers. From the context user claims can be accessed and e.g. passed to a database query.

context.js

const { AuthenticationError } = require('apollo-server-micro')
const jwt = require('jsonwebtoken')

const context = ({ req }) => {
  // Get the user token from the headers
  let token = req.headers.authorization ? req.headers.authorization.split(' ')[1] : null

  // Verify token if available
  if (token) {
    try {
      token = jwt.verify(token, process.env.JWT_SECRET)
    } catch (error) {
      throw new AuthenticationError(
        'Authentication token is invalid, please log in.'
      )
    }
  }

  return {
    email: token ? token.email : null,
    name: token ? token.name : null
  }
}

module.exports = context

If the token is set in the header and has been verified, the two claims email and name are then added to the context.

Directive

As I mentioned we enforce schema field access with a custom directive. In the isAuthenticated directive we simply check if the email property is set in the context object.

const { SchemaDirectiveVisitor, ForbiddenError } = require('apollo-server-micro')
const { defaultFieldResolver } = require('graphql')

// Custom directive to check if user is authenicated
class isAuthenticated extends SchemaDirectiveVisitor {
  // Field definition directive
  visitFieldDefinition (field) {
    // Get field resolver
    const { resolve = defaultFieldResolver } = field

    field.resolve = async function (...args) {
      // Check if user email is in context
      if (!args[2].email) {
        throw new ForbiddenError('You are not authorized for this ressource.')
      }

      // Resolve field
      return resolve.apply(this, args)
    }
  }
}

module.exports = { isAuthenticated: isAuthenticated }

Whenever a field declared with the isAuthenticated directive is queried, the directive will also ensure the user has a valid token.

Server

In the index.js we stitch everything together.

const { ApolloServer } = require('apollo-server-micro')
const cors = require('micro-cors')()
const typeDefs = require('./schema')
const resolvers = require('./resolvers')
const context = require('./context')
const directives = require('./directives')

// Initialize Apollo server
const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: context,
  introspection: true,
  playground: true,
  schemaDirectives: directives
})

// Export server as handler
module.exports = cors((req, res) => {
  // Workaround abort on Options method
  if (req.method === 'OPTIONS') {
    res.end()
    return
  }
  return server.createHandler({ path: '/api' })(req, res)
})

To those who noticed that I import apollo-server-micro instead of apollo-server, it is because I am deploying my apps as serverless functions with Zeit Now using their HTTP microservice.

Test

Start the Apollo server and open the Graphql playground.

Create a user with the createUser mutation.

mutation { 
  createUser(
    email: "login@example.com",
    password: "password",
    firstname: "Login",
    lastname: "Example"
  ) { id } }

{ loginUser(email: "login@example.org", password: "password") {
  token
} }

Copy the token in to the HTTP header field.

{
    "Authorization": "Bearer YOUR_TOKEN_HERE"
}

Query the user info.

{ currentUser {
  firstname
  lastname
  email
  password
  id
} }

What the final query should look like:

If this worked you have reached the end of part 1 😊.

In part 2 I will show how we implement the user authentication mechanism in a React app.

Additions

I try to keep my guides as slick as possible and therefore intentionally do not cover certain parts. But at least I wanna let know you which parts I ignored.

In order to provide a full user accounting module of course more queries are required. You would at least have to implement the following ones:

signupUser: Public query to create user account.
verifyUserEmail: Query to verify user account.
resetUserPassword: Query to initiate password reset.

If you have any questions, feel free to ask below 👋.

Updates

2019/08/30: Updated all code snippets after applying JavaScript Standard Style guide. Removed unnecessary await statements.

Reactive subscriptions with Apollo and React

Mon, 28 Nov 2016 12:27:08 +0000

Apollo server and client support real-time subscriptions with web sockets. Compared to Meteor’s out of the box real-time communication this is a lot more difficult to set up. With this short tutorial I’ll give you an example of how you can get a simple reactive subscriptions into your Apollo/React app. The idea is that you use real-time communication for a specific case only, f.g. sending notifications. We will accomplish this in five steps.

Install project requirements.
Setup the server schema.
Add server resolvers.
Setup the client subscription.
Modify a component to receive data from a subscription.

As reference you can have look at this project: Meteor Apollo Accounts Example

The concept of GraphQL subscriptions in Apollo:

Install project requirements

I assume you already have an Apollo (server) and React (client) application up and running. To get started we need to install the GraphQL subscription package for the server.

npm install --save graphql-subscriptions

This packages extends the GraphQL schema for subscriptions.

As client server implementation for the subscription communications we use the subscriptions transport web socket package.

npm install --save subscriptions-transport-ws

This package will be used to set up the web socket client and server.

Setup server schema

Subscriptions are similar to queries and have their own type definition. For our example we add trigger based subscriptions to our schema which means they send data based on specific events.

server/schema.js

...
const rootSchema = [`

type Post {
  _id: ID
  title: String
}

type Mutation {
  insertPost(
    title: String
  ): Post
  deletePost(
    _id: ID
  ): SuccessResponse
  updatePost(
    _id: ID
    title: String
  ): SuccessResponse
}

type Subscription {
  postInserted: Post
  postDeleted: ID
  postUpdated: Post
}

type Query {
  posts: [Post]
}

schema {
  query: Query
  mutation: Mutation
  subscription: Subscription
}
`]
...

Whenever the post type is modified we will submit the mutation in real-time to the clients.

To dispatch data to the web socket connection we have to set up a subscriptions manager.

server/subscriptions.js

import { PubSub, SubscriptionManager } from 'graphql-subscriptions';
import { schema } from './index';

const pubsub = new PubSub();
const subscriptionManager = new SubscriptionManager({
  schema,
  pubsub,
});
export { subscriptionManager, pubsub };

It is a middle ware between the web socket server and the GraphQL schemas.

Next add a web socket server instance to server application and pass and pass the SubscrptionManager config.

server/main.js

import { schema, Posts, subscriptionManager } from './index'
import { createApolloServer } from 'meteor/apollo';
import { createServer } from 'http';
import { SubscriptionServer } from 'subscriptions-transport-ws';

const WS_PORT = process.env.WS_PORT || 8080;

createApolloServer({
  schema: schema,
});

const httpServer = createServer((request, response) => {
  response.writeHead(404);
  response.end();
});
httpServer.listen(WS_PORT, () => console.log(
  `Websocket Server is now running on http://localhost:${WS_PORT}`
));
const server = new SubscriptionServer({ subscriptionManager }, httpServer);

Add server resolvers

First add the resolvers for the subscription queries.

server/resolvers.js

...
const resolvers = {
  Query: { ... },
  Mutation: { ... },
  Subscription: {
    postInserted(post) {
      return post;
    },
    postDeleted(_id) {
      return _id;
    },
    postUpdated(post) {
      return post;
    },
  },
}
...

Then tell the other mutation resolvers to dispatch mutation data. I’m using Meteor and MongoDB to store the post data. It is not required that you have the same setup. Just make sure that a mutation event triggers a publication on the pubsub manager.

sever/resolver.js

import { Posts, pubsub } from './index'
...
Mutation: {
    insertPost(root, args, context){
        return Posts.insert(args, (error, response) => {
          if(response){
            args._id = response
            pubsub.publish('postInserted', args)
          }
        })
    },
    deletePost(root, args, context){
        return { success: Posts.remove(args, (error, response) => {
          if(response){
            pubsub.publish('postDeleted', args._id)
          }
        }) }
    },
    updatePost(root, args, context){
        let _id = args._id
        delete args._id
        return { success: Posts.upsert(_id, { $set: args }, (error, response) => {
          if(response){
            args._id = _id
            pubsub.publish('postUpdated', args)
          }
        }) }
    },
...

Our server is now ready to send subscriptions data in real-time.

Setup the client subscription

Now we configure our client to receive data sent by the publication. For this we configure a Apollo network interface.

client/Subscriptions.js

import { print } from 'graphql-tag/printer';

const addGraphQLSubscriptions = (networkInterface, wsClient) => Object.assign(networkInterface, {
  subscribe: (request, handler) => wsClient.subscribe({
    query: print(request.query),
    variables: request.variables,
  }, handler),
  unsubscribe: (id) => {
    wsClient.unsubscribe(id);
  },
});

export default addGraphQLSubscriptions;

And connect it to our Apollo client.

client/ApolloClient.js

import ApolloClient, { createNetworkInterface } from 'apollo-client'
import { Client } from 'subscriptions-transport-ws';
import { addGraphQLSubscriptions } from './index';

const wsClient = new Client('ws://localhost:8080');

const networkInterface = createNetworkInterface({ uri: '/graphql' })

const networkInterfaceWithSubscriptions = addGraphQLSubscriptions(
  networkInterface,
  wsClient,
);

const client = new ApolloClient({
  networkInterface: networkInterfaceWithSubscriptions,
})

export default client

There is nothing more to do. We can now subscribe to a publication and receive data from the server.

Modify a component to receive data from a subscription

Finally I give an example of a modified React component that is able to mutate a post model list, make subscriptions and receive emitted events from a publication.

client/PostList.js

import React from 'react'
import { graphql } from 'react-apollo'
import gql from 'graphql-tag'
import { ApolloClient, Notification } from './index'
import _ from 'underscore'

const postInserted = gql`
  subscription postInserted {
    postInserted {
      _id
      title
    }
  }
`;

const postDeleted = gql`
  subscription postDeleted {
    postDeleted
  }
`;

const postUpdated = gql`
  subscription postUpdated {
    postUpdated {
      _id
      title
    }
  }
`;

class PostList extends React.Component {

  constructor(props) {
    super(props)
    this.state = {}
    this.subscription = null
  }

  componentWillReceiveProps(nextProps) {
    if (!this.subscription && !nextProps.data.loading) {
      let { subscribeToMore } = this.props.data
      this.subscription = [subscribeToMore(
        {
          document: postInserted,
          updateQuery: (previousResult, { subscriptionData }) => {
            previousResult.posts.push(subscriptionData.data.postInserted)
            return previousResult
          },
        }
      ),
      subscribeToMore(
        {
          document: postDeleted,
          updateQuery: (previousResult, { subscriptionData }) => {
            previousResult.posts = _.without(previousResult.posts, _.findWhere(previousResult.posts, {
              _id: subscriptionData.data.postDeleted
            }));
            return previousResult
          },
        }
      ),
      subscribeToMore(
        {
          document: postUpdated,
          updateQuery: (previousResult, { subscriptionData }) => {
            previousResult.posts = previousResult.posts.map((post) => {
              if(post._id === subscriptionData.data.postUpdated._id) {
                return subscriptionData.data.postUpdated
              } else {
                return post
              }
            })
            return previousResult
          },
        }
      )]
    }
  }

  async insert(event) {
    event.preventDefault()

    let { insertPost, data } = this.props
    let { insertTitle } = this.refs
    let title = insertTitle.value

    try {
      const response = await insertPost({ title })
      Notification.success(response)
    } catch (error) {
      Notification.error(error)
    }
  }

  async delete(_id, event) {
    event.preventDefault()

    let { deletePost, data } = this.props

    try {
      const response = await deletePost({ _id })
      Notification.success(response)
    } catch (error) {
      Notification.error(error)
    }
  }

  edit(_id) {
    this.setState({edit: _id})
  }

  async update(_id) {
    let { updatePost, data } = this.props

    let { updateTitle } = this.refs
    let title = updateTitle.value

    try {
      const response = await updatePost({ _id, title })
      Notification.success(response)
      this.setState({edit: null})
    } catch (error) {
      Notification.error(error)
    }
  }

  render() {
    let { posts, loading } = this.props.data
    let { edit } = this.state

    return loading ? (<p>Loading...</p>) : (
      <div>
        <h2>Posts</h2>
        <form onSubmit={this.insert.bind(this)}>
          <label>Title: </label>
          <input
          defaultValue="Untitled"
          type="text"
          required="true"
          ref="insertTitle" />
          <br />
          <button type="submit">Insert Post</button>
        </form>
        { posts ? (
          <ul>
            {posts.map((post) => {
              return (
                edit === post._id ?
                  <li key={post._id}>
                    <input
                    ref="updateTitle"
                    defaultValue={post.title}
                    size="50"
                    type="text" />
                    <button onClick={this.update.bind(this, post._id)}>Update</button>
                  </li> : <li key={post._id}>
                    <span onClick={this.edit.bind(this, post._id)}>{post.title} </span>
                    <button onClick={this.delete.bind(this, post._id)}>Delete</button>
                  </li>
              )
            })}
          </ul>
        ) : <p>No posts available.</p> }
      </div>
    )
  }
}

const query = gql`
query getData {
  posts {
    _id
    title
  }
}
`

const insertPost = gql`
mutation insertPost($title: String) {
  insertPost(title: $title){
    _id
  }
}
`

const deletePost = gql`
mutation deletePost($_id: ID) {
  deletePost(_id: $_id){
    success
  }
}
`

const updatePost = gql`
mutation updatePost($_id: ID, $title: String) {
  updatePost(_id: $_id, title: $title){
    success
  }
}
`

PostList = graphql(updatePost, {
  props({ mutate }) {
    return {
      updatePost({_id, title}) {
        return mutate({ variables: { _id, title }})
      }
    }
  },
})(graphql(deletePost, {
  props({ mutate }) {
    return {
      deletePost({_id}) {
        return mutate({ variables: { _id }})
      }
    }
  },
})(graphql(insertPost, {
  props({ mutate }) {
    return {
      insertPost({title}) {
        return mutate({ variables: { title }})
      }
    }
  },
})(graphql(query)(PostList))))

export default PostList

Hope you liked this tutorial.

Source

Apollo Example GitHunt server

Apollo Example GitHunt React client

GraphQL Subscriptions in Apollo Client

A proposal for GraphQL subscriptions

GraphQL Subscriptions in Apollo Client

Authenticate Meteor accounts with the Apollo GraphQL API

Sat, 12 Nov 2016 10:21:20 +0000

One of the popular features of Meteor is its accounts package. As you know, it makes it fairly easy to add a user authentication solution to your Meteor app or add support for different oAuth services. With the possibility to integrate an Apollo GraphQL API into your Meteor app this became a bit more difficult. The Apollo stack does not support an out of the box solutions to authenticate users with Meteor accounts. Jonas Helfer, one of the Apollo core devs, proposed two ways to authenticate users with your app:

Let the web server (e.g. express or nginx) take care of authentication.
Handle authentication in GraphQL itself.

Of course this was not meant especially for Meteor, however, it gave some direction where this is going for Meteor. Obviously the first solution is not very attractive, if possible you want to use one API to exchange data only. So I looked for a solution where it was possible to extend an existing GraphQL schema and authenticate Meteor user accounts without the hassle to write GraphQL resolvers or client methods. Nicolas Lopes built exactly what I was looking for:

Meteor Apollo Accounts An implementation of Meteor Accounts only in GraphQL with Apollo.

The package was still early in development, so I decided to help him out. Not only because I wanted this package to work, but also because I never contributed to an open source project before. Nicolas looked for someone building him an example app. Perfect for me. One month later I’ve built an example app that implements all the Meteor accounts features one would expect:

Meteor Apollo Accounts Example Example app implementing Meteor Apollo Accounts.

Together we solved quite a lot of issues and learned a lot. Building the example app was kind of software testing for Nicolas and him telling me about his style of coding and PR requirements taught me a lot about open source contribution and coding skills. So in conclusion this was a great experience.

Graphql with Apollo, Meteor and React

Sun, 09 Oct 2016 19:39:30 +0000

For my last project I had to build a web application to administrate a MongoDB database. Due to using Meteor quite a lot I heard about Graphql and the Apollostack. Graphql, which is a specification done by Facebook engineers, promises to be the better REST API (which I hope it is). I became curious and decided the build the server API with Apollo. First I tried to evade using the Meteor as build system as I don’t want to get too accustomed to this full-stack ecosystem. However, building a live-reload server and client build system in ES6 with Node.js, Babel and Webpack was simply too much work compared to building this simple web app. So in result this was my stack:

Build system > Meteor
Graphql client > React and Apollo
Graphql server > Express and Apollo

Learning Graphql and how to use Apollo in this environment was a bit of a challenge. As Apollo is still the new kid on the block and its documentation lacks a few chapters I had to checkout the source code a few other projects to learn more about it. Graphl involves a few new concepts and makes you build APIs differently. Whereas in REST you build a hierarchical, untyped and strict interface in Graphql the possibilities first seem endless. Apollo delivers a high grade of flexibility in designing schemas and abstraction of data gathering with a set of resolvers. This might by overwhelming at the beginning, but is a lot of fun once you understand it. Despite the project was quite easy I had to solve a lot of issues. To make life easier for fellow Meteor, React, Apollo developer I’ll share the source code of my project and list the most interesting problems I’ve solved:

GitHub repository: https://codeberg.org/janikvonrotz/Apometact

Custom scalar data types

In all of my models I’m using the default Date data type. As Apollo basically only supports strings and numbers to be transported I came up with this solution.

schema.js

scalar Date
...
type Category {
  id: String
  label: String
  createdAt: Date
}
...

Define a new scalar, which is basically another type.

resolvers.js

  Date: {
    __parseValue(value) {
      return new Date(value); // value from the client
    },
    __serialize(value) {
      return value.toISOString(); // value sent to the client
    },
    __parseLiteral(ast) {
      return ast.value;
    },
  },

And tell Apollo how to parse it when receiving queries or dispatch data.

Now you can send date types as string to the Graphql interface.

Multiple queries and mutators in a React component

All the examples as part of the source code of projects or the documentation didn’t tell how to use multiple mutators and queries in a React component. Here’s how I’ve solved it:

CategoryEdit.js

...
const updateMutation = gql`
mutation updateCategory($id: String, $label: String) {
  updateCategory(id: $id, label: $label)
}
`;
const deleteMutation = gql`
mutation deleteCategory($id: String) {
  deleteCategory(id: $id)
}
`;
const CategoryEditWithMutation = graphql(updateMutation, {
  props({ mutate }) {
    return {
      updateCategory({id, label}) {
        return mutate({ variables: { id, label }});
      }
    };
  },
})(graphql(deleteMutation, {
  props({ mutate }) {
    return {
      deleteCategory(id){
        return mutate({ variables: { id }});
      }
    };
  },
})(CategoryEdit));

const query = gql`
query getCategory($id: String) {
  category(id: $id) {
    id
    label
  }
}
`;
const CategoryEditWithData = graphql(query, {
  options: (ownProps) => ({ variables: { id: ownProps.params.id } }),
})(CategoryEditWithMutation);

export default CategoryEditWithData;
...

Multiple queries can be lined up in one Graphql tag whereas mutators have to be divided (as long you don’t wish to run multiple mutators in one call).

Mongoose promises in Apollo resolver

Node.js runs asynchronously and so does Apollo. Instead of retrieving data from another endpoint you’ll pass a callback function which will be executed once the endpoint delivered its data. When defining resolvers in Apollo you have to switch roles. Instead of returning pure data in a resolve function you have to return a promise, which can be executed in a callback.

resolvers.js

...
categories(root, args){
  return Categories.find({}).then((items) => {
    return items.map((item) => {
      item.id = item._id;
      return item;
    });
  });
},
...

Define with then and catch the returned promise.

mongoose.js

...
Mongoose.Promise = global.Promise;
...
var CategoriesSchema = new Schema({
  label: String,
  createdAt: Date
});
var Categories = mongo.model('Categories', CategoriesSchema);
...

Set the ES6 default Promise object for Mongoose.

Load configurations the right way

This is not necessarily a use case for this kind of project, but I would like to share it anyway. Loading configurations works kind of different in Meteor than it does in Node.js.

First an example of how I load configurations in Node.js.

node-config.js

import fs from 'fs';

var config = {}
var path = `./${process.env.NODE_ENV || 'development'}.json`
try {
  fs.accessSync(path, fs.F_OK);
  console.log(`Load configurations from ${path}`)
  config = require(path);
} catch (error) {
  console.log(error)
}

// load environment variables
config = Object.assign(config, process.env);

export default config;

Based on the environment variable a json file will be chosen and loaded. All the configurations then will be overwritten by the available environment variables (necessary when deploying to most app host services like Heroku or Modulus).

meteor-config.js

import { Meteor } from 'meteor/meteor';

var config = Object.assign(Meteor.settings.private, Meteor.settings.public);

export default config

The meteor app can be started with this npm command: "start": "meteor --production --settings ./production.json",

Now in both cases the code creates an object containing configurations.