[Proposal] File Uploads

[jangerhofer]

After toying with the Express-GraphQL file upload demo, I have been thinking about how to bring file uploads inside GraphQL mutations to Apollo.

Here is the rundown of what I've learned and the best solution I have formulated:

• Canonical file uploads happen via a mutipart/form-data POST request, whereas Apollo Client interfaces with the Server exclusively with application/json requests at present.

• There are other ways to transmit a file from browser to server, but they are often flimsy and poor solutions.

• The ideal solution delivers both a GraphQL mutation and the uploaded file(s) to the server in such a way that the schema resolvers have access to the files, such that custom logic can test, modify, and/or store the uploads. The best way to ensure both mutation string and file(s) reach the server at the same time is to merge them into the same request.

• Thus, I think that Apollo Client needs to either

  • gain a new method, e.g. mutateWithFiles( "gqlQueryString", { apolloOptions }, [ files ] ) or
  • include a new option, e.g. uploadFiles : [ ... ]

  which, when used, sends a multipart/form-data POST to the specified Apollo Server endpoint. The request would be identical to the normal request apart from the inclusion of a new files field or similar which contains the uploading files. I think I would lean towards the clarity of a new method on account of readability.

• Apollo Server will then need to check each request for its content-type; if it is application/json, then no upload-specific logic happens and the mutation continues as usual. If, however, the POST is of content-type multipart/form-data, the server will append the files in memory to the root query object. The mutation then continues as usual.

  • This way, the files are available to the resolvers via the first root argument and subsequently to connectors if need-be.

Please chime in if you have any thoughts. I'd especially like for members of the Apollo team to offer their opinions. If we get to a design that satisfies the dev team, I am happy to work alongside any other interested parties to create a PR!

[stubailo]

That sounds pretty cool, I'd be interested to hear more about how people do this with express-graphql, and maybe also Relay today. The solution proposed sounds reasonable, but I want to see if it aligns with what other people have done.

[HriBB]

Using Koa v2 on the server. I have a custom /upload endpoint with async-busboy that handles file uploads for the entire app. For example I send type SalonPicture, list of files and all extra parameters. After a successful upload, I fire refresh-salon-pictures with fbemitter to refetch data on all components that listen to this specific event. It's not so bad, but I would prefer to have this logic in graphql. Unless someone can convince me otherwise.

I really like what @jangerhofer is proposing. Maybe we can support file uploads without even touching the core. We can create custom middleware for each server integration. On express and koa it should be possible, not sure about hapi.

As for the client. Can we somehow pull it of with middleware or do we need a custom NetworkInterface?

[stubailo]

Hmmm, OK, this is starting to sound pretty cool. What about this:

1. We pass files via variables to the mutation
2. The network interface looks through the variables, and looks for any files
3. The files are moved to the multipart request body, and the variable is replaced with some kind of reference
4. There's a server middleware that pulls files off the body, and puts them back into the variables in the right location
5. In your mutation arguments, you get a file object

Alternative:

1. (1-3 from above)
2. There's a server middleware that pulls files off the body, uploads them to a file storage service, and replaces the variables with a reference to that file on S3 or wherever
3. In your mutation arguments, you get a reference to a file that has been uploaded to S3 already

Other options?

Still interested to see if this server component will be compatible with Relay - someone should go look at how that works.

[HriBB]

I did some analysis. Most of the Relay examples use express-graphql. From the docs:

GraphQL will first look for each parameter in the URL's query-string
If not found in the query-string, it will look in the POST request body.
If a previous middleware has already parsed the POST body, the request.body value will be used. Use multer or a similar middleware to add support for multipart/form-data content, which may be useful for GraphQL mutations involving uploading files.

If that is what you mean?

[jangerhofer]

Two thoughts, @stubailo; first...

uploads them to a file storage service, and replaces the variables with a reference

Perhaps I am alone in this, but I strongly prefer to avoid prescriptive solutions whenever possible. It's a totally reasonable proposition to have integrations with different services, but I would want to see that in an add-on package rather than within the base functionality.

Second, I'm not sure I follow the requests that are made in steps 2+3. Are you thinking of using one request of type app/json and a subsequent POST of type multipart, where the latter holds the files themselves? If so, how do you tie the two requests together on the server, given the unknowns in timing?

At any rate, if it is possible to determine which variables are of the file-type, then that's an even more elegant solution from the user's perspective!

[sandervanhooft]

@jangerhofer You're not alone in this. That's why I prefer @stubailo's first suggestion:

In your mutation arguments, you get a file object

This way the graphql layer remains transparent and flexible.

I.e. this way @stubailo's second suggestion (S3 storage etc.) would be easy to implement / customize using already existing packages.

[HriBB]

If possible, I would prefer to send everything with a single request.

I am trying to understand, what would need to be done, to support this on the apollo client/server, and also how we can support other graphql implementations.

