upload

README

graphql-go-upload

This library exposes a middleware for the GraphQL-Go project in order to expose a new Upload scalar type and allow you to send multipart/form-data POST requests containing files and fields data.

Installation

$ dep ensure --add github.com/eko/graphql-go-upload

Add the middleware handler in your GraphQL project

Once the dependency is installed, simply update your GraphQL project code in order to add this middleware:

import (
    "github.com/eko/graphql-go-upload"
)

// ...

h := handler.GraphQL{
    Schema: graphql.MustParseSchema(schema.String(), root, graphql.MaxParallelism(maxParallelism), graphql.MaxDepth(maxDepth)),
    Handler: handler.NewHandler(conf, &m),
}

mux := mux.NewRouter()
mux.Handle("/graphql", upload.Handler(h)) // Add the middleware here (wrap the original handler)

s := &http.Server{
    Addr:    ":8000",
    Handler: mux,
}

You're ready to use the new middleware!

Use the new Upload scalar type

In order to use the new Upload scalar type, you have to declare it in your GraphQL schema and use it in your mutations, this way:

scalar Upload

type Mutation {
    myUploadMutation(file: Upload!, title: String!): Boolean
}

Usage on client side

On a client point of view, requests have to be formed this way:

$ curl http://localhost:8000/graphql \
  -F operations='{ "query": "mutation DoUpload($file: Upload!, $title: String!) { upload(file: $file, title: $title) }", "variables": { "file": null, "title": null } }' \
  -F map='{ "file": ["variables.file"], "title": ["variables.title"] }' \
  -F file=@myfile.txt \
  -F title="My content title"

Documentation

Index

• func Handler(next http.Handler) http.Handler
• type GraphQLUpload
  • func (u *GraphQLUpload) GetReader() (io.Reader, error)
  • func (u GraphQLUpload) ImplementsGraphQLType(name string) bool
  • func (u *GraphQLUpload) UnmarshalGraphQL(input interface{}) error

Functions

func Handler

func Handler(next http.Handler) http.Handler

Handler is the middleware function that retrieves the incoming HTTP request and in case it is a POST and multipart/form-data request, re-maps the field values given in the GraphQL format and saves uploaded files.

Here is how to implement the middleware handler (see upload.Handler use below):

h := handler.GraphQL{
    Schema: graphql.MustParseSchema(schema.String(), root, graphql.MaxParallelism(maxParallelism), graphql.MaxDepth(maxDepth)),
    Handler: handler.NewHandler(conf, &m),
}

mux := mux.NewRouter()
mux.Handle("/graphql", upload.Handler(h))

s := &http.Server{
    Addr:    ":8000",
    Handler: mux,
}

Types

type GraphQLUpload

type GraphQLUpload struct {
	Filename string `json:"filename"`
	MIMEType string `json:"mimetype"`
	Filepath string `json:"filepath"`
}

GraphQLUpload is the struct used for the new "Upload" GraphQL scalar type

It allows you to use the Upload type in your GraphQL schema, this way:

scalar Upload

type Mutation {
  upload(file: Upload!, title: String!, description: String!): Boolean
}

func (*GraphQLUpload) GetReader

func (u *GraphQLUpload) GetReader() (io.Reader, error)

GetReader returns the buffer of the uploaded (and temporary saved) file.

func (GraphQLUpload) ImplementsGraphQLType

func (u GraphQLUpload) ImplementsGraphQLType(name string) bool

ImplementsGraphQLType is implemented to respect the GraphQL-Go Unmarshaler interface. It allows to chose the name of the GraphQL scalar type you want to implement

Reference: https://github.com/graph-gophers/graphql-go/blob/bb9738501bd42a6536227b96068349b814379d6e/internal/exec/packer/packer.go#L319

func (*GraphQLUpload) UnmarshalGraphQL

func (u *GraphQLUpload) UnmarshalGraphQL(input interface{}) error

UnmarshalGraphQL is implemented to respect the GraphQL-Go Unmarshaler interface. It hydrates the GraphQLUpload struct with input data

Reference: https://github.com/graph-gophers/graphql-go/blob/bb9738501bd42a6536227b96068349b814379d6e/internal/exec/packer/packer.go#L319