@kalisio/feathers-automerge-server

Package to set up an automerge sync server that synchronizes documents with a Feathers API.

Usage

As a sync server

In your Feathers application, add the following to your app file:

import { automergeServer } from '@kalisio/feathers-automerge-server'

//...
app.configure(services)
app.configure(
  automergeServer({
    directory: '../../data/automerge',
    serverId: 'test-server',
    syncServicePath: 'automerge',
    async authenticate(accessToken) {
      if (!accessToken) {
        return false
      }
      // Check with the local authentication service if the token is valid
      await app.service('authentication').create({
        strategy: 'jwt',
        accessToken
      })

      return true
    },
    async initializeDocument(servicePath, query) {
      if (servicePath === 'todos') {
        const { username } = query
        return app.service('todos').find({
          paginate: false,
          query: { username }
        })
      }

      return null
    },
    async getDocumentsForData(servicePath, data, documents) {
      if (servicePath === 'todos') {
        return documents.filter(doc => data.username === doc.query.username)
      }

      return []
    },
    async canAccess(query, user) {
      // Only allow access to documents where the query username matches the authenticated user
      return query.username === user?.username
    }
  })
)

Server to server synchronization

import { automergeServer } from '@kalisio/feathers-automerge-server'

//...
app.configure(services)
app.configure(
  automergeServer({
    syncServerUrl: 'https://server.com',
    directory: '../../data/automerge',
    serverId: 'test-server',
    syncServicePath: 'automerge',
    async getAccessToken() {
      const response = await fetch('http://localhost:3030/authentication', {
        body: JSON.stringify({
          strategy: 'local',
          email: '[email protected]',
          password: 'test'
        }),
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        }
      })
      const { accessToken } = await response.json()
      return accessToken
    },
    async initializeDocument(servicePath, query) {
      if (servicePath === 'todos') {
        const { username } = query
        return app.service('todos').find({
          paginate: false,
          query: { username }
        })
      }

      return null
    },
    async getDocumentsForData(servicePath, data, documents) {
      if (servicePath === 'todos') {
        return documents.filter(doc => data.username === doc.query.username)
      }

      return []
    },
    async canAccess(query, user) {
      // Only allow access to documents where the query username matches the authenticated user
      return query.username === user?.username
    }
  })
)

Options

The following options are available:

Common Options

• directory: string: The directory where the automerge repository data will be stored. The root document ID will be automatically stored in a automerge-server.json file in this directory.
• serverId: string: A unique identifier for this server instance (used to track data source).
• syncServicePath: The service path where the automerge sync service will be mounted (e.g., 'automerge').
• canAccess(query: Query, params: Params): Promise<boolean>: An async function that controls access to documents based on the query and service call params. Called for all operations when a provider is present in params (external calls).
• initializeDocument: (servicePath: string, query: Query, documents: SyncServiceInfo[]) => Promise<unknown[]>: An async function that initializes document data for a given service path and query. Called when creating new documents.
• getDocumentsForData: (servicePath: string, data: any, documents: SyncServiceInfo[]) => Promise<SyncServiceInfo[]>: An async function that determines which documents should be updated when service data changes.
• getInitialDocuments: (app: Application) => Promise<SyncServiceInfo>: Return the documents to load when there are no local documents on this server. This is useful when running as a client (syncServerUrl is pointing to another server) to determine which documents should be synced with this instance.

Server Options

• syncServerWsPath?: string: The websocket path for the local sync server
• authenticate: (accessToken: string | null) => Promise<boolean>: Authenticate an access token that was passed to the connection of the local sync server.

Client Options

• syncServerUrl?: string: Connect to another remote sync server instead (for server to server synchronization)
• getAccessToken?: () => Promise<string>: Get an access token for the remote sync server.