How to plug external services into a state machine?

[HerbCaudill]

I'm using Xstate to model a peer-to-peer authentication protocol. It's network-agnostic, so for example you'd need to provide it with a sendMessage function that you've wired up to an existing communications channel (WebSocket, WebRTC, etc).

I've stubbed out different actions like claimIdentity and challengeClaim etc. that would call sendMessage.

What's the correct way to allow the developer to provide their own sendMessage function?

Options I've considered:

• Make a dummy sendMessage action, with the expectation that the developer will override it using .withConfig() (although I haven't figured out how to invoke one action from another one, or if that's even a thing)
• Wrap the machine in a class that is instantiated with a sendMessage function

[davidkpiano]

Using an invoked callback would work best here:

import { createMachine, actions } from 'xstate';

const sendMessage = message => actions.send({ type: 'sendMessage', message }, { to: 'auth' });

const machine = createMachine({
  invoke: {
    id: 'auth',
    src: () => (cb, receive) => {
      const authProtocol = ...

      receive(e => {
        if (e.type === 'sendMessage') {
          authProtocol.sendMessage(e.message);
        }
      });

      // ...
    }
  },
  // ...
    on: {
      CLICK: { actions: sendMessage('clicked') }
    }
  }
});

[HerbCaudill]

Thanks, David. I'm not following from your example how a developer using my machine would provide their own sendMessage function.

At the risk of providing way too much detail, here's an implementation that I've worked out using the second approach from my original post (wrap the machine in a class):

(way too much detail)

```ts export class ConnectionService { private sendMessage: SendFunction = message => { throw new Error('Send must be implemented') }

private context: ConnectionContext

constructor(options: { sendMessage: SendFunction; context: ConnectionContext }) {
const { sendMessage, context } = options
this.sendMessage = sendMessage
this.context = context
}

public start = () => {
const machine = this.connectionMachine.withContext(this.context)
const service = interpret(machine)
return service.start()
}

private connectionMachine = createMachine<ConnectionContext, ConnectionEvent, ConnectionState>(
{
id: 'connection',
initial: 'disconnected',
states: {
disconnected: {
id: 'disconnected',
on: { CONNECT: 'connecting' },
},
connecting: {
id: 'connecting',
type: 'parallel',
states: {
claimingIdentity: {
initial: 'awaitingChallenge',
states: {
awaitingChallenge: {
entry: ['claimIdentity'],
on: {
CHALLENGE_IDENTITY: {
actions: ['sendProof'],
target: 'awaitingConfirmation',
},
},
},
awaitingConfirmation: {
on: { ACCEPT_IDENTITY: { target: 'success' } },
},
success: { type: 'final' },
},
},
verifyingIdentity: {
initial: 'awaitingClaim',
states: {
awaitingClaim: {
on: {
CLAIM_IDENTITY: {
cond: { type: 'identityIsKnown' },
actions: ['challengeClaim'],
target: 'awaitingProof',
},
},
},
awaitingProof: {
on: {
PROVE_IDENTITY: {
cond: { type: 'proofIsValid' },
actions: ['sendConfirmation'],
target: 'success',
},
},
},
success: { type: 'final' },
},
},
},
onDone: 'connected',
},
connected: { type: 'final' },
},
},
{
actions: {
claimIdentity: (context, event) => {
const claimMessage = ...
this.sendMessage(claimMessage)
},

    challengeClaim: (context, event) => {
      const claimMessage = ...
      const challengeMessage = ...
      this.sendMessage(challengeMessage)
    },

    sendProof: (context, event) => {
      const proofMessage = ...
      this.sendMessage(proofMessage)
    },

    sendConfirmation: (context, event) => {
      const confirmMessage = ...
      this.sendMessage(confirmMessage)
    },
  },
  guards: {
    identityIsKnown: (context, event) => {...},

    proofIsValid: (context, event) => {...},
  },
}

)
}

And here's a test illustrating how this is used:

```ts
it(`should successfully verify someone's identity`, () => {
  // Create a new team and add Bob to it
  const team = newTeam()
  team.add(bob)

  // Our dummy `sendMessage` just pushes messages onto a queue
  const messageQueue: ConnectionEvent[] = []
  const sendMessage = (message: ConnectionEvent) => messageQueue.push(message)

  // Instantiate the connection service
  const alice = new ConnectionService({
    context: { team, user: alice },
    sendMessage,
  }).start()

  // we test the one side of the verification workflow, using a real ConnectionService for Alice and manually simulating Bob's responses

  // at the beginning, Alice is disconnected
  expect(alice.state.value).toEqual('disconnected')

  // Alice connects & waits for the other end to claim an identity
  alice.send('CONNECT')
  expect(alice.state.value).toEqual({
    connecting: { claimingIdentity: 'awaitingChallenge', verifyingIdentity: 'awaitingClaim' },
  })

  // Bob sends a message claiming that he is Bob
  const claimMessage = identity.claim({ type: MEMBER, name: 'bob' })
  alice.send(claimMessage)

  // Alice automatically sends Bob a challenge & waits for proof
  expect(alice.state.value).toEqual({
    connecting: { claimingIdentity: 'awaitingChallenge', verifyingIdentity: 'awaitingProof' },
  })

  // Bob generates proof by signing Alice's challenge and sends it back
  const challengeMessage = lastItem(messageQueue) as ChallengeIdentityMessage
  const proofMessage = identity.prove(challengeMessage, bob.keys)
  alice.send(proofMessage)

  // Success! Alice has verified Bob's identity
  expect(alice.state.value).toEqual({
    connecting: { claimingIdentity: 'awaitingChallenge', verifyingIdentity: 'success' },
  })
})

This works, but I'm wondering if there's a more idiomatic way to do this with XState.

[HerbCaudill]

Trying again with many fewer lines of sample code! 😀

The solution I've come up with is to wrap my state machine in a class, and to provide sendMessage to the class constructor.

export class ConnectionService {
  private sendMessage

  constructor(sendMessage) {
    this.sendMessage = sendMessage
  }

  public start = () => {
    const machine = createMachine(
        {
          // ... XState config
        },
        {
          actions: {
            someAction: (context, event) => {
              // ...
              this.sendMessage(...)
            },

        }
      )
      const service = interpret(machine)
      return service.start()
    }
  }
}

This way whoever is consuming my ConnectionService can wire up sendMessage however they see fit:

const sendMessage = message => {
  // ... developer implements message sending here - could be WebSocket, WebRTC, carrier pigeon, etc.
}

const alice = new ConnectionService(sendMessage).start()

Again - this works, but feels non-idiomatic. Is there a more natural way to do this in XState?

[Andarist]

If you need to have this configurable by the consumer this LGTM. You could also use withConfig, but this is OK as well - I would mysef probably go for a factory-like approach over withConfig most if the time. It seems easier to reason about to me as you dont have to learn any new APIs and how exactly it behaves, you can use "just JavaScript"™ to get the job done.