Context

"Context" is a feature that allows you to pass custom data about the current user around.

This is very useful when you need to read/write data based on information that is not relevant to the collaboration system itself.

important

The context feature uses a custom header called collab-context. If you are deploying the collab server behind a proxy or something similar, the collab-context header must be accepted and forwarded for this feature to work.

Example#

Let's start with a simple example to show why context is useful.

On the client we set some application specific information about the current user. In this example lets pretend they navigated into a "project" with the ID 'abc'. Our resolvers need this data, so we need to set that data in our context:

// Client code

import { CollabClient } from '@pdftron/collab-client'

const client = new CollabClient({ ...options })

await client.setContext({
  projectId: 'abc'
})

Now, our resolvers have access to this context whenever they are called:

// Server code

import CollabServer from "@pdftron/collab-server";

const server = new CollabServer({
  resolvers: {
    Mutation: {
      addDocument: async (doc, ctx) => {

        console.log(ctx) // { projectId: 'abc' }

        // get a reference to our fictional ORM
        const db = getDatabaseConnection();

        const newDoc = await db
          .insert('documents')
          .values({
            author_id: doc.authorId,
            is_public: doc.isPublic,
            name: doc.name,
            created_at: doc.createdAt,
            updated_at: doc.updatedAt,

            // Get project ID from context
            project_id: ctx.projectId
          });

        return newDoc;
      },
    },
  },
});

As you can see, this is useful for writing additional data that the collaboration system is not aware of. There are also many other use cases such as permissions.

Setting context#

Context must be set client side with the CollabClient module. See this guide for more info.

Using context#

Context is provided to most server side callback functions. This includes all resolvers, email handlers, authentication functions, permission callbacks, transform functions (SQL generator) and middleware (SQL generator)

See the relevant guides for more information.

Default values#

Whenever possible, the collaboration server will inject the userId property onto the context object. This property is not guaranteed to exist, but should be there if a user is signed in.

Security#

Context is stored in signed JWT cookies. Before passing context to your callback functions, we first verify the cookie to make sure it has not been altered. If the cookie has been altered, an error will be thrown. This ensures that users cannot modify the context before its sent to the server.

note

Even though the data in context is signed, it is still visible to the user. Do not store any information that you do not want visible to the user in context.