I'm looking at the networkInterface code, and I think it could be possible by using a middleware. If I understand the code correctly, it goes something like this: HTTPFetchNetworkInterface has a public method fetchFromRemoteEndpoint which receives request and options objects from the middleware chain. It then makes a request using whatwg-fetch. By default is uses Content-Type: application/json, but I think we can override it to multipart/form-data and append uploaded files to the body together with the original request. @stubailo can you confirm this? Then there's HTTPBatchedNetworkInterface and addQueryMerging ... and my head starts to hurt :)

Anyway, if we assume that the client makes a single multipart/form-data request with a mutation, variables and all the files, we can then use something like app.use(apolloKoaUpload()) middleware on the server, process the request, put everything in the right place, and pass it to the apollo server integration (Express, Koa, HAPI). Server can then process it just like any other mutation, except this time, there will be a files parameter available on the resolver method. @helfer @nnance what do you guys think? Maybe I'm missing something, but I think that this could work at least for Express and Koa. Not sure about HAPI. Need to do some research for that.

I can start working on PR(s), but I would love to get some feedback from the core devs first.

[helfer]

@HriBB I think that's a pretty reasonable approach. On the server side I would put the files on the context initially, and then try creating a special "file" input type.

On the client, how exactly would the user specify a file upload so it gets appended properly in the network layer?

[HriBB]

@helfer we could check request variables for the presence of File or FileList similar to this implementation. Or we can add a new option files to the mutate function, but then we would have to add that to the core. Not really sure at this point. @stubailo, what do you think?

[HriBB]

I managed to get some work done on this.

CLIENT

Upload middleware will check if any variable is a FileList instance, and will send a FormData if it finds one. I'm using hardcoded key files in the example. Problem is this line, because for the multipart/form-data header to be correctly set, we need to omit Content-Type on the fetch() options. ATM I am using a hacked version of networkInterface.

import { printAST } from 'apollo-client'

function isUpload(request) {
  if (request.variables) {
    for (let key in request.variables) {
      if (request.variables[key] instanceof FileList) {
        return true
      }
    }
  }
  return false
}

export default class UploadMiddleware {
  applyMiddleware(req, next) {
    if (!isUpload(req.request)) return next()

    const body = new FormData()
    const variables = {}

    for (let key in req.request.variables) {
      let v = req.request.variables[key]
      if (v instanceof FileList) {
        Array.from(v).forEach(f => body.append('files', f))
      } else {
        variables[key] = v
      }
    }

    body.append('operationName', req.request.operationName)
    body.append('query', printAST(req.request.query))
    body.append('variables', JSON.stringify(variables))

    req.options.body = body

    next()
  }
}

Use it like any other middleware

import ApolloClient, { createNetworkInterface } from 'apollo-client'
import UploadMiddleware from './UploadMiddleware'

const networkInterface = createNetworkInterface(`http://localhost:4000/graphql`)

networkInterface.use([
  new UploadMiddleware(),
])

Mutation with files, simply pass FileList as a variable.

import React, { Component, PropTypes } from 'react'
import { compose, graphql } from 'react-apollo'
import gql from 'graphql-tag'

class AddImages extends Component {

  static propTypes = {
    gallery: PropTypes.object.isRequired,
  }

  constructor(props) {
    super(props)
    this.files = null
  }

  upload = () => {
    const { gallery, uploadGalleryImages } = this.props
    uploadGalleryImages(gallery.id, this.files)
      .then(({ data }) => {
        console.log('data', data);
      })
      .catch(error => {
        console.log('error', error.message);
      })
  }

  changeFiles = (e) => {
    this.files = e.target.files
  }

  render() {
    return (
      <form>
        <input type={'file'} name={'files'} onChange={this.changeFiles} multiple />
        <button onClick={this.upload}>Upload</button>
      </form>
    )
  }

}

const UPLOAD_GALLERY_IMAGES = gql`
  mutation uploadGalleryImages($id: String!, $files: [UploadedFile!]!) {
    uploadGalleryImages(id: $id, files: $files) {
      id
      slug
      name
    }
  }`

export default compose(
  graphql(UPLOAD_GALLERY_IMAGES, {
    props: ({ ownProps, mutate }) => ({
      uploadGalleryImages: (id, files) => mutate({
        variables: { id, files },
      }),
    }),
  }),
)(AddImages)

SERVER

Upload middleware for apolloKoa(). Will check if request made to /graphql endpoint is multipart, and will process ctx.request.body. In this case I use async-busboy to parse form data.

import asyncBusboy from 'async-busboy'

export default function apolloKoaUpload(options) {

  function isUpload(ctx) {
    return Boolean(
      ctx.path === options.endpointURL &&
      ctx.request.method === 'POST' &&
      ctx.request.is('multipart/*')
    )
  }

  return async function(ctx, next) {
    if (!isUpload(ctx)) return next()
    const { files, fields } = await asyncBusboy(ctx.req)
    const { operationName, query, variables } = fields
    ctx.request.body = {
      operationName,
      query,
      variables: Object.assign(JSON.parse(variables), { files }),
    }
    return next()
  }
}

Use it before apolloKoa()

