Cancelling an axios request from within machine

[bflemi3]

Looking through the interwebs on best practices for cancelling a request in xstate v5 yielded nothing of note... so I thought I'd post a new discussion on how I accomplished this task. Feedback is welcome!

I'm currently using xstate@5.5.1.

My use case

Users upload documents to our system. Each document is uploaded as a multipart upload to AWS S3 via a signed URL, retrieved from our API. The user can cancel the uploading process at anytime, for any document. When the user cancels the upload process, if the file is currently being uploaded, the multipart upload requests need to be aborted. Pretty standard stuff...

How?

I found a ton of examples on how to abort requests in xstate v4, but nothing on how to do this in v5. Here's how I did it...

Create the AbortController in the context of the Machine

Each document upload machine is responsible for instantiating their own AbortController and sending it to the upload actor in the uploading state. The request abort occurs upon exit of the uploading state. In this way, if there's a transition out of the uploading state for any reason, the upload is aborted. This simplifies the cancellation of the upload process, and decouples the cancelling state so that it's solely responsible for notifying the parent (the machine that manages all the document uploads) that it needs to be stopped.

For brevity, I'll show the relevant parts of the machine.

documentUploadMachine.ts

const documentUploadMachine = createMachine({
  id: 'Document Upload Machine',
  context: ({ input: { file } }) => ({
    file,
    uploadAbortController: new AbortController(),
  }),
  initial: 'init',
  on: {
    CANCEL: { target: '.cancelling' }
  },
  states: {
    ...
    start: {
      invoke: {
        src: 'getMultipartUploadUrls',
        input: ({ context: { file } }) => ({ file }),
        onDone: { 
          target: 'uploading', 
          actions: assign(({ event }) => ({ uploadUrls: event.ouput.urls  })) 
        },
        onError: { target: 'failed', actions: assign({ error: 'initialize upload failed' }) }
      },
    },
    uploading: {
      entry: ['resetProgress'],
      exit: [
        ({ context }) => context.uploadAbortController.abort(), // The important part
        'resetProgress'
      ],
      invoke: {
        src: 'upload',
        input: ({ context: { file, uploadAbortController, uploadUrls }, self }) => ({ 
          abortController: uploadAbortController, 
          file, 
          parentId: self.id,
          urls: uploadUrls 
        }),
        onDone: { target: 'startProcessing' },
        onError: { target: 'failed', actions: assign({ error: 'uploading error' }) },
      },
    },
    cancelling: {
      ...
    },
  },
})

Use the AbortController in the upload actor

The abort controller is passed to the upload actor. I use axios@1.6.5, but this could be done with any library (including the fetch API) that consumes the AbortController. Again, for brevity I'll only add the relevant parts.

./actors/upload.ts

import uploadPart from '../utils/uploadPart'

interface Input {
  abortController: AbortController
  file: File
  parentId: string
  urls: string[]
}

const upload = fromPromise<IMultipartPart[], Input>(
  async ({ input: { abortController, file, parentId, urls }, system }) => {
    const partCount = urls.length
    const total = file.size
    const parent = system.get(parentId) as ActorRefFrom<typeof documentUploadMachine>

    const overallProgress = Array.from({ length: partCount }).map(() => 0)

    const _onUploadProgress = (part: number) => (event: AxiosProgressEvent) => {
      overallProgress[part - 1] = event.loaded
      const loaded = overallProgress.reduce((loaded, part) => loaded + part, 0)
      
      // Let the user know the progress of their overall upload
      parent.send({ type: 'PROGRESS', value: (loaded * 100) / total })
    }

    const parts = await Promise.all(
      urls.map((url, index) => {
        const partNumber = index + 1

        return uploadPart(
          url,
          { file, partCount, partNumber },
          { signal: abortController.signal, onUploadProgress: _onUploadProgress(partNumber) }
        )
      })
    )

    return parts
  }
)

./utils/uploadPart.ts

interface UploadPartOptions extends Pick<AxiosRequestConfig, 'onUploadProgress'> {
  file: File
  partCount: number
  partNumber: number
}

export default async function uploadPart(
  url: string,
  options: UploadPartOptions,
  config?: AxiosRequestConfig
): Promise<IMultipartPart> {
  const { file, partCount, partNumber } = options
  const chunk = getChunk(partNumber, file, partCount)
  const response = await axios.put(url, chunk, config).catch((e) => {
    if (axios.isCancel(e)) {
      console.log('Request cancelled', e.message)
      return
    }

    throw e
  })

  return { eTag: response.headers.etag, partNumber }
}

The architected solution above works well for my use case. It may not for yours.

My intent was to have a request cancellation solution for xstate v5 published for others to find and adapt to their use case. I welcome feedback, criticism and questions 🙏

[lyleunderwood]

Cleaner than what I was going to do!