app.use(apolloKoaUpload({
  endpointURL: '/graphql'
}))

app.use(post('/graphql', apolloKoa({
  schema
})))

app.use(get('/graphiql', graphiqlKoa({
  endpointURL: '/graphql'
})))

Add UploadedFile scalar to schema

scalar UploadedFile

Also add resolver - a simple JSON will do for now ...

const resolveFunctions = {
  UploadedFile: {
    __parseLiteral: parseJSONLiteral,
    __serialize: value => value,
    __parseValue: value => value,
  },
  ...
}

function parseJSONLiteral(ast) {
  console.log('ast', ast);
  switch (ast.kind) {
    case Kind.STRING:
    case Kind.BOOLEAN:
      return ast.value;
    case Kind.INT:
    case Kind.FLOAT:
      return parseFloat(ast.value);
    case Kind.OBJECT: {
      const value = Object.create(null);
      ast.fields.forEach(field => {
        value[field.name.value] = parseJSONLiteral(field.value);
      });

      return value;
    }
    case Kind.LIST:
      return ast.values.map(parseJSONLiteral);
    default:
      return null;
  }
}

So the only thing that's blocking me ATM is the Content-Type header on the fetch() options inside NetworkInterface. @stubailo @helfer what do you think?

[HriBB]

Some update

I think it's actually better to use a custom network interface instead of middleware.
I have created UploadNetworkInterface that extends HTTPFetchNetworkInterface.
Before fetching, it checks if the request contains any uploaded files.
If it does, it uses FormData, otherwise JSON body, and sets appropriate headers.

UploadNetworkInterface.js

import { printAST } from 'apollo-client'
import {
  HTTPFetchNetworkInterface,
  addQueryMerging,
  printRequest,
} from 'apollo-client/networkInterface'

export class UploadNetworkInterface extends HTTPFetchNetworkInterface {

  fetchFromRemoteEndpoint(req) {
    const options = this.isUpload(req)
      ? this.getUploadOptions(req)
      : this.getJSONOptions(req)
    return fetch(this._uri, options);
  }

  isUpload({ request }) {
    if (request.variables) {
      for (let key in request.variables) {
        if (request.variables[key] instanceof FileList) {
          return true
        }
      }
    }
    return false
  }

  getJSONOptions({ request, options }) {
    return Object.assign({}, this._opts, {
      body: JSON.stringify(printRequest(request)),
      method: 'POST',
    }, options, {
      headers: Object.assign({}, {
        Accept: '*/*',
        'Content-Type': 'application/json',
      }, options.headers),
    })
  }

  getUploadOptions({ request, options }) {
    const body = new FormData()
    const variables = {}

    for (let key in request.variables) {
      let v = request.variables[key]
      if (v instanceof FileList) {
        Array.from(v).forEach(f => body.append(key, f))
      } else {
        variables[key] = v
      }
    }

    body.append('operationName', request.operationName)
    body.append('query', printAST(request.query))
    body.append('variables', JSON.stringify(variables))

    return Object.assign({}, this._opts, {
      body,
      method: 'POST',
    }, options, {
      headers: Object.assign({}, {
        Accept: '*/*',
      }, options.headers),
    })
  }

}

export function createNetworkInterface(opts) {
  const { uri } = opts
  return addQueryMerging(new UploadNetworkInterface(uri, opts))
}

You can simply use it like this

import { createNetworkInterface } from './UploadNetworkInterface'

const networkInterface = createNetworkInterface({
  uri: `http://localhost:4000/graphql`
})

And a slight improvement of server middleware, to support variable names

import asyncBusboy from 'async-busboy'

export default function apolloKoaUpload(options) {

  function isUpload(ctx) {
    return Boolean(
      ctx.path === options.endpointURL &&
      ctx.request.method === 'POST' &&
      ctx.request.is('multipart/*')
    )
  }

  return async function(ctx, next) {
    if (!isUpload(ctx)) return next()
    const { files, fields } = await asyncBusboy(ctx.req)
    const { operationName, query } = fields
    const variables = JSON.parse(fields.variables)
    files.forEach(file => {
      if (!variables[file.fieldname]) {
        variables[file.fieldname] = []
      }
      variables[file.fieldname].push(file)
    })
    ctx.request.body = {
      operationName,
      query,
      variables,
    }
    return next()
  }
}

I will try to put this into a repo and also create Express example.

Would love to get some feedback on this.

[HriBB]

@jangerhofer what do you think?

[zimme]

@stubailo

Alternative:

(1-3 from above)
There's a server middleware that pulls files off the body, uploads them to a file storage service, and replaces the variables with a reference to that file on S3 or wherever
In your mutation arguments, you get a reference to a file that has been uploaded to S3 already
Other options?

If I was using s3 or some other file service I would not like to upload anything to my graphql server but rather get a token and have my users directly upload to s3/whatever.

[HriBB]

@zimme you don't need any of this stuff in your case. But you could write a middleware that uploads files to s3/whatever, replaces variables with tokens and pass them to the mutation.

My proposal involves both apollo client and